portable-agent-layer 0.19.0 → 0.21.0

package/README.md

@@ -117,8 +117,8 @@ pal cli install               # all available (default)
 
 | Variable | Description |
 |----------|-------------|
-| `GEMINI_API_KEY` | For YouTube video analysis skill |
-| `XAI_API_KEY` | For Grok real-time research skill (X/web search) |
+| `PAL_GEMINI_API_KEY` | For YouTube video analysis skill |
+| `PAL_XAI_API_KEY` | For Grok real-time research skill (X/web search) |
 | `PAL_HOME` | Override user state directory (default: `~/.pal` or repo root) |
 | `PAL_PKG` | Override package root |
 | `PAL_CLAUDE_DIR` | Override Claude config dir (default: `~/.claude`) |

package/assets/agents/gemini-researcher.md

@@ -0,0 +1,73 @@
+---
+name: gemini-researcher
+description: Deep research with academic rigor — Gemini-grounded search with scholarly focus, query decomposition, multi-source synthesis. Falls back to WebSearch if no API key.
+tools: Bash, WebSearch, WebFetch, Read, Grep, Glob
+model: sonnet
+---
+
+You are a research specialist focused on **depth and academic rigor**.
+
+## Tool Selection
+
+**Always start with Gemini Search.** Use the grounded search tool for your first sub-question:
+```bash
+bun ~/.agents/skills/research/tools/gemini-search.ts -- "<query>"
+```
+
+- If it returns results → **continue using Gemini Search** for remaining queries
+- If it errors about `PAL_GEMINI_API_KEY` → **fall back to WebSearch/WebFetch** for all queries using the fallback methodology below
+
+The tool has a built-in academic system prompt that prioritizes scholarly sources, but you should still craft queries to target academic content:
+- Include author names, paper titles, or venue names when known
+- Use precise technical terminology
+- Add "peer-reviewed", "systematic review", or venue names to narrow results
+
+## Fallback Mode (WebSearch/WebFetch)
+
+When Gemini Search is unavailable, use WebSearch with academic focus:
+
+1. **Decompose** the query into 2-3 sub-questions targeting the core of the topic
+2. **Search** each sub-question using WebSearch — craft queries that target academic sources:
+   - Prefix with `site:arxiv.org`, `site:scholar.google.com`, `site:pubmed.ncbi.nlm.nih.gov` where relevant
+   - Include technical terms, author names, conference/journal names
+   - Add year ranges to find recent work
+3. **Read** the most promising results with WebFetch to extract detail
+4. **Synthesize** findings into a structured analysis
+
+## Guidelines (Both Modes)
+
+- Prioritize peer-reviewed sources over blog posts and summaries
+- Distinguish between established findings, preprints, and speculation
+- Note methodology limitations, sample sizes, and confidence intervals when citing research
+- Include author names, publication year, and venue for all cited work
+- If a claim has no strong source, say so — do not fabricate citations
+- Keep findings concise but substantive
+
+## Output Format
+
+```markdown
+## Findings
+
+[Numbered list of key discoveries, each with a brief explanation and citation]
+
+## Sources
+
+[Verified URLs with one-line descriptions — only include URLs you actually visited or that were returned by grounding]
+
+## Confidence
+
+[High/Medium/Low rating per finding, with brief justification]
+
+## Gaps
+
+[What couldn't be answered or needs further investigation]
+```
+
+## Fallback Footnote (MANDATORY when using WebSearch fallback)
+
+If you fell back to WebSearch because the Gemini API was unavailable, you MUST append this footnote at the very end of your output:
+
+```markdown
+---
+> **Note:** This research used WebSearch fallback instead of Gemini Search. The `PAL_GEMINI_API_KEY` environment variable is not set. To enable Gemini-grounded search, set the key: `export PAL_GEMINI_API_KEY=...` (get one at https://aistudio.google.com/apikey)
+```

package/assets/agents/grok-researcher.md

@@ -33,7 +33,7 @@ The tool outputs findings as markdown with a `## Sources` section listing URLs a
 
 ## Fallback Path — WebSearch
 
-If the grok-search tool fails (missing `XAI_API_KEY` or API error), fall back to WebSearch and WebFetch with a **recency focus**:
+If the grok-search tool fails (missing `PAL_XAI_API_KEY` or API error), fall back to WebSearch and WebFetch with a **recency focus**:
 
 1. **Search** using WebSearch with time-sensitive queries — prepend "2026" or "latest" or "today" to queries
 2. **Prioritize** news sources, social media aggregators, and live blogs
@@ -84,3 +84,12 @@ If the grok-search tool fails (missing `XAI_API_KEY` or API error), fall back to
 
 [What couldn't be confirmed or needs monitoring as the situation develops]
 ```
+
+## Fallback Footnote (MANDATORY when using WebSearch fallback)
+
+If you fell back to WebSearch because the Grok API was unavailable, you MUST append this footnote at the very end of your output:
+
+```markdown
+---
+> **Note:** This research used WebSearch fallback instead of Grok Search. The `PAL_XAI_API_KEY` environment variable is not set. To enable Grok real-time search, set the key: `export PAL_XAI_API_KEY=...` (get one at https://console.x.ai/)
+```

package/assets/agents/perplexity-researcher.md

@@ -0,0 +1,67 @@
+---
+name: perplexity-researcher
+description: Investigative research with verification rigor — Perplexity-grounded search with source cross-referencing, credibility assessment, and evidence chains. Falls back to WebSearch if no API key.
+tools: Bash, WebSearch, WebFetch, Read, Grep, Glob
+model: sonnet
+---
+
+You are a research specialist focused on **investigative rigor and source verification**.
+
+## Tool Selection
+
+**Always start with Perplexity Search.** Use the grounded search tool for your first sub-question:
+```bash
+bun ~/.agents/skills/research/tools/perplexity-search.ts -- "<query>"
+```
+
+- If it returns results → **continue using Perplexity Search** for remaining queries
+- If it errors about `PAL_PERPLEXITY_API_KEY` → **fall back to WebSearch/WebFetch** for all queries using the fallback methodology below, and **set a flag** to include the fallback footnote in your output
+
+## Fallback Mode (WebSearch/WebFetch)
+
+When Perplexity Search is unavailable, use WebSearch with investigative focus:
+
+1. **Search** the topic broadly using WebSearch to map the information landscape
+2. **Verify** key claims by finding 2+ independent sources for each
+3. **Assess** source credibility — check publication date, author expertise, potential bias
+4. **Cross-reference** findings to identify contradictions or unsupported claims
+5. **Report** with clear evidence chains
+
+## Guidelines (Both Modes)
+
+- Every factual claim should have at least 2 independent sources
+- Note when a claim is single-sourced or comes from a potentially biased source
+- Check publication dates — flag stale information
+- Distinguish between verified facts, likely true (single credible source), and unverified claims
+- Include source names, publication dates, and direct quotes when available
+- Flag contradictions between sources
+- If a claim has no strong source, say so — do not fabricate citations
+
+## Output Format
+
+```markdown
+## Findings
+
+[Numbered list of verified findings, each tagged: verified (2+ sources) | ~ likely (1 credible source) | ? unverified]
+
+## Sources
+
+[Verified URLs with one-line descriptions — only include URLs you actually visited or that were returned by Perplexity]
+
+## Confidence
+
+[High/Medium/Low rating per finding, with evidence chain summary]
+
+## Flags
+
+[Contradictions found, stale information, potential bias in sources]
+```
+
+## Fallback Footnote (MANDATORY when using WebSearch fallback)
+
+If you fell back to WebSearch because the Perplexity API was unavailable, you MUST append this footnote at the very end of your output:
+
+```markdown
+---
+> **Note:** This research used WebSearch fallback instead of Perplexity Search. The `PAL_PERPLEXITY_API_KEY` environment variable is not set. To enable Perplexity-grounded search, set the key: `export PAL_PERPLEXITY_API_KEY=pplx-...` (get one at https://www.perplexity.ai/settings/api)
+```

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

@@ -32,4 +32,4 @@ Follow the user's request. Common tasks:
 - For long videos, consider asking a focused question via `--prompt` rather than a full analysis
 - Gemini sees both visuals and audio — mention on-screen content (slides, code, diagrams) when relevant
 - Quote speakers verbatim when the user asks about specific statements
-- If the tool reports a missing API key, tell the user to get one at https://aistudio.google.com/apikey and set `GEMINI_API_KEY` in their shell profile or PAL settings
+- If the tool reports a missing API key, tell the user to get one at https://aistudio.google.com/apikey and set `PAL_GEMINI_API_KEY` in their shell profile or PAL settings

package/assets/skills/analyze-youtube/tools/youtube-analyze.ts

@@ -4,7 +4,7 @@
  * YouTube Analyze — Sends a YouTube URL + prompt to Gemini for video analysis.
  *
  * Gemini can natively process YouTube videos (visual + audio).
- * Requires GEMINI_API_KEY environment variable.
+ * Requires PAL_GEMINI_API_KEY environment variable.
  *
  * Usage:
  *   bun youtube-analyze.ts -- <youtube-url> [--prompt "your question"]
@@ -25,9 +25,9 @@ const DEFAULT_PROMPT = `Analyze this video and provide:
 const MODEL = "gemini-3.1-flash-lite-preview";
 
 function loadApiKey(): string {
-  const key = process.env.GEMINI_API_KEY;
+  const key = process.env.PAL_GEMINI_API_KEY;
   if (!key) {
-    console.error("Error: GEMINI_API_KEY environment variable is not set.");
+    console.error("Error: PAL_GEMINI_API_KEY environment variable is not set.");
     console.error("Get a free key at https://aistudio.google.com/apikey");
     process.exit(1);
   }

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

@@ -0,0 +1,119 @@
+---
+name: create-pdf
+description: Convert markdown files into a styled PDF report using md-to-pdf. Use when creating a PDF from existing markdown files, combining markdown into a report, or converting .md to .pdf.
+argument-hint: <file paths, glob pattern, or directory containing .md files>
+---
+
+## Overview
+
+Combine one or more markdown files into a single styled PDF using `bunx --bun md-to-pdf`. This skill handles concatenation, page breaks, styling, and conversion. It does NOT generate content — use the `research` skill or other content-generation workflows first, then pipe the resulting markdown files into this skill.
+
+## Input
+
+The user provides one of:
+- **Explicit file paths**: `/path/to/file1.md /path/to/file2.md ...`
+- **A glob pattern**: `/path/to/report/*.md`
+- **A directory**: `/path/to/report/` (all `.md` files inside, sorted alphabetically)
+
+If no output filename is specified, derive it from the directory name or first file: `<name>.pdf` in the same directory as the input files.
+
+## Workflow
+
+### Step 1: Resolve Input Files
+
+Determine the list of markdown files and their order:
+- If explicit paths: use as given
+- If glob/directory: list and sort alphabetically (files prefixed with `00_` come first naturally)
+- Confirm the file list and order with the user if more than 5 files
+
+### Step 2: Combine with Page Breaks
+
+Concatenate all files with page break dividers between them:
+
+```bash
+cat \
+  first_file.md \
+  <(echo -e '\n\n<div style="page-break-before: always"></div>\n\n---\n\n') \
+  second_file.md \
+  <(echo -e '\n\n<div style="page-break-before: always"></div>\n\n---\n\n') \
+  third_file.md \
+  ... \
+  > /tmp/combined_raw.md
+```
+
+For many files, generate the cat command dynamically rather than typing each one.
+
+### Step 3: Add PDF Frontmatter
+
+Prepend YAML frontmatter with styling, then append the combined content:
+
+```bash
+cat > <output_name>.md << 'FRONTMATTER'
+---
+pdf_options:
+  format: A4
+  margin: 25mm
+  printBackground: true
+stylesheet: https://cdn.jsdelivr.net/npm/github-markdown-css/github-markdown.css
+body_class: markdown-body
+css: |-
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; font-size: 11px; line-height: 1.6; color: #1a1a1a; }
+  h1 { font-size: 22px; border-bottom: 2px solid #333; padding-bottom: 8px; }
+  h2 { font-size: 17px; }
+  h3 { font-size: 14px; }
+  table { border-collapse: collapse; width: 100%; margin: 12px 0; }
+  th, td { border: 1px solid #ccc; padding: 6px 10px; text-align: left; font-size: 10px; }
+  th { background: #f0f0f0; }
+  blockquote { border-left: 3px solid #666; padding-left: 12px; color: #444; }
+  hr { border: none; border-top: 1px solid #ccc; margin: 20px 0; }
+  a { color: #0366d6; text-decoration: none; }
+---
+
+FRONTMATTER
+cat /tmp/combined_raw.md >> <output_name>.md
+```
+
+The user may request custom styling (font size, margins, colors). Override the defaults above accordingly.
+
+### Step 4: Generate PDF
+
+```bash
+bunx --bun md-to-pdf <output_name>.md
+```
+
+### Step 5: Verify and Report
+
+```bash
+ls -lh <output_name>.pdf
+```
+
+Report the file path and size to the user.
+
+## Translation Variant
+
+If the user asks to translate markdown files and then create a PDF:
+
+1. Spawn **parallel subagents** to translate files — batch 2-4 files per agent, all agents in a **single message**
+2. Each agent reads the source file, translates all text content to the target language, and writes to `<original_name>_<lang>.md`
+3. Rules for translation agents:
+   - Keep all markdown formatting, links, and structure identical
+   - Keep source/link titles in their original language; translate surrounding text
+   - Translate naturally, not word-for-word; use proper domain terminology
+4. After all agents complete, run Steps 2-5 above on the translated files
+5. Output filename gets a `_<lang>` suffix (e.g., `report_hu.pdf`)
+
+**Batch sizing for translation agents:**
+
+| Files | Agents | Files per agent |
+|-------|--------|-----------------|
+| 1-4   | 1-2    | 2 each          |
+| 5-10  | 3-4    | 2-3 each        |
+| 11+   | 5      | 3-4 each        |
+
+## Important
+
+- Use `bunx --bun md-to-pdf` (NOT npx) for PDF conversion
+- This skill only converts — it does not research or generate content
+- Individual markdown files are preserved alongside the PDF for future editing
+- If `md-to-pdf` is not installed, `bunx` will auto-install it on first run
+- Always verify the PDF exists before reporting success

package/assets/skills/research/SKILL.md

@@ -14,16 +14,16 @@ argument-hint: <topic or question>
 
 ## Available Researcher Agents
 
-- **claude-researcher** — academic depth, query decomposition, scholarly synthesis
+- **gemini-researcher** — academic depth via Gemini grounding, query decomposition, scholarly synthesis (falls back to WebSearch if no API key)
 - **multi-perspective-researcher** — breadth, multiple angles, diverse viewpoints
-- **investigative-researcher** — verification rigor, triple-checks, source credibility
+- **perplexity-researcher** — investigative rigor via Perplexity grounding, source cross-referencing, credibility assessment (falls back to WebSearch if no API key)
 - **grok-researcher** — real-time data via Grok/X API, breaking news, social sentiment (falls back to WebSearch with recency focus if no API key)
 
 ## Quick Mode
 
 Spawn **1 subagent** for a focused answer:
 
-- Spawn `claude-researcher` with the full query and context
+- Spawn `gemini-researcher` with the full query and context
 
 Wait for the result, then deliver it directly with light formatting.
 
@@ -31,12 +31,12 @@ Wait for the result, then deliver it directly with light formatting.
 
 Craft **3 different queries** optimized for each researcher's strengths, then spawn all **in parallel (in a single message)**:
 
-- Spawn `claude-researcher` with a query optimized for depth/analysis
+- Spawn `gemini-researcher` with a query optimized for depth/analysis
 - Spawn `multi-perspective-researcher` with a query optimized for breadth/perspectives
 - Spawn `grok-researcher` with a query optimized for real-time data, recent developments, current state
 
 **Query design:**
-- claude-researcher: focus on authoritative sources, technical depth, how/why
+- gemini-researcher: focus on authoritative sources, technical depth, how/why
 - multi-perspective-researcher: focus on different stakeholder views, trade-offs, alternatives
 - grok-researcher: focus on latest news, breaking developments, social sentiment, what's happening right now
 
@@ -44,12 +44,12 @@ Craft **3 different queries** optimized for each researcher's strengths, then sp
 
 Craft **8 queries** (2 per researcher type, each from a different angle), then spawn all **in parallel (in a single message)**:
 
-- Spawn `claude-researcher` — angle 1: core technical depth
-- Spawn `claude-researcher` — angle 2: historical context / evolution
+- Spawn `gemini-researcher` — angle 1: core technical depth
+- Spawn `gemini-researcher` — angle 2: historical context / evolution
 - Spawn `multi-perspective-researcher` — angle 3: stakeholder perspectives
 - Spawn `multi-perspective-researcher` — angle 4: cross-domain connections
-- Spawn `investigative-researcher` — angle 5: verify key claims
-- Spawn `investigative-researcher` — angle 6: find contradictions / counter-evidence
+- Spawn `perplexity-researcher` — angle 5: verify key claims
+- Spawn `perplexity-researcher` — angle 6: find contradictions / counter-evidence
 - Spawn `grok-researcher` — angle 7: real-time developments and breaking news
 - Spawn `grok-researcher` — angle 8: social sentiment, public reaction, trending discourse
 

package/assets/skills/research/tools/gemini-search.ts

@@ -0,0 +1,186 @@
+#!/usr/bin/env bun
+/**
+ * Gemini Search — CLI tool for grounded search via the Gemini API.
+ *
+ * Uses Gemini's built-in Google Search grounding to fetch real-time,
+ * source-cited information. Optimized for academic and scholarly queries.
+ *
+ * Requires PAL_GEMINI_API_KEY environment variable.
+ *
+ * Usage:
+ *   bun gemini-search.ts -- <query> [--max-tokens 4096]
+ *   bun gemini-search.ts -- "recent advances in transformer architectures"
+ *   bun gemini-search.ts -- "CRISPR gene editing clinical trials 2025"
+ */
+
+import { parseArgs } from "node:util";
+
+const API_BASE = "https://generativelanguage.googleapis.com/v1beta";
+const DEFAULT_MODEL = "gemini-3.1-flash-lite-preview";
+
+interface GroundingChunk {
+  web?: { uri: string; title: string };
+}
+
+interface GroundingSupport {
+  segment?: { startIndex: number; endIndex: number; text: string };
+  groundingChunkIndices?: number[];
+}
+
+interface GroundingMetadata {
+  webSearchQueries?: string[];
+  groundingChunks?: GroundingChunk[];
+  groundingSupports?: GroundingSupport[];
+  searchEntryPoint?: { renderedContent: string };
+}
+
+interface ContentPart {
+  text?: string;
+}
+
+interface Candidate {
+  content?: { parts?: ContentPart[]; role?: string };
+  groundingMetadata?: GroundingMetadata;
+}
+
+interface GeminiResponse {
+  candidates?: Candidate[];
+  error?: { message: string; code: number };
+}
+
+function loadApiKey(): string {
+  const key = process.env.PAL_GEMINI_API_KEY;
+  if (!key) {
+    console.error("Error: PAL_GEMINI_API_KEY environment variable is not set.");
+    console.error("Get an API key at https://aistudio.google.com/apikey");
+    process.exit(1);
+  }
+  return key;
+}
+
+const SYSTEM_PROMPT = `You are an academic research assistant. When searching, prioritize:
+- Peer-reviewed papers, preprints (arXiv, bioRxiv, medRxiv)
+- Official documentation and technical specifications
+- University and research institution publications
+- Conference proceedings (NeurIPS, ICML, ACL, CVPR, etc.)
+- Systematic reviews and meta-analyses
+
+Always include: author names, publication year, journal/venue when available.
+Distinguish between peer-reviewed findings and preprints/working papers.
+Note methodology limitations and sample sizes when relevant.
+Be thorough but concise.`;
+
+export async function geminiSearch(query: string, maxTokens: number): Promise<void> {
+  const apiKey = loadApiKey();
+
+  const body = {
+    system_instruction: {
+      parts: [{ text: SYSTEM_PROMPT }],
+    },
+    contents: [
+      {
+        parts: [{ text: query }],
+      },
+    ],
+    tools: [{ google_search: {} }],
+    generationConfig: {
+      maxOutputTokens: maxTokens,
+    },
+  };
+
+  const url = `${API_BASE}/models/${DEFAULT_MODEL}:generateContent?key=${apiKey}`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text().catch(() => "");
+    console.error(`Error: HTTP ${response.status} — ${err.slice(0, 500)}`);
+    process.exit(1);
+  }
+
+  const data = (await response.json()) as GeminiResponse;
+
+  if (data.error) {
+    console.error(`Error: ${data.error.message}`);
+    process.exit(1);
+  }
+
+  if (!data.candidates || data.candidates.length === 0) {
+    console.error("Error: No candidates in Gemini response.");
+    process.exit(1);
+  }
+
+  const candidate = data.candidates[0];
+
+  // Extract text
+  const textParts: string[] = [];
+  if (candidate.content?.parts) {
+    for (const part of candidate.content.parts) {
+      if (part.text) textParts.push(part.text);
+    }
+  }
+
+  if (textParts.length === 0) {
+    console.error("Error: No text content in Gemini response.");
+    process.exit(1);
+  }
+
+  console.log(textParts.join("\n\n"));
+
+  // Extract grounding metadata
+  const meta = candidate.groundingMetadata;
+  if (meta) {
+    if (meta.webSearchQueries && meta.webSearchQueries.length > 0) {
+      console.log("\n---\n## Search Queries Used\n");
+      for (const q of meta.webSearchQueries) {
+        console.log(`- ${q}`);
+      }
+    }
+
+    if (meta.groundingChunks && meta.groundingChunks.length > 0) {
+      console.log("\n---\n## Sources\n");
+      for (const chunk of meta.groundingChunks) {
+        if (chunk.web) {
+          console.log(`- [${chunk.web.title}](${chunk.web.uri})`);
+        }
+      }
+    }
+  }
+}
+
+async function run() {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      "max-tokens": { type: "string", short: "m", default: "4096" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help || positionals.length === 0) {
+    console.log(`Gemini Search — grounded academic search via Gemini API
+
+Usage:
+  bun gemini-search.ts -- <query> [options]
+
+Options:
+  --max-tokens, -m <n>       Max response tokens (default: 4096)
+  --help, -h                 Show this help
+
+Examples:
+  bun gemini-search.ts -- "transformer architecture advances 2025"
+  bun gemini-search.ts -- "CRISPR clinical trials"`);
+    process.exit(0);
+  }
+
+  const query = positionals.join(" ");
+  const maxTokens = Number.parseInt(values["max-tokens"] ?? "4096", 10);
+
+  await geminiSearch(query, maxTokens);
+}
+
+if (import.meta.main) run();

package/assets/skills/research/tools/grok-search.ts

@@ -5,7 +5,7 @@
  * Uses the Grok Responses API with web_search and x_search tools
  * to fetch real-time information from the web and X (Twitter).
  *
- * Requires XAI_API_KEY environment variable.
+ * Requires PAL_XAI_API_KEY environment variable.
  *
  * Usage:
  *   bun grok-search.ts -- <query> [--sources web,x] [--max-tokens 2048]
@@ -45,9 +45,9 @@ interface GrokResponse {
 }
 
 function loadApiKey(): string {
-  const key = process.env.XAI_API_KEY;
+  const key = process.env.PAL_XAI_API_KEY;
   if (!key) {
-    console.error("Error: XAI_API_KEY environment variable is not set.");
+    console.error("Error: PAL_XAI_API_KEY environment variable is not set.");
     console.error("Get an API key at https://console.x.ai/");
     process.exit(1);
   }

package/assets/skills/research/tools/perplexity-search.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env bun
+/**
+ * Perplexity Search — CLI tool for investigative search via the Perplexity Sonar API.
+ *
+ * Uses Perplexity's Sonar model with built-in web search to fetch
+ * source-cited, verified information. Optimized for investigative queries
+ * requiring cross-referenced, credible sources.
+ *
+ * Requires PAL_PERPLEXITY_API_KEY environment variable.
+ *
+ * Usage:
+ *   bun perplexity-search.ts -- <query> [--max-tokens 4096]
+ *   bun perplexity-search.ts -- "corruption allegations against company X"
+ *   bun perplexity-search.ts -- "timeline of event Y with sources"
+ */
+
+import { parseArgs } from "node:util";
+
+const API_BASE = "https://api.perplexity.ai";
+const DEFAULT_MODEL = "sonar-pro";
+
+interface Choice {
+  message?: {
+    role: string;
+    content: string;
+  };
+}
+
+interface PerplexityResponse {
+  choices?: Choice[];
+  citations?: string[];
+  error?: { message: string; code?: number };
+}
+
+function loadApiKey(): string {
+  const key = process.env.PAL_PERPLEXITY_API_KEY;
+  if (!key) {
+    console.error(
+      "Error: PAL_PERPLEXITY_API_KEY environment variable is not set.\n" +
+        "The Perplexity API could not be reached. The researcher agent should fall back to WebSearch.\n" +
+        "To enable Perplexity search, get an API key at https://www.perplexity.ai/settings/api\n" +
+        "and set it: export PAL_PERPLEXITY_API_KEY=pplx-..."
+    );
+    process.exit(1);
+  }
+  return key;
+}
+
+const SYSTEM_PROMPT = `You are an investigative research assistant. When searching, prioritize:
+- Cross-referenced facts verified by 2+ independent sources
+- Primary sources: court filings, official reports, government records, regulatory filings
+- Credible journalism: established outlets with editorial standards
+- Source credibility assessment: note publication reputation, potential bias, date of publication
+- Evidence chains: connect claims to their original sources
+
+Always include: source names, publication dates, and direct quotes when available.
+Distinguish between confirmed facts, single-source claims, and unverified allegations.
+Flag contradictions between sources.
+Be thorough but concise.`;
+
+export async function perplexitySearch(query: string, maxTokens: number): Promise<void> {
+  const apiKey = loadApiKey();
+
+  const body = {
+    model: DEFAULT_MODEL,
+    messages: [
+      { role: "system", content: SYSTEM_PROMPT },
+      { role: "user", content: query },
+    ],
+    max_tokens: maxTokens,
+    return_citations: true,
+    search_recency_filter: "week",
+  };
+
+  const response = await fetch(`${API_BASE}/chat/completions`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const err = await response.text().catch(() => "");
+    console.error(`Error: HTTP ${response.status} — ${err.slice(0, 500)}`);
+    process.exit(1);
+  }
+
+  const data = (await response.json()) as PerplexityResponse;
+
+  if (data.error) {
+    console.error(`Error: ${data.error.message}`);
+    process.exit(1);
+  }
+
+  if (!data.choices || data.choices.length === 0) {
+    console.error("Error: No choices in Perplexity response.");
+    process.exit(1);
+  }
+
+  const content = data.choices[0].message?.content;
+  if (!content) {
+    console.error("Error: No text content in Perplexity response.");
+    process.exit(1);
+  }
+
+  console.log(content);
+
+  // Extract citations
+  if (data.citations && data.citations.length > 0) {
+    console.log("\n---\n## Sources\n");
+    for (let i = 0; i < data.citations.length; i++) {
+      console.log(`- [${i + 1}] ${data.citations[i]}`);
+    }
+  }
+}
+
+async function run() {
+  const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: {
+      "max-tokens": { type: "string", short: "m", default: "4096" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+
+  if (values.help || positionals.length === 0) {
+    console.log(`Perplexity Search — investigative search via Perplexity Sonar API
+
+Usage:
+  bun perplexity-search.ts -- <query> [options]
+
+Options:
+  --max-tokens, -m <n>       Max response tokens (default: 4096)
+  --help, -h                 Show this help
+
+Examples:
+  bun perplexity-search.ts -- "corruption allegations timeline"
+  bun perplexity-search.ts -- "regulatory actions against company X"`);
+    process.exit(0);
+  }
+
+  const query = positionals.join(" ");
+  const maxTokens = Number.parseInt(values["max-tokens"] ?? "4096", 10);
+
+  await perplexitySearch(query, maxTokens);
+}
+
+if (import.meta.main) run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -380,9 +380,9 @@ function doctor(silent = false): DoctorResult {
     process.env.ANTHROPIC_API_KEY
       ? ok("ANTHROPIC_API_KEY is set")
       : fail("ANTHROPIC_API_KEY — not set (hooks need it for inference)");
-    process.env.GEMINI_API_KEY
-      ? ok("GEMINI_API_KEY is set")
-      : warn("GEMINI_API_KEY — not set (optional, for YouTube analysis)");
+    process.env.PAL_GEMINI_API_KEY
+      ? ok("PAL_GEMINI_API_KEY is set")
+      : warn("PAL_GEMINI_API_KEY — not set (optional, for YouTube analysis)");
 
     // Hook health from debug.log
     const hookHealth = checkHookHealth(home);
@@ -443,6 +443,18 @@ async function init(args: string[]) {
 }
 
 async function install(targets: { claude: boolean; opencode: boolean; cursor: boolean }) {
+  // Ensure dependencies are installed
+  const pkg = palPkg();
+  log.info("Installing dependencies...");
+  const deps = spawnSync("bun", ["install", "--frozen-lockfile"], {
+    cwd: pkg,
+    stdio: "inherit",
+    shell: true,
+  });
+  if (deps.status !== 0) {
+    log.warn("bun install failed — continuing anyway, but hooks may not work");
+  }
+
   // Scaffold TELOS + PAL settings, then prompt for missing identity
   const { scaffoldTelos, scaffoldPalSettings } = await import("../targets/lib");
   const { promptIdentity } = await import("./setup-identity");

package/src/hooks/handlers/work-learning.ts

@@ -19,6 +19,7 @@ import {
   extractLastUser,
   parseMessages,
 } from "../lib/transcript";
+import { appendProjectHistory } from "../lib/work-tracking";
 
 function slugify(text: string): string {
   return text
@@ -183,5 +184,13 @@ export async function captureWorkLearning(
   const filepath = resolve(dir, filename);
   writeFileSync(filepath, content, "utf-8");
 
+  // Append to per-project history (agent-agnostic recall)
+  appendProjectHistory(process.cwd(), {
+    date: new Date().toISOString().slice(0, 10),
+    title,
+    summary,
+    insights,
+  });
+
   if (sessionId) markCaptured(sessionId, filepath, messages.length);
 }

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

@@ -7,6 +7,7 @@
  */
 
 import {
+  copyFileSync,
   existsSync,
   lstatSync,
   readdirSync,
@@ -48,7 +49,7 @@ function latestMtime(...filePaths: string[]): number {
   return latest;
 }
 
-/** Create or verify a symlink pointing to AGENTS.md */
+/** Create or verify a symlink pointing to AGENTS.md (falls back to copy on Windows EPERM) */
 function ensureOneSymlink(linkPath: string, targetPath: string): void {
   try {
     const stat = lstatSync(linkPath);
@@ -58,8 +59,16 @@ function ensureOneSymlink(linkPath: string, targetPath: string): void {
     // doesn't exist — create it
   }
   ensureDir(dirname(linkPath));
-  const relTarget = relative(dirname(linkPath), targetPath).replaceAll("\\", "/");
-  symlinkSync(relTarget, linkPath);
+  try {
+    const relTarget = relative(dirname(linkPath), targetPath).replaceAll("\\", "/");
+    symlinkSync(relTarget, linkPath);
+  } catch (e: unknown) {
+    if ((e as NodeJS.ErrnoException).code === "EPERM") {
+      copyFileSync(targetPath, linkPath);
+    } else {
+      throw e;
+    }
+  }
 }
 
 /** Ensure all agent symlinks point to the canonical AGENTS.md */
@@ -156,9 +165,12 @@ export function buildClaudeMd(): string {
 /** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */
 export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
-  ensureSymlinks();
-  if (!needsRebuild()) return false;
+  if (!needsRebuild()) {
+    ensureSymlinks();
+    return false;
+  }
   ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");
+  ensureSymlinks();
   return true;
 }

package/src/hooks/lib/context.ts

@@ -17,6 +17,7 @@ import { computeSignalTrends, formatTrends } from "./signal-trends";
 import { readFramePrinciples } from "./wisdom";
 import {
   activeProjects,
+  readProjectHistory,
   readSessions,
   recentSessions,
   staleProjects,
@@ -240,25 +241,15 @@ export function loadLearningDigest(): string {
     const entries = readLearnings(paths.sessionLearning(), 10);
     if (entries.length === 0) return "";
 
-    const thisProject = entries.filter((e) => e.cwd === cwd).slice(0, 4);
-    const other = entries.filter((e) => e.cwd !== cwd).slice(0, 3);
+    // This-project learnings are now in loadProjectHistoryContext(); only show cross-project here
+    const other = entries.filter((e) => e.cwd !== cwd).slice(0, 5);
 
-    if (thisProject.length === 0 && other.length === 0) return "";
+    if (other.length === 0) return "";
 
     const lines: string[] = [];
 
-    if (thisProject.length > 0) {
-      lines.push("## This Project — Recent Sessions");
-      for (const e of thisProject) {
-        lines.push(`- **${e.title}**`);
-        if (e.insights) lines.push(`  ${e.insights.split("\n")[0].slice(0, 150)}`);
-      }
-    }
-
-    if (other.length > 0) {
-      lines.push(thisProject.length > 0 ? "" : "", "## Other Recent Learnings");
-      for (const e of other) lines.push(`- ${e.title}`);
-    }
+    lines.push("## Other Recent Learnings");
+    for (const e of other) lines.push(`- ${e.title}`);
 
     return lines.join("\n");
   } catch {
@@ -346,6 +337,25 @@ export function loadSignalTrends(): string {
   }
 }
 
+/** Load per-project session history for the current working directory */
+export function loadProjectHistoryContext(): string {
+  try {
+    const cwd = process.cwd();
+    const entries = readProjectHistory(cwd, 15);
+    if (entries.length === 0) return "";
+
+    const lines: string[] = ["## This Project — Session History"];
+    for (const e of entries) {
+      lines.push(`- **${e.title}** (${e.date})`);
+      if (e.summary) lines.push(`  ${e.summary.split("\n")[0].slice(0, 150)}`);
+    }
+
+    return lines.join("\n");
+  } catch {
+    return "";
+  }
+}
+
 /** Load recent relationship notes (today + yesterday) */
 export function loadRelationshipContext(): string {
   try {
@@ -373,6 +383,9 @@ export function buildSystemReminder(): string {
     ? loadRelationshipContext()
     : "";
   const digest = isEnabled(settings, "learningDigest") ? loadLearningDigest() : "";
+  const projectHistory = isEnabled(settings, "projectHistory")
+    ? loadProjectHistoryContext()
+    : "";
   const trends = isEnabled(settings, "signalTrends") ? loadSignalTrends() : "";
   const failures = isEnabled(settings, "failurePatterns") ? loadFailurePatterns() : "";
   const synthesis = isEnabled(settings, "synthesis")
@@ -384,6 +397,7 @@ export function buildSystemReminder(): string {
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);
   if (relationship) parts.push(relationship);
+  if (projectHistory) parts.push(projectHistory);
   if (digest) parts.push(digest);
   if (synthesis) parts.push(synthesis);
   if (trends) parts.push(trends);

package/src/hooks/lib/export.ts

@@ -15,7 +15,8 @@ const EXPORT_DIRS = ["telos", "memory"];
 const SKIP_PATTERNS = ["memory/downloads"];
 
 function shouldSkip(relPath: string): boolean {
-  return SKIP_PATTERNS.some((p) => relPath.startsWith(p));
+  const normalized = relPath.replaceAll("\\", "/");
+  return SKIP_PATTERNS.some((p) => normalized.startsWith(p));
 }
 
 /** Recursively collect all files under a directory, returning paths relative to root. */
@@ -32,7 +33,7 @@ function walkDir(dir: string, root: string): string[] {
     if (entry.isDirectory()) {
       files.push(...walkDir(fullPath, root));
     } else if (entry.isFile()) {
-      files.push(relPath);
+      files.push(relPath.replaceAll("\\", "/"));
     }
   }
   return files;

package/src/hooks/lib/paths.ts

@@ -57,6 +57,7 @@ export const paths = {
   relationship: () => ensureDir(home("memory", "relationship")),
   entities: () => ensureDir(home("memory", "entities")),
   failures: () => ensureDir(home("memory", "learning", "failures")),
+  projectHistory: () => ensureDir(home("memory", "projects")),
   sessionLearning: () => ensureDir(home("memory", "learning", "session")),
   synthesis: () => ensureDir(home("memory", "learning", "synthesis")),
   backups: () => ensureDir(home("backups")),

package/src/hooks/lib/readme-sync.ts

@@ -67,12 +67,12 @@ function extractEnvVars(): string[] {
     }
   }
 
-  // GEMINI_API_KEY from youtube-analyze.ts
+  // PAL_GEMINI_API_KEY from youtube-analyze.ts
   const youtubeFile = resolve(pkg, "src", "tools", "youtube-analyze.ts");
   if (existsSync(youtubeFile)) {
     const content = readFileSync(youtubeFile, "utf-8");
-    if (content.includes("GEMINI_API_KEY")) {
-      vars.add("GEMINI_API_KEY");
+    if (content.includes("PAL_GEMINI_API_KEY")) {
+      vars.add("PAL_GEMINI_API_KEY");
     }
   }
 

package/src/hooks/lib/security.ts

@@ -44,6 +44,7 @@ export const HOOK_MANAGED_DIRS = [
   "memory/learning/synthesis",
   "memory/relationship",
   "memory/wisdom/state",
+  "memory/projects",
   ".agents/PAL",
 ];
 

package/src/hooks/lib/work-tracking.ts

@@ -3,7 +3,7 @@
  * Used by both Claude Code (StopOrchestrator) and opencode (plugin).
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { ensureDir, paths } from "./paths";
 import { now } from "./time";
@@ -143,6 +143,43 @@ export function extractHandoff(lastAssistant: string): string {
   return cleaned;
 }
 
+// ── Per-Project History ──────────────────────────────────────────
+
+export interface ProjectHistoryEntry {
+  date: string;
+  title: string;
+  summary: string;
+  insights: string;
+}
+
+/** Convert a cwd path to a filesystem-safe slug (last directory segment) */
+export function cwdToSlug(cwd: string): string {
+  const normalized = cwd.replace(/\\/g, "/").replace(/\/+$/, "");
+  return normalized.split("/").pop() || "unknown";
+}
+
+/** Append a learning entry to the project's history.jsonl */
+export function appendProjectHistory(cwd: string, entry: ProjectHistoryEntry): void {
+  const slug = cwdToSlug(cwd);
+  const dir = ensureDir(resolve(paths.projectHistory(), slug));
+  const historyPath = resolve(dir, "history.jsonl");
+  const line = `${JSON.stringify(entry)}\n`;
+  appendFileSync(historyPath, line, "utf-8");
+}
+
+/** Read the project history for a given cwd */
+export function readProjectHistory(cwd: string, limit = 15): ProjectHistoryEntry[] {
+  const slug = cwdToSlug(cwd);
+  const historyPath = resolve(paths.projectHistory(), slug, "history.jsonl");
+  if (!existsSync(historyPath)) return [];
+  try {
+    const lines = readFileSync(historyPath, "utf-8").trim().split("\n").filter(Boolean);
+    return lines.slice(-limit).map((line) => JSON.parse(line) as ProjectHistoryEntry);
+  } catch {
+    return [];
+  }
+}
+
 // ── Persistent Projects ──────────────────────────────────────────
 
 export interface Project {

package/src/tools/agent/wisdom-frame.ts

@@ -167,8 +167,6 @@ ${type === "anti-pattern" ? `### ${observation}\n- **Severity:** Medium\n- **Fre
         `- ${date()}: Principle candidate — ${observation}`
       );
       break;
-
-    case "evolution":
     default:
       content = appendToSection(content, "## Evolution Log", evolutionEntry);
       break;

package/assets/agents/claude-researcher.md

@@ -1,43 +0,0 @@
----
-name: claude-researcher
-description: Deep research with academic rigor — query decomposition, multi-source synthesis, scholarly depth. Use for research tasks requiring thorough analysis.
-tools: WebSearch, WebFetch, Read, Grep, Glob
-model: sonnet
----
-
-You are a research specialist focused on **depth and academic rigor**.
-
-## Methodology
-
-1. **Decompose** the query into 2-3 sub-questions that target the core of the topic
-2. **Search** each sub-question using WebSearch — prioritize authoritative sources (papers, docs, official sites)
-3. **Read** the most promising results with WebFetch to extract detail
-4. **Synthesize** findings into a structured analysis
-
-## Guidelines
-
-- Prioritize primary sources over summaries
-- Distinguish between established facts, expert consensus, and speculation
-- Note methodology limitations when citing research
-- If a claim has no strong source, say so — do not fabricate citations
-- Keep findings concise but substantive
-
-## Output Format
-
-```markdown
-## Findings
-
-[Numbered list of key discoveries, each with a brief explanation]
-
-## Sources
-
-[Verified URLs with one-line descriptions — only include URLs you actually visited]
-
-## Confidence
-
-[High/Medium/Low rating per finding, with brief justification]
-
-## Gaps
-
-[What couldn't be answered or needs further investigation]
-```

package/assets/agents/investigative-researcher.md

@@ -1,44 +0,0 @@
----
-name: investigative-researcher
-description: Investigative research with verification rigor — triple-checks sources, cross-references claims, assesses credibility. Use for research requiring high factual confidence.
-tools: WebSearch, WebFetch, Read, Grep, Glob
-model: sonnet
----
-
-You are a research specialist focused on **verification and investigative rigor**.
-
-## Methodology
-
-1. **Search** the topic broadly using WebSearch to map the information landscape
-2. **Verify** key claims by finding 2+ independent sources for each
-3. **Assess** source credibility — check publication date, author expertise, potential bias
-4. **Cross-reference** findings to identify contradictions or unsupported claims
-5. **Report** with clear evidence chains
-
-## Guidelines
-
-- Every factual claim should have at least 2 independent sources
-- Note when a claim is single-sourced or comes from a potentially biased source
-- Check publication dates — flag stale information
-- Distinguish between verified facts, likely true (single credible source), and unverified claims
-- If a claim has no strong source, say so — do not fabricate citations
-
-## Output Format
-
-```markdown
-## Findings
-
-[Numbered list of verified findings, each tagged: ✓ verified (2+ sources) | ~ likely (1 credible source) | ? unverified]
-
-## Sources
-
-[Verified URLs with one-line descriptions — only include URLs you actually visited]
-
-## Confidence
-
-[High/Medium/Low rating per finding, with evidence chain summary]
-
-## Flags
-
-[Contradictions found, stale information, potential bias in sources]
-```