portable-agent-layer 0.10.0 → 0.12.0

package/assets/skills/{analyze-pdf.md → analyze-pdf/SKILL.md}

@@ -1,15 +1,16 @@
 ---
 name: analyze-pdf
-description: Download and analyze PDF files from URLs or local paths — extract text, answer questions, summarize content
+description: Download and analyze PDF files from URLs or local paths — extract text, answer questions, summarize content. Use when analyzing, reading, or extracting information from a PDF.
+argument-hint: <URL or file path>
 ---
 
 When the user asks to analyze, read, or extract information from a PDF:
 
 ## How to get the PDF
 
-- **URL**: Use the `ai:pdf-download` CLI tool to download and archive the PDF:
+- **URL**: Use the `pdf-download` CLI tool to download and archive the PDF:
   ```bash
-  bun run ai:pdf-download -- <url> [--filename <name.pdf>]
+  bun ~/.agents/skills/analyze-pdf/tools/pdf-download.ts -- <url> [--filename <name.pdf>]
   ```
   The tool downloads the file, saves it to `memory/downloads/{YYYY}/{MM}/{DD}/{filename}.pdf`, and returns JSON with the saved `path`.
 
@@ -33,7 +34,6 @@ Follow the user's request. Common tasks:
 
 ## Guidelines
 
-- Always run the tool from the PAL directory (the `ai:pdf-download` script is registered there)
 - For large PDFs, read specific page ranges rather than the entire document
 - Preserve the original structure (headings, lists, tables) when relevant
 - Quote verbatim when the user asks about specific content

package/{src → assets/skills/analyze-pdf}/tools/pdf-download.ts

@@ -6,7 +6,7 @@
  * Saves to: {PAL_ROOT}/memory/downloads/{YYYY}/{MM}/{DD}/{filename}.pdf
  *
  * Usage:
- *   bun run ai:pdf-download -- <url> [--filename <name.pdf>]
+ *   bun pdf-download.ts -- <url> [--filename <name.pdf>]
  *
  * Returns JSON with the saved file path for downstream reading.
  */
@@ -14,7 +14,7 @@
 import { mkdir } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { parseArgs } from "node:util";
-import { palHome } from "../hooks/lib/paths";
+import { palHome } from "../../../../src/hooks/lib/paths";
 
 const DOWNLOADS_DIR = join(palHome(), "memory", "downloads");
 
@@ -45,7 +45,7 @@ async function main() {
 
   const url = positionals[0];
   if (!url) {
-    console.error("Usage: bun run ai:pdf-download -- <url> [--filename <name.pdf>]");
+    console.error("Usage: bun pdf-download.ts -- <url> [--filename <name.pdf>]");
     process.exit(1);
   }
 

package/assets/skills/{analyze-youtube.md → analyze-youtube/SKILL.md}

@@ -1,16 +1,17 @@
 ---
 name: analyze-youtube
-description: Analyze YouTube videos using Gemini's native video understanding — summarize, extract insights, answer questions
+description: Analyze YouTube videos using Gemini's native video understanding — summarize, extract insights, answer questions. Use when analyzing, summarizing, or extracting information from a YouTube video.
+argument-hint: <YouTube URL>
 ---
 
 When the user asks to analyze, summarize, or extract information from a YouTube video:
 
 ## How to analyze
 
-Use the `ai:youtube-analyze` CLI tool. It sends the video to Gemini, which processes both visual and audio content natively.
+Use the `youtube-analyze` CLI tool. It sends the video to Gemini, which processes both visual and audio content natively.
 
 ```bash
-bun run ai:youtube-analyze -- <youtube-url> [--prompt "your question"]
+bun ~/.agents/skills/analyze-youtube/tools/youtube-analyze.ts -- <youtube-url> [--prompt "your question"]
 ```
 
 - Without `--prompt`, it returns a structured summary with key insights, topics, people, and quotes.
@@ -28,7 +29,6 @@ Follow the user's request. Common tasks:
 
 ## Guidelines
 
-- Always run the tool from the PAL directory (the `ai:youtube-analyze` script is registered there)
 - 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

package/{src → assets/skills/analyze-youtube}/tools/youtube-analyze.ts

@@ -7,7 +7,7 @@
  * Requires GEMINI_API_KEY environment variable.
  *
  * Usage:
- *   bun run ai:youtube-analyze -- <youtube-url> [--prompt "your question"]
+ *   bun youtube-analyze.ts -- <youtube-url> [--prompt "your question"]
  *
  * Default prompt extracts a structured summary with key insights.
  */
@@ -45,7 +45,7 @@ async function main() {
   const url = positionals[0];
   if (!url) {
     console.error(
-      'Usage: bun run ai:youtube-analyze -- <youtube-url> [--prompt "your question"]'
+      'Usage: bun youtube-analyze.ts -- <youtube-url> [--prompt "your question"]'
     );
     process.exit(1);
   }

package/assets/skills/{council.md → council/SKILL.md}

@@ -1,9 +1,10 @@
 ---
 name: council
-description: Multi-perspective parallel debate on a decision — 3-5 independent perspectives argue in parallel, then synthesize into a verdict
+description: Multi-perspective parallel debate on a decision — 3-5 independent perspectives argue in parallel, then synthesize into a verdict. Use when debating, weighing options, or needing multiple viewpoints on a question.
+argument-hint: <question or decision>
 ---
 
-When the user invokes /council <question or decision>:
+Debate $ARGUMENTS from multiple perspectives:
 
 ## Step 1: Define Perspectives
 

package/assets/skills/{create-skill.md → create-skill/SKILL.md}

@@ -1,6 +1,7 @@
 ---
 name: create-skill
-description: Scaffold a new PAL skill from a description
+description: Scaffold a new PAL skill from a description. Use when creating a new skill, adding a capability, or building a custom command.
+argument-hint: <skill description>
 ---
 
 When the user invokes /create-skill <name> <description>:

package/assets/skills/{extract-entities.md → extract-entities/SKILL.md}

@@ -1,9 +1,10 @@
 ---
 name: extract-entities
-description: Extract people and companies from content (articles, videos, URLs, pasted text)
+description: Extract people and companies from content (articles, videos, URLs, pasted text). Use when identifying who and what organizations are mentioned in content.
+argument-hint: <content, URL, or pasted text>
 ---
 
-When the user invokes /extract-entities <content, URL, or pasted text>:
+Extract people and companies from $ARGUMENTS:
 
 1. Read/fetch the content
 2. Extract ALL people and companies mentioned
@@ -52,12 +53,10 @@ Return structured JSON:
 
 ## Persistence
 
-Always run the tool from the PAL directory (the `ai:entity-save` script is registered there).
-
 After displaying results, ask the user if they want to save. When saving, pipe the JSON output through the entity-save tool which handles deduplication automatically:
 
 ```bash
-echo '<the JSON output>' | bun run ai:entity-save -- --source "<URL or content origin>"
+echo '<the JSON output>' | bun ~/.agents/skills/extract-entities/tools/entity-save.ts -- --source "<URL or content origin>"
 ```
 
 The tool deduplicates against the entity index (`memory/entities/entity-index.json`), assigns stable UUIDs, tracks occurrences, and reports what was new vs existing.

package/{src → assets/skills/extract-entities}/tools/entity-save.ts

@@ -6,13 +6,13 @@
  * deduplicates against the entity index, and saves.
  *
  * Usage:
- *   echo '{"people":[...],"companies":[...]}' | bun run ai:entity-save -- --source "https://example.com"
- *   bun run ai:entity-save -- --file /path/to/extracted.json --source "https://example.com"
+ *   echo '{"people":[...],"companies":[...]}' | bun entity-save.ts -- --source "https://example.com"
+ *   bun entity-save.ts -- --file /path/to/extracted.json --source "https://example.com"
  */
 
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { loadEntityIndex, processEntities } from "../hooks/lib/entities";
+import { loadEntityIndex, processEntities } from "../../../../src/hooks/lib/entities";
 
 const { values } = parseArgs({
   args: Bun.argv.slice(2),

package/assets/skills/{extract-wisdom.md → extract-wisdom/SKILL.md}

@@ -1,9 +1,10 @@
 ---
 name: extract-wisdom
-description: Extract structured insights from content (articles, videos, podcasts)
+description: Extract structured insights from content (articles, videos, podcasts). Use when extracting wisdom, key takeaways, or structured insights from any content.
+argument-hint: <content or URL>
 ---
 
-When the user invokes /extract-wisdom <content or URL>:
+Extract structured insights from $ARGUMENTS:
 
 1. Read/fetch the content
 2. Extract:

package/assets/skills/{first-principles.md → first-principles/SKILL.md}

@@ -1,9 +1,10 @@
 ---
 name: first-principles
-description: Break down a problem to its fundamental constraints and build up a solution
+description: Break down a problem to its fundamental constraints and build up a solution. Use when decomposing complexity, challenging assumptions, or finding root causes.
+argument-hint: <problem>
 ---
 
-When the user invokes /first-principles <problem>:
+Break down $ARGUMENTS to fundamentals:
 
 1. **State the problem** clearly in one sentence
 2. **Identify assumptions** — what are we taking for granted?

package/assets/skills/{fyzz-chat-api.md → fyzz-chat-api/SKILL.md}

@@ -1,28 +1,29 @@
 ---
 name: fyzz-chat-api
-description: Query Fyzz Chat conversations and projects via the REST API (API key is handled securely by the CLI tool)
+description: Query Fyzz Chat conversations and projects via the REST API. Use when looking up conversations, searching chat history, or listing projects in Fyzz Chat.
+argument-hint: <conversations|projects> [options]
 ---
 
-When you need to access the user's Fyzz Chat conversations or projects, use the `ai: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 `FYZZ_API_KEY` environment variable automatically — never attempt to read, print, or reference the API key or the env var directly.
 
 ## Available commands
 
 ### List conversations
 
 ```bash
-bun run ai:fyzz-api -- conversations [--limit 20] [--search "query"] [--project-id <id>] [--cursor <cursor>]
+bun ~/.agents/skills/fyzz-chat-api/tools/fyzz-api.ts -- conversations [--limit 20] [--search "query"] [--project-id <id>] [--cursor <cursor>]
 ```
 
 ### Get a single conversation with messages
 
 ```bash
-bun run ai:fyzz-api -- conversations <conversation-id>
+bun ~/.agents/skills/fyzz-chat-api/tools/fyzz-api.ts -- conversations <conversation-id>
 ```
 
 ### List projects
 
 ```bash
-bun run ai:fyzz-api -- projects
+bun ~/.agents/skills/fyzz-chat-api/tools/fyzz-api.ts -- projects
 ```
 
 ## Setup
@@ -35,7 +36,6 @@ If the tool reports a missing API key:
 
 ## Guidelines
 
-- Always run the tool from the PAL directory (the `ai:fyzz-api` script is registered there)
 - The API key is never visible in this conversation — that is by design
 - Use `--search` for keyword-based lookup across titles and message content
 - Use `--project-id` to scope results to a specific project

package/{src → assets/skills/fyzz-chat-api}/tools/fyzz-api.ts

@@ -6,9 +6,9 @@
  * Returns JSON responses from the Fyzz Chat REST API.
  *
  * Usage:
- *   bun run ai:fyzz-api -- conversations [--limit 20] [--search "query"] [--project-id <id>] [--cursor <cursor>]
- *   bun run ai:fyzz-api -- conversations <id>
- *   bun run ai:fyzz-api -- projects
+ *   bun fyzz-api.ts -- conversations [--limit 20] [--search "query"] [--project-id <id>] [--cursor <cursor>]
+ *   bun fyzz-api.ts -- conversations <id>
+ *   bun fyzz-api.ts -- projects
  */
 
 import { parseArgs } from "node:util";
@@ -53,11 +53,11 @@ const command = args[0];
 
 if (!command || command === "--help" || command === "-h") {
   console.log("Usage:");
-  console.log("  bun run ai:fyzz-api -- conversations                List conversations");
+  console.log("  bun fyzz-api.ts -- conversations                List conversations");
   console.log(
-    "  bun run ai:fyzz-api -- conversations <id>           Get conversation with messages"
+    "  bun fyzz-api.ts -- conversations <id>           Get conversation with messages"
   );
-  console.log("  bun run ai:fyzz-api -- projects                     List projects");
+  console.log("  bun fyzz-api.ts -- projects                     List projects");
   console.log("");
   console.log("Options for 'conversations' (list mode):");
   console.log("  --limit <n>          Max results (default 20)");

package/assets/skills/{reflect.md → reflect/SKILL.md}

@@ -1,6 +1,7 @@
 ---
 name: reflect
-description: Diagnose why a PAL behavior did not trigger as expected — trace hooks, instructions, and logic to find the gap
+description: Diagnose why a PAL behavior did not trigger as expected — trace hooks, instructions, and logic to find the gap. Use when a hook, skill, or automation didn't fire or behaved unexpectedly.
+argument-hint: <what went wrong>
 ---
 
 When the user invokes `/reflect [optional: description of what didn't happen]`:

package/assets/skills/{research.md → research/SKILL.md}

@@ -1,6 +1,7 @@
 ---
 name: research
-description: Multi-agent parallel research — quick/standard/extensive modes with specialized researcher agents for depth, breadth, and verification
+description: Multi-agent parallel research — quick/standard/extensive modes with specialized researcher agents for depth, breadth, and verification. Use when researching a topic, finding information, or investigating something thoroughly.
+argument-hint: <topic or question>
 ---
 
 ## Mode Routing

package/assets/skills/{review.md → review/SKILL.md}

@@ -1,6 +1,7 @@
 ---
 name: review
-description: Security-focused code review with severity ratings
+description: Security-focused code review with severity ratings. Use when reviewing code for security issues, vulnerabilities, or OWASP concerns.
+argument-hint: [file or directory]
 ---
 
 When the user invokes /review <file, diff, or PR>:

package/assets/skills/{summarize.md → summarize/SKILL.md}

@@ -1,9 +1,10 @@
 ---
 name: summarize
-description: Structured summarization of documents, URLs, or conversations
+description: Structured summarization of documents, URLs, or conversations. Use when summarizing content, creating overviews, or distilling key points.
+argument-hint: <document, URL, or topic>
 ---
 
-When the user invokes /summarize <target>:
+Summarize $ARGUMENTS:
 
 1. Fetch or read the target content
 2. Produce:

package/assets/skills/telos/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: telos
+description: Personal and project context management. Use when discussing goals, projects, beliefs, challenges, identity, updating telos, life context, what am I working on, adding a project, changing a goal, priorities, what do I believe, current obstacles, mission, or strategies.
+argument-hint: [area to view or update]
+---
+
+Manage the user's TELOS files — the persistent personal context that drives PAL.
+
+## TELOS Files
+
+All files live in `~/.agents/PAL/telos/`:
+
+| File | Contains |
+|------|----------|
+| `GOALS.md` | Short/medium/long-term goals |
+| `PROJECTS.md` | Active projects, status, priority |
+| `BELIEFS.md` | Core principles and values |
+| `CHALLENGES.md` | Current obstacles |
+| `MISSION.md` | Purpose and direction |
+| `STRATEGIES.md` | Approaches and plans |
+| `IDEAS.md` | Ideas to explore |
+| `LEARNED.md` | Key lessons |
+| `MODELS.md` | Mental models |
+| `NARRATIVES.md` | Narrative context |
+
+## Reading
+
+Read the file directly from `~/.agents/PAL/telos/` when the user asks about any area. Summarize what's relevant — don't dump the entire file unless asked.
+
+## Updating
+
+Use the update tool for all changes. It validates the file, creates a backup, appends content, and logs the change:
+
+```bash
+bun ~/.agents/skills/telos/tools/update-telos.ts <FILE> "<content>" "<description>"
+```
+
+## Routing
+
+| Intent | Action |
+|--------|--------|
+| "what am I working on", "my projects", "priorities" | Read `PROJECTS.md`, summarize active work |
+| "my goals", "what are my goals" | Read `GOALS.md`, present current state |
+| "update goals/projects/beliefs/challenges" | Read the target file, discuss changes with user, then run update tool |
+| "add a project", "new project" | Read `PROJECTS.md`, confirm with user, run update tool |
+| "complete/remove a project" | Read `PROJECTS.md`, confirm with user, update status via tool |
+| "what do I believe", "my principles" | Read `BELIEFS.md` |
+| "current obstacles", "challenges" | Read `CHALLENGES.md` |
+| "I learned something", "lesson" | Discuss, then append to `LEARNED.md` via tool |
+| "I have an idea" | Discuss, then append to `IDEAS.md` via tool |
+| General "update telos", "telos" | Ask which area to review/update |
+
+## Examples
+
+**Example 1: Checking projects**
+```
+User: "what am I working on?"
+→ Read PROJECTS.md
+→ Summarize active work by priority — don't list every column
+→ Highlight status changes, blockers, what needs attention
+```
+
+**Example 2: Adding a project**
+```
+User: "add my new side project"
+→ Ask: "What's the project name, status, and priority?"
+→ User provides details
+→ Show the row you'll add, confirm
+→ Run: bun ~/.agents/skills/telos/tools/update-telos.ts PROJECTS.md "| Side Project | In progress | Medium | Description |" "Added Side Project"
+```
+
+**Example 3: Updating goals**
+```
+User: "I finished the migration, update my goals"
+→ Read GOALS.md to see current state
+→ Discuss what changed — what's done, what's next
+→ Run tool to append updated goals
+→ Remind: CLAUDE.md regenerates next session
+```
+
+## Anti-patterns
+
+- **Don't dump raw file contents.** Summarize what's relevant to the user's question. They can ask for the full file if needed.
+- **Don't update without confirming.** Always show what you'll change and get a "yes" before running the tool.
+- **Don't create new TELOS files.** Only the 10 listed files are valid. If something doesn't fit, suggest the closest match.
+- **Don't mix TELOS with identity.** AI/principal identity lives in `pal-settings.json`, not TELOS. TELOS is personal context — goals, beliefs, projects.
+- **Don't reference stale data.** If TELOS was loaded earlier in the session via context routing, re-read the file before updating — it may have changed.
+
+## Rules
+
+- **Always read the file first** before making changes — match the existing format exactly
+- **Confirm changes** with the user before running the update tool
+- **Always use the tool** for writes — never edit TELOS files directly
+- CLAUDE.md auto-regenerates from these files on next session start

package/assets/skills/telos/tools/update-telos.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env bun
+/**
+ * UpdateTelos — Validate, backup, update, and log changes to TELOS files.
+ *
+ * Usage:
+ *   bun update-telos.ts <file> "<content>" "<description>"
+ *
+ * - Validates the filename against the known TELOS files
+ * - Creates a timestamped backup before modifying
+ * - Appends content (preserves existing)
+ * - Logs the change to updates.md
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+import { palHome } from "../../../../src/hooks/lib/paths";
+
+const TELOS_DIR = resolve(palHome(), "telos");
+const BACKUPS_DIR = resolve(TELOS_DIR, "backups");
+const UPDATES_LOG = resolve(TELOS_DIR, "updates.md");
+
+const VALID_FILES = [
+  "BELIEFS.md",
+  "CHALLENGES.md",
+  "GOALS.md",
+  "IDEAS.md",
+  "LEARNED.md",
+  "MISSION.md",
+  "MODELS.md",
+  "NARRATIVES.md",
+  "PROJECTS.md",
+  "STRATEGIES.md",
+];
+
+function timestamp(): string {
+  const now = new Date();
+  const pad = (n: number) => n.toString().padStart(2, "0");
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+function isoDate(): string {
+  return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+
+const args = process.argv.slice(2);
+const file = args[0];
+const content = args[1];
+const description = args[2];
+
+if (!file || !content || !description) {
+  console.error('Usage: bun update-telos.ts <file> "<content>" "<description>"');
+  console.error(`\nValid files: ${VALID_FILES.join(", ")}`);
+  process.exit(1);
+}
+
+if (!VALID_FILES.includes(file)) {
+  console.error(`Error: "${file}" is not a valid TELOS file.`);
+  console.error(`Valid files: ${VALID_FILES.join(", ")}`);
+  process.exit(1);
+}
+
+const filePath = resolve(TELOS_DIR, file);
+
+// Backup
+mkdirSync(BACKUPS_DIR, { recursive: true });
+if (existsSync(filePath)) {
+  const backupName = `${file.replace(".md", "")}-${timestamp()}.md`;
+  copyFileSync(filePath, resolve(BACKUPS_DIR, backupName));
+}
+
+// Append content
+const existing = existsSync(filePath) ? readFileSync(filePath, "utf-8") : "";
+const separator = existing.trim() ? "\n\n" : "";
+writeFileSync(filePath, `${existing.trimEnd()}${separator}${content.trim()}\n`, "utf-8");
+
+// Log change
+const logEntry = `- **${isoDate()}** — \`${file}\`: ${description}`;
+const existingLog = existsSync(UPDATES_LOG)
+  ? readFileSync(UPDATES_LOG, "utf-8")
+  : "# TELOS Updates\n";
+writeFileSync(UPDATES_LOG, `${existingLog.trimEnd()}\n${logEntry}\n`, "utf-8");
+
+console.log(
+  JSON.stringify(
+    {
+      file,
+      backed_up: true,
+      logged: true,
+      description,
+    },
+    null,
+    2
+  )
+);

package/assets/skills/think/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: think
+description: Thinking mode router — selects the right analytical approach for a question. Use when thinking through a problem, analyzing deeply, brainstorming ideas, debating options, decomposing to root cause, challenging assumptions, or exploring from multiple perspectives.
+argument-hint: <question or topic>
+---
+
+Route $ARGUMENTS to the right thinking mode based on intent. Detect the mode from context — do NOT ask.
+
+## Routing
+
+| Intent signals | Mode | How to invoke |
+|---------------|------|---------------|
+| decompose, root cause, fundamental, challenge assumptions, first principles | **First Principles** | Use the Skill tool to invoke `first-principles` with $ARGUMENTS |
+| debate, weigh options, multiple viewpoints, perspectives, deliberate | **Council** | Use the Skill tool to invoke `council` with $ARGUMENTS |
+| brainstorm, creative, divergent, ideas, what if, possibilities | **Creative** | Follow the Creative steps below with $ARGUMENTS |
+| think through, analyze, explore deeply, examine from angles | **Deep Analysis** | Follow the Deep Analysis steps below with $ARGUMENTS |
+
+If intent is ambiguous, default to **Deep Analysis**.
+
+---
+
+## Creative
+
+Divergent ideation — quantity and variety over polish.
+
+1. **Restate the challenge** in one sentence
+2. **Obvious solutions** — 2-3 conventional approaches (acknowledge, then move past)
+3. **Wild ideas** — 5-7 unconventional approaches. Mix:
+   - Inversion (what if we did the opposite?)
+   - Analogy (how does a different domain solve this?)
+   - Removal (what if we deleted the constraint?)
+   - Combination (what if we merged two approaches?)
+4. **Diamond pick** — which 1-2 wild ideas have real potential and why
+5. **Next step** — one concrete action to explore the best idea
+
+---
+
+## Deep Analysis
+
+Multi-angle exploration for complex topics.
+
+1. **Frame the question** precisely
+2. **Technical** — mechanics, constraints, and trade-offs
+3. **Practical** — what does this look like in practice? What's the effort?
+4. **Strategic** — how does this fit the bigger picture? What does it enable or block?
+5. **Tensions** — where do the angles disagree?
+6. **Synthesis** — what the analysis reveals that wasn't obvious at the surface