portable-agent-layer 0.10.0 → 0.11.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,60 @@
+---
+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 |
+| `IDENTITY.md` | AI identity and personality |
+| `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.
+
+## 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>"
+```
+
+**Example:**
+```bash
+bun ~/.agents/skills/telos/tools/update-telos.ts PROJECTS.md "| New Project | In progress | High | Description |" "Added New Project"
+```
+
+## Routing
+
+| Intent | Action |
+|--------|--------|
+| "what am I working on", "my projects", "priorities" | Read `PROJECTS.md`, summarize |
+| "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 |
+| "what do I believe", "my principles" | Read `BELIEFS.md` |
+| "current obstacles", "challenges" | Read `CHALLENGES.md` |
+| General "update telos", "telos" | Ask which area to review/update |
+
+## 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

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

@@ -0,0 +1,101 @@
+#!/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",
+  "IDENTITY.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

package/assets/templates/AGENTS.md.template

@@ -1,51 +1,16 @@
 # PAL — Portable Agent Layer
 
-You have PA installed. PAL provides persistent personal context across sessions — the user's identity, goals, projects, beliefs, and challenges are stored in TELOS files and loaded into your context automatically. Use this information to tailor your responses to who they are and what they care about.
+You have PAL installed. PAL provides persistent personal context across sessions — the user's identity, goals, projects, beliefs, and challenges are stored in TELOS files and loaded on demand via the `telos` skill.
 
 When TELOS is populated, you already know the user. When it's empty, first-run setup is required — follow the setup instructions below.
 
 {{SETUP_PROMPT}}
-{{TELOS}}
-## Memory
+## Context Routing
 
-PAL has its own memory system that persists across sessions AND across tools (Claude Code, opencode). Always prefer PAL memory over any tool-native memory system.
+When you need context about any of these topics, read `~/.agents/PAL/CONTEXT_ROUTING.md` for the file path:
 
-### Where to write
-
-{{MEMORY_PATHS}}
-
-### Format
-
-- **Wisdom frames**: One `.md` file per domain/topic. Each file contains bullet-point principles the user has validated or you've learned. Append new principles to existing files or create new domain files.
-- **Relationship notes**: Daily `.md` file with bullet-point observations about the interaction (tone, preferences, corrections).
-- **Session learnings**: One `.md` file per session with a `**Title:**` line summarizing what was learned.
-- **Failure captures**: One directory per failure, named `{YYYYMMDD-HHmmss}_{slug}/`, containing a `capture.md` with what went wrong and why.
-
-## Work Tracking
-
-PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captured) and `memory/state/projects.json` (AI-managed).
-
-### Projects
-
-Update `projects.json` via the work-tracking library when:
-- **Starting sustained multi-session work** → create a project with objectives and an id (slugified, e.g. "pdf-template-engine")
-- **Making a key decision** → add to the project's `decisions` array
-- **Completing a milestone** → add to `completed`, remove from `nextSteps`
-- **Session ends with open work** → update `nextSteps` and `handoff`
-- **Work is done** → set status to "completed"
-
-Do not create projects for one-off questions or quick fixes.
-
-### When to write
-
-- When the user corrects you or gives feedback → wisdom frame
-- When you learn something about how the user prefers to work → relationship note
-- When a session produces reusable insights → session learning
-- When something fails significantly (rating < 6) → failure capture
-- Do NOT write memories about trivial exchanges or things already captured in TELOS.
-
-## Opinion Tracking
-
-PAL tracks confidence-scored opinions about the user. When you notice the user confirming or contradicting a behavioral pattern, update it via `bun run tool:opinion`. Run `bun run tool:opinion -- --help` for full usage and examples. Opinions at ≥85% confidence are automatically injected into every session context.
-
-{{STEERING_RULES}}
+- PAL internals
+- The user, their life and work, etc
+- Your own personality and rules
+- Any project referenced, any work, etc.
+- Basically anything that's specialized

package/assets/templates/PAL/CONTEXT_ROUTING.md

@@ -0,0 +1,12 @@
+# Context Routing
+
+Load context on-demand by reading the file at the path listed. Only load what the current task requires.
+
+## PAL System
+
+| Topic | Path |
+|-------|------|
+| Memory format & guidelines | `~/.agents/PAL/MEMORY_SYSTEM.md` |
+| Work tracking (projects, sessions) | `~/.agents/PAL/WORK_TRACKING.md` |
+| Opinion tracking | `~/.agents/PAL/OPINION_TRACKING.md` |
+| Steering rules | `~/.agents/PAL/STEERING_RULES.md` |

package/assets/templates/PAL/MEMORY_SYSTEM.md

@@ -0,0 +1,26 @@
+# Memory System
+
+PAL has its own memory system that persists across sessions AND across tools (Claude Code, opencode). Always prefer PAL memory over any tool-native memory system.
+
+## Where to write
+
+- **Wisdom frames**: `~/.agents/PAL/memory/wisdom/frames/` — crystallized principles per domain (loaded every session)
+- **Relationship notes**: `~/.agents/PAL/memory/relationship/YYYY-MM/YYYY-MM-DD.md` — daily interaction observations (loaded every session)
+- **Session learnings**: `~/.agents/PAL/memory/learning/session/YYYY-MM/*.md` — reusable insights from sessions (loaded every session)
+- **Failure captures**: `~/.agents/PAL/memory/learning/failures/YYYY-MM/{timestamp}_{slug}/capture.md` — what went wrong and why
+- **Signals**: `~/.agents/PAL/memory/signals/ratings.jsonl` — append-only rating signal log (do not edit directly)
+
+## Format
+
+- **Wisdom frames**: One `.md` file per domain/topic. Each file contains bullet-point principles the user has validated or you've learned. Append new principles to existing files or create new domain files.
+- **Relationship notes**: Daily `.md` file with bullet-point observations about the interaction (tone, preferences, corrections).
+- **Session learnings**: One `.md` file per session with a `**Title:**` line summarizing what was learned.
+- **Failure captures**: One directory per failure, named `{YYYYMMDD-HHmmss}_{slug}/`, containing a `capture.md` with what went wrong and why.
+
+## When to write
+
+- When the user corrects you or gives feedback → wisdom frame
+- When you learn something about how the user prefers to work → relationship note
+- When a session produces reusable insights → session learning
+- When something fails significantly (rating < 6) → failure capture
+- Do NOT write memories about trivial exchanges or things already captured in TELOS.

package/assets/templates/PAL/OPINION_TRACKING.md

@@ -0,0 +1,3 @@
+# Opinion Tracking
+
+PAL tracks confidence-scored opinions about the user. When you notice the user confirming or contradicting a behavioral pattern, update it via `bun run tool:opinion`. Run `bun run tool:opinion -- --help` for full usage and examples. Opinions at ≥85% confidence are automatically injected into every session context.

package/assets/templates/{STEERING-RULES.md → PAL/STEERING_RULES.md}

@@ -1,4 +1,4 @@
-## Steering Rules
+# Steering Rules
 
 Behavioral directives — act on these, don't just know them.