portable-agent-layer 0.20.0 → 0.22.0

package/README.md

@@ -111,14 +111,15 @@ pal cli install               # all available (default)
 
 | Variable | Description |
 |----------|-------------|
-| `ANTHROPIC_API_KEY` | Required for PAL's hook inference (sentiment analysis, session naming). Uses Haiku for low-cost background calls. |
+| `PAL_ANTHROPIC_API_KEY` | Required for PAL's hook inference (sentiment analysis, session naming). Uses Haiku for low-cost background calls. |
 
 ### Optional
 
 | 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 and web search skill  |
+| `PAL_XAI_API_KEY` | For Grok real-time research skill (X/web search) |
+| `PAL_PERPLEXITY_API_KEY` | For Perplexity deep research skill |
 | `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

@@ -1,89 +1,54 @@
 ---
 name: create-pdf
-description: Generate a structured PDF report from a topic or content using parallel research/writing agents and md-to-pdf. Use when creating a report, generating a PDF, writing a document, or producing a structured multi-section PDF.
-argument-hint: <topic, outline, or content description>
+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
 
-Create professional PDF reports by orchestrating parallel subagents for content generation, writing results as structured markdown files, then converting to PDF via `bunx md-to-pdf`.
+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.
 
-## Workflow
-
-### Phase 1: Plan the Report Structure
-
-Based on the user's request, determine:
-
-1. **Report topic and scope**
-2. **Section breakdown** — identify 5-15 discrete sections/chapters
-3. **Output directory** — ask the user or default to `~/Documents/<kebab-case-topic>/`
-4. **Language** — detect from the user's request or ask
-5. **File naming** — each section: `YYYYMMDD_snake_case_title.md` (use today's date if no specific date applies)
-
-Present the outline to the user for approval before proceeding.
-
-### Phase 2: Parallel Content Generation
-
-Spawn **parallel subagents** to write sections simultaneously. Batch sections across agents — each agent handles 2-4 sections depending on total count.
-
-**Agent spawning rules:**
-- All agent spawns for a batch MUST be in a **single message** for true parallel execution
-- Each agent gets a clear, self-contained prompt with: section title, scope, key points to cover, tone/style, and the output file path
-- Agents write their sections directly as markdown files
-- For research-heavy reports: use `investigative-researcher`, `multi-perspective-researcher`, and `claude-researcher` agent types to get different perspectives
-- For content-heavy reports: use `general-purpose` agents with detailed writing instructions
+## Input
 
-**Prompt template for each agent:**
-```
-Read [any reference files if applicable].
-Write a detailed markdown file at [output path] covering:
-- Section title: [title]
-- Scope: [what to cover]
-- Key points: [specific items to include]
-- Tone: [objective/persuasive/technical/casual]
-- Structure: Use ## for main headings, ### for sub-sections
-- Include sources with full URLs where applicable
-```
+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)
 
-**Batch sizing guide:**
+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.
 
-| Total sections | Agents | Sections per agent |
-|----------------|--------|--------------------|
-| 3-6 | 2-3 | 2 each |
-| 7-12 | 3-4 | 2-3 each |
-| 13+ | 5 | 3-4 each |
-
-### Phase 3: Overview File
+## Workflow
 
-After all agents complete, write a `00_overview.md` file containing:
-- Report title and date
-- Methodology description
-- Table of contents linking to each section
-- Executive summary synthesizing key findings from all sections
+### Step 1: Resolve Input Files
 
-### Phase 4: Combine and Convert to PDF
+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 1: Combine all markdown files into one.**
+### Step 2: Combine with Page Breaks
 
-Concatenate files in order with page break dividers between sections:
+Concatenate all files with page break dividers between them:
 
 ```bash
 cat \
-  00_overview.md \
+  first_file.md \
   <(echo -e '\n\n<div style="page-break-before: always"></div>\n\n---\n\n') \
-  YYYYMMDD_section_one.md \
+  second_file.md \
   <(echo -e '\n\n<div style="page-break-before: always"></div>\n\n---\n\n') \
-  YYYYMMDD_section_two.md \
+  third_file.md \
   ... \
   > /tmp/combined_raw.md
 ```
 
-**Step 2: Add PDF frontmatter.**
+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 > <report_name>.md << 'FRONTMATTER'
+cat > <output_name>.md << 'FRONTMATTER'
 ---
 pdf_options:
   format: A4
@@ -105,38 +70,50 @@ css: |-
 ---
 
 FRONTMATTER
-cat /tmp/combined_raw.md >> <report_name>.md
+cat /tmp/combined_raw.md >> <output_name>.md
 ```
 
-**Step 3: Generate the PDF.**
+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 <report_name>.md
+bunx --bun md-to-pdf <output_name>.md
 ```
 
-**Step 4: Verify.**
+### Step 5: Verify and Report
 
 ```bash
-ls -lh <report_name>.pdf
+ls -lh <output_name>.pdf
 ```
 
 Report the file path and size to the user.
 
-### Phase 5: Translation (Optional)
+## 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`)
 
-If the user requests translation to another language:
+**Batch sizing for translation agents:**
 
-1. Spawn parallel agents (same batching as Phase 2) to translate each markdown file
-2. Translated files get the same name with a `_<lang>` suffix (e.g., `_hu`, `_de`, `_es`)
-3. Keep all markdown formatting, links, and structure identical — only translate text content
-4. Keep source link titles in their original language; translate surrounding descriptive text
-5. Combine and convert the translated files to PDF using the same Phase 4 process with a `_<lang>` suffix on the final filename
+| Files | Agents | Files per agent |
+|-------|--------|-----------------|
+| 1-4   | 1-2    | 2 each          |
+| 5-10  | 3-4    | 2-3 each        |
+| 11+   | 5      | 3-4 each        |
 
 ## Important
 
-- All subagent spawns for a batch MUST be in a **single message** for true parallel execution
-- Do NOT run agents sequentially — that defeats the purpose of parallel generation
-- Each agent writes its own files directly — the orchestrating agent only combines and converts
-- Always verify the final PDF exists and report its size
 - Use `bunx --bun md-to-pdf` (NOT npx) for PDF conversion
-- Individual markdown files are kept alongside the PDF so the user can edit and regenerate
+- 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/fyzz-chat-api/SKILL.md

@@ -4,7 +4,7 @@ description: Query Fyzz Chat conversations and projects via the REST API. Use wh
 argument-hint: <conversations|projects> [options]
 ---
 
-When you need to access the user's Fyzz Chat conversations or projects, use the `fyzz-api` CLI tool. The tool reads the API key from the `FYZZ_API_KEY` environment variable automatically — never attempt to read, print, or reference the API key or the env var directly.
+When you need to access the user's Fyzz Chat conversations or projects, use the `fyzz-api` CLI tool. The tool reads the API key from the `PAL_FYZZ_API_KEY` environment variable automatically — never attempt to read, print, or reference the API key or the env var directly.
 
 ## Available commands
 
@@ -31,8 +31,8 @@ bun ~/.agents/skills/fyzz-chat-api/tools/fyzz-api.ts -- projects
 If the tool reports a missing API key:
 
 1. Ask the user to create one in Fyzz Chat → Settings → API Keys
-2. They should set `FYZZ_API_KEY` in their shell profile or in PAL's `settings.json` env section
-3. Optionally set `FYZZ_BASE_URL` (defaults to `http://localhost:3000`)
+2. They should set `PAL_FYZZ_API_KEY` in their shell profile or in PAL's `settings.json` env section
+3. Optionally set `PAL_FYZZ_BASE_URL` (defaults to `http://localhost:3000`)
 
 ## Guidelines
 

package/assets/skills/fyzz-chat-api/tools/fyzz-api.ts

@@ -2,7 +2,7 @@
 /**
  * Fyzz Chat API — CLI wrapper for programmatic conversation access.
  *
- * Reads the API key from FYZZ_API_KEY env var (never printed to stdout).
+ * Reads the API key from PAL_FYZZ_API_KEY env var (never printed to stdout).
  * Returns JSON responses from the Fyzz Chat REST API.
  *
  * Usage:
@@ -14,9 +14,9 @@
 import { parseArgs } from "node:util";
 
 function loadApiKey(): string {
-  const key = process.env.FYZZ_API_KEY;
+  const key = process.env.PAL_FYZZ_API_KEY;
   if (!key) {
-    console.error("Error: FYZZ_API_KEY environment variable is not set.");
+    console.error("Error: PAL_FYZZ_API_KEY environment variable is not set.");
     console.error("Set it in your shell profile or PAL settings.json env section.");
     process.exit(1);
   }
@@ -25,7 +25,7 @@ function loadApiKey(): string {
 
 async function apiFetch(path: string, params?: Record<string, string>): Promise<unknown> {
   const apiKey = loadApiKey();
-  const baseUrl = process.env.FYZZ_BASE_URL ?? "http://localhost:3000";
+  const baseUrl = process.env.PAL_FYZZ_BASE_URL ?? "http://localhost:3000";
 
   const url = new URL(`/api/v1${path}`, baseUrl);
   if (params) {

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