portable-agent-layer 0.21.0 → 0.23.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 |
 |----------|-------------|
-| `PAL_GEMINI_API_KEY` | For YouTube video analysis skill |
+| `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

@@ -1,8 +1,22 @@
 ---
 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
+
+claude:
+  tools: Bash, WebSearch, WebFetch, Read, Grep, Glob
+  model: sonnet
+
+opencode:
+  mode: subagent
+  permission:
+    read: allow
+    webfetch: allow
+    bash: allow
+
+cursor:
+  model: inherit
+  readonly: false
+  is_background: false
 ---
 
 You are a research specialist focused on **depth and academic rigor**.
@@ -11,7 +25,7 @@ You are a research specialist focused on **depth and academic rigor**.
 
 **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>"
+bun ~/.pal/skills/research/tools/gemini-search.ts -- "<query>"
 ```
 
 - If it returns results → **continue using Gemini Search** for remaining queries

package/assets/agents/grok-researcher.md

@@ -1,8 +1,22 @@
 ---
 name: grok-researcher
 description: Real-time research via Grok/X API — fetches live data from X (Twitter), trending topics, and breaking news. Use for research requiring up-to-the-minute information about current events, public sentiment, or rapidly evolving situations.
-tools: WebSearch, WebFetch, Bash, Read, Grep, Glob
-model: sonnet
+
+claude:
+  tools: WebSearch, WebFetch, Bash, Read, Grep, Glob
+  model: sonnet
+
+opencode:
+  mode: subagent
+  permission:
+    read: allow
+    webfetch: allow
+    bash: allow
+
+cursor:
+  model: inherit
+  readonly: false
+  is_background: false
 ---
 
 You are a research specialist focused on **real-time information and current events** using the Grok API and X (Twitter) data.
@@ -14,19 +28,19 @@ Use the `grok-search` tool to query the Grok API with real-time search grounding
 ### Current events / breaking news (web + X sources)
 
 ```bash
-bun ~/.agents/skills/research/tools/grok-search.ts -- "<your research query>" --sources web,x
+bun ~/.pal/skills/research/tools/grok-search.ts -- "<your research query>" --sources web,x
 ```
 
 ### Social sentiment / trending topics (X only)
 
 ```bash
-bun ~/.agents/skills/research/tools/grok-search.ts -- "Search X for recent posts about: <topic>. Summarize key themes, notable accounts, and overall sentiment." --sources x
+bun ~/.pal/skills/research/tools/grok-search.ts -- "Search X for recent posts about: <topic>. Summarize key themes, notable accounts, and overall sentiment." --sources x
 ```
 
 ### Web-only search
 
 ```bash
-bun ~/.agents/skills/research/tools/grok-search.ts -- "<query>" --sources web
+bun ~/.pal/skills/research/tools/grok-search.ts -- "<query>" --sources web
 ```
 
 The tool outputs findings as markdown with a `## Sources` section listing URLs and X posts.

package/assets/agents/multi-perspective-researcher.md

@@ -1,8 +1,22 @@
 ---
 name: multi-perspective-researcher
 description: Breadth-focused research — generates multiple query variations, explores different angles, synthesizes diverse viewpoints. Use for research needing perspective diversity.
-tools: WebSearch, WebFetch, Read, Grep, Glob
-model: sonnet
+
+claude:
+  tools: WebSearch, WebFetch, Read, Grep, Glob
+  model: sonnet
+
+opencode:
+  mode: subagent
+  permission:
+    read: allow
+    webfetch: allow
+    bash: allow
+
+cursor:
+  model: inherit
+  readonly: false
+  is_background: false
 ---
 
 You are a research specialist focused on **breadth and perspective diversity**.

package/assets/agents/perplexity-researcher.md

@@ -1,8 +1,22 @@
 ---
 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
+
+claude:
+  tools: Bash, WebSearch, WebFetch, Read, Grep, Glob
+  model: sonnet
+
+opencode:
+  mode: subagent
+  permission:
+    read: allow
+    webfetch: allow
+    bash: allow
+
+cursor:
+  model: inherit
+  readonly: false
+  is_background: false
 ---
 
 You are a research specialist focused on **investigative rigor and source verification**.
@@ -11,7 +25,7 @@ You are a research specialist focused on **investigative rigor and source verifi
 
 **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>"
+bun ~/.pal/skills/research/tools/perplexity-search.ts -- "<query>"
 ```
 
 - If it returns results → **continue using Perplexity Search** for remaining queries

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

@@ -10,7 +10,7 @@ When the user asks to analyze, read, or extract information from a PDF:
 
 - **URL**: Use the `pdf-download` CLI tool to download and archive the PDF:
   ```bash
-  bun ~/.agents/skills/analyze-pdf/tools/pdf-download.ts -- <url> [--filename <name.pdf>]
+  bun ~/.pal/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`.
 

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

@@ -11,7 +11,7 @@ When the user asks to analyze, summarize, or extract information from a YouTube
 Use the `youtube-analyze` CLI tool. It sends the video to Gemini, which processes both visual and audio content natively.
 
 ```bash
-bun ~/.agents/skills/analyze-youtube/tools/youtube-analyze.ts -- <youtube-url> [--prompt "your question"]
+bun ~/.pal/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.

package/assets/skills/extract-entities/SKILL.md

@@ -56,7 +56,7 @@ Return structured JSON:
 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 ~/.agents/skills/extract-entities/tools/entity-save.ts -- --source "<URL or content origin>"
+echo '<the JSON output>' | bun ~/.pal/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/assets/skills/fyzz-chat-api/SKILL.md

@@ -4,26 +4,26 @@ 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
 
 ### List conversations
 
 ```bash
-bun ~/.agents/skills/fyzz-chat-api/tools/fyzz-api.ts -- conversations [--limit 20] [--search "query"] [--project-id <id>] [--cursor <cursor>]
+bun ~/.pal/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 ~/.agents/skills/fyzz-chat-api/tools/fyzz-api.ts -- conversations <conversation-id>
+bun ~/.pal/skills/fyzz-chat-api/tools/fyzz-api.ts -- conversations <conversation-id>
 ```
 
 ### List projects
 
 ```bash
-bun ~/.agents/skills/fyzz-chat-api/tools/fyzz-api.ts -- projects
+bun ~/.pal/skills/fyzz-chat-api/tools/fyzz-api.ts -- projects
 ```
 
 ## Setup
@@ -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/reflect/SKILL.md

@@ -23,7 +23,7 @@ Determine which PAL subsystem owns this behavior:
 | **Hook-automated** | Runs automatically via StopOrchestrator or UserPromptOrchestrator | `hooks/StopOrchestrator.ts`, `hooks/UserPromptOrchestrator.ts`, `hooks/lib/stop.ts` |
 | **Instruction-driven** | AI is told to do it via CLAUDE.md / AGENTS.md instructions | `~/.claude/CLAUDE.md`, project CLAUDE.md files |
 | **Context-dependent** | Requires specific context to be loaded at session start | `hooks/LoadContext.ts`, `hooks/lib/context.ts` |
-| **Skill-triggered** | Should have been invoked via a skill | `~/.agents/skills/*/SKILL.md` |
+| **Skill-triggered** | Should have been invoked via a skill | `~/.pal/skills/*/SKILL.md` |
 
 ## 3. Trace the execution path
 
@@ -48,7 +48,7 @@ Based on the type, investigate the relevant chain:
 3. Check if context was truncated or missing
 
 ### For skill-triggered behaviors:
-1. Verify the skill exists in `~/.agents/skills/`
+1. Verify the skill exists in `~/.pal/skills/`
 2. Check if SkillGuard blocked it
 3. Check if the skill's trigger conditions match what happened
 

package/assets/skills/telos/SKILL.md

@@ -8,7 +8,7 @@ Manage the user's TELOS files — the persistent personal context that drives PA
 
 ## TELOS Files
 
-All files live in `~/.agents/PAL/telos/`:
+All files live in `~/.pal/telos/`:
 
 | File | Contains |
 |------|----------|
@@ -25,7 +25,7 @@ All files live in `~/.agents/PAL/telos/`:
 
 ## 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.
+Read the file directly from `~/.pal/telos/` when the user asks about any area. Summarize what's relevant — don't dump the entire file unless asked.
 
 ## Updating
 
@@ -34,7 +34,7 @@ Read the file directly from `~/.agents/PAL/telos/` when the user asks about any
 For all files except PROJECTS.md — appends content, creates backup, logs the change:
 
 ```bash
-bun ~/.agents/skills/telos/tools/update-telos.ts <FILE> "<content>" "<description>"
+bun ~/.pal/skills/telos/tools/update-telos.ts <FILE> "<content>" "<description>"
 ```
 
 ### Projects (upsert by ID)
@@ -42,7 +42,7 @@ bun ~/.agents/skills/telos/tools/update-telos.ts <FILE> "<content>" "<descriptio
 For PROJECTS.md — upserts a row by the ID column. Replaces if the ID exists, appends if new:
 
 ```bash
-bun ~/.agents/skills/telos/tools/update-projects.ts <id> "<row>" "<description>"
+bun ~/.pal/skills/telos/tools/update-projects.ts <id> "<row>" "<description>"
 ```
 
 The ID is the first column of the table. Use short, lowercase, kebab-case slugs (e.g., `my-project`, `side-gig`).
@@ -78,7 +78,7 @@ 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-projects.ts side-project "| side-project | Side Project | In progress | Medium | Description |" "Added Side Project"
+→ Run: bun ~/.pal/skills/telos/tools/update-projects.ts side-project "| side-project | Side Project | In progress | Medium | Description |" "Added Side Project"
 ```
 
 **Example 3: Updating a project**
@@ -86,7 +86,7 @@ User: "add my new side project"
 User: "mark X as complete"
 → Read PROJECTS.md, find the entry and its ID
 → Show updated row, confirm
-→ Run: bun ~/.agents/skills/telos/tools/update-projects.ts some-id "| some-id | Project Name | Complete | High | ... |" "Marked project as complete"
+→ Run: bun ~/.pal/skills/telos/tools/update-projects.ts some-id "| some-id | Project Name | Complete | High | ... |" "Marked project as complete"
 → The existing row is replaced, not duplicated
 ```
 

package/assets/templates/AGENTS.md.template

@@ -44,7 +44,7 @@ On follow-ups, include the ITERATION line. On first response to a new request, o
 
 FOR: Multi-step, complex, or difficult work. Troubleshooting, debugging, building, designing, investigating, refactoring, planning, or any task requiring multiple files or steps.
 
-**MANDATORY FIRST ACTION:** Read `~/.agents/PAL/ALGORITHM.md` and follow its instructions exactly.
+**MANDATORY FIRST ACTION:** Read `~/.pal/docs/ALGORITHM.md` and follow its instructions exactly.
 
 Start your response with the following header in this mode:
 ══════ PAL | ALGORITHM ══════
@@ -61,7 +61,7 @@ Start your response with the following header in this mode:
 {{SETUP_PROMPT}}
 ## Context Routing
 
-When you need context about any of these topics, read `~/.agents/PAL/CONTEXT_ROUTING.md` for the file path:
+When you need context about any of these topics, read `~/.pal/docs/CONTEXT_ROUTING.md` for the file path:
 
 - PAL internals
 - The user, their life and work, etc

package/assets/templates/PAL/ALGORITHM.md

@@ -2,6 +2,26 @@
 
 Core: transition from CURRENT STATE to IDEAL STATE using verifiable criteria. Every criterion is atomic, binary testable, and checked off with evidence.
 
+## Effort Levels
+
+Assign ONE tier at the start of OBSERVE. Default is Standard — only escalate if the request demands depth.
+
+| Tier | Criteria | Min Capabilities | When |
+|------|----------|-----------------|------|
+| **Standard** | 3-8 | 1-2 | Normal request, single concern |
+| **Extended** | 8-16 | 3-5 | Multi-file, quality must be high |
+| **Advanced** | 16-32 | 5-8 | Substantial design or refactoring |
+| **Deep** | 32+ | 8+ | Complex architecture, no time pressure |
+
+**What scales by effort level:**
+
+| Element | Standard | Extended+ |
+|---------|----------|-----------|
+| Capability audit format | One-line summary | Full USE/DECLINE/N/A |
+| Plan Mode (EnterPlanMode) | Skip | Use for user alignment |
+| LEARN phase | Reflection log + threads | + Wisdom frame |
+| Constraint extraction | Inline in reverse engineering | Numbered [EX-N] list |
+
 ## The Five Phases
 
 All work happens inside these phases. No work outside the phase structure until the Algorithm completes.
@@ -10,6 +30,11 @@ All work happens inside these phases. No work outside the phase structure until
 
 Thinking-only. No tool calls except context recovery (Grep/Glob/Read).
 
+**0. Assign effort level** — classify the request using the table above. Output:
+```
+⏱️ EFFORT: [Standard | Extended | Advanced | Deep] — [one-line reason]
+```
+
 **1. Reverse engineer the request:**
 
 🔎 REVERSE ENGINEERING:
@@ -19,6 +44,24 @@ Thinking-only. No tool calls except context recovery (Grep/Glob/Read).
 - What is obvious they don't want that they didn't say?
 - What are common gotchas for this type of work?
 
+**1.5. Extract constraints:**
+
+**Standard:** Note constraints inline in the reverse engineering bullets above — e.g. "[Constraint: max 3 retries, timeout 30s]". No separate section needed.
+
+**Extended+:** Extract numbered constraints from the request. Scan for:
+- **Quantitative** — numbers, limits, thresholds, ranges
+- **Prohibitions** — "don't", "never", "must not", "avoid"
+- **Requirements** — "must", "always", "required", "needs to"
+- **Implicit** — conventions, patterns, or standards obvious from context
+
+```
+🔬 CONSTRAINTS:
+- [EX-1]: [constraint]
+- [EX-2]: [constraint]
+```
+
+Every constraint must map to at least one criterion in step 2. A constraint without a covering criterion is a gap.
+
 **2. Define verifiable criteria:**
 
 Write atomic criteria — each one is a single testable end-state. Apply the splitting test:
@@ -35,13 +78,62 @@ Format:
 
 Include at least one anti-criterion (C-A prefix).
 
-**3. Select capabilities:**
+**3. Capability audit:**
+
+Scan ALL 14 capabilities below. For each, assign exactly one disposition:
+- **USE** — will invoke during a specific phase. State which.
+- **DECLINE** — would help but not worth it for this task's scope.
+- **N/A** — genuinely irrelevant to this task.
+
+**A: Foundation**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 1 | Task Tool | TaskCreate, TaskUpdate, TaskList |
+| 2 | AskUserQuestion | Built-in tool |
+| 3 | Skills (ACTIVE SCAN) | Read `skill-index.json`, match triggers against task |
+
+**B: Thinking & Analysis**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 4 | Think (analysis router) | `think` skill |
+| 5 | First Principles | `first-principles` skill |
+| 6 | Council (multi-perspective) | `council` skill |
+| 7 | Plan Mode | EnterPlanMode tool |
+
+**C: Agents & Research**
+
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 8 | Research (multi-agent) | `research` skill |
+| 9 | Subagents | Agent tool (Explore, Plan, general-purpose) |
+| 10 | Background agents | Agent tool with `run_in_background: true` |
+
+**D: Execution & Verification**
 
-Scan the available skills listing. Select skills and tools you'll invoke during EXECUTE. Selecting a capability = commitment to invoke it via tool call. Don't select what you won't use.
+| # | Capability | Invocation |
+|---|-----------|------------|
+| 11 | Git worktree isolation | `isolation: "worktree"` on Agent |
+| 12 | Test runner | `bun test`, vitest, jest, pytest |
+| 13 | Static analysis | `tsc --noEmit`, biome, eslint |
+| 14 | CLI probes | curl, diff, jq, exit codes |
 
-Output:
+**Capability #3 (Skills) requires active scanning.** Read `skill-index.json` and match the task against skill triggers. "Skills — N/A" without evidence of scanning is an error.
+
+Output — scales by effort level:
+
+**Standard:**
+```
+🏹 CAPABILITIES: #1 Task, #3 Skills (matched: research) | 14/14 scanned, USE: 2
 ```
-🏹 CAPABILITIES: [list each selected skill/tool and why]
+
+**Extended+:**
+```
+🏹 CAPABILITIES (14/14):
+USE: [#, #, #] — [reason (phase: WHICH)]
+DECLINE: [#, #] — [reason]
+N/A: [rest]
 ```
 
 ### ━━━ 🧠 PLAN ━━━ 2/5
@@ -57,7 +149,7 @@ Refine criteria if the pressure test reveals gaps. Add criteria for uncovered fa
 **Plan the execution:**
 - Validate prerequisites (env vars, dependencies, files, state)
 - Decide execution order — what's serial, what can parallelize
-- If Advanced+ complexity, use EnterPlanMode for user alignment
+- **Extended+:** use EnterPlanMode for user alignment before executing
 
 ### ━━━ ⚡ EXECUTE ━━━ 3/5
 
@@ -90,16 +182,44 @@ If any criteria failed, fix and re-verify before completing.
 
 ### ━━━ 📚 LEARN ━━━ 5/5
 
-Reflect on the work and capture reusable knowledge. Skip this phase when the work was trivial or purely mechanical.
+Reflect on the work and capture reusable knowledge.
+
+**Skip only if:** the entire task was a single edit or lookup with zero decisions made (e.g. a typo fix, reading a file). Any task involving planning, debugging, multiple steps, or judgment calls requires LEARN — no exceptions.
+
+**1. Algorithm Reflection** (one sentence each — reflect on ALGORITHM PERFORMANCE, not task subject matter):
+
+**Q1 — Self:** "What would I have done differently in this Algorithm run?"
+Focus: phase execution, criteria quality, capability selection decisions.
+
+**Q2 — Algorithm:** "What would a smarter algorithm have done differently?"
+Focus: structural improvements — missing phases, better gating, capability triggers, ISC patterns.
+
+**Q3 — AI:** "What would a fundamentally smarter AI have done differently?"
+Focus: reasoning approach, problem decomposition, anticipation, blind spots.
+
+**2. Reflection Log** — record algorithm performance:
 
-**1. Reflection** (one sentence each):
-- What would I do differently next time?
-- What would a better algorithm have done differently?
+```bash
+bun ~/.pal/tools/algorithm-reflect.ts --task "description" --criteria N --passed N --failed N --sentiment 1-10 \
+  --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+```
+
+**3. Open Threads** — for each unresolved question, decision, or follow-up that came up during this session:
+
+```bash
+bun ~/.pal/tools/thread.ts --add --title "brief title" --context "why it matters, what needs to happen"
+```
 
-**2. Wisdom Frame** — if the session produced a genuine, reusable insight:
+Only add threads that genuinely need follow-up. Resolve existing threads if this session closed them:
 
 ```bash
-bun ~/.agents/PAL/tools/wisdom-frame.ts --domain <domain> --observation "insight" [--type principle|contextual-rule|anti-pattern|evolution]
+bun ~/.pal/tools/thread.ts --resolve --id <id>
+```
+
+**4. Wisdom Frame** (Extended+ only) — if the session produced a genuine, reusable insight:
+
+```bash
+bun ~/.pal/tools/wisdom-frame.ts --domain <domain> --observation "insight" [--type principle|contextual-rule|anti-pattern|evolution]
 ```
 
 Domains: `development`, `workflow`, `communication`, `infrastructure`, `integration`, or any fitting domain.
@@ -110,15 +230,18 @@ Only write if the insight is **genuine and reusable** — not every session prod
 ```
 ♻️ ALGORITHM ═══════════════════════════
 🗒️ TASK: [brief description]
+⏱️ EFFORT: [tier] — [reason]
 
 ━━━ 👁️ OBSERVE ━━━ 1/5
 🔎 REVERSE ENGINEERING:
 [reverse engineering output]
 
+🔬 CONSTRAINTS: [Extended+: EX-1, EX-2... | Standard: inline above]
+
 📋 CRITERIA:
 [criteria checklist]
 
-🏹 CAPABILITIES: [selected capabilities]
+🏹 CAPABILITIES: [format scales by effort level]
 
 ━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]
@@ -136,6 +259,9 @@ Only write if the insight is **genuine and reusable** — not every session prod
 🗣️ {{IDENTITY_NAME}}: [summary]
 
 ━━━ 📚 LEARN ━━━ 5/5
-🪞 REFLECT: [what I'd do differently]
+🪞 Q1 — Self: [what I'd do differently]
+🪞 Q2 — Algorithm: [structural improvement]
+🪞 Q3 — AI: [reasoning blind spot]
+📊 REFLECTION LOG: [appended to algorithm-reflections.jsonl]
 📝 WISDOM: [frame update if genuine insight, or "No new insight"]
 ```

package/assets/templates/PAL/CONTEXT_ROUTING.md

@@ -6,25 +6,25 @@ Load context on-demand by reading the file at the path listed. Only load what th
 
 | Topic | Path |
 |-------|------|
-| PAL system overview | `~/.agents/PAL/README.md` |
-| System architecture | `~/.agents/PAL/SYSTEM_ARCHITECTURE.md` |
-| 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` |
-| Algorithm (complex work phases) | `~/.agents/PAL/ALGORITHM.md` |
+| PAL system overview | `~/.pal/docs/README.md` |
+| System architecture | `~/.pal/docs/SYSTEM_ARCHITECTURE.md` |
+| Memory format & guidelines | `~/.pal/docs/MEMORY_SYSTEM.md` |
+| Work tracking (projects, sessions) | `~/.pal/docs/WORK_TRACKING.md` |
+| Opinion tracking | `~/.pal/docs/OPINION_TRACKING.md` |
+| Steering rules | `~/.pal/docs/STEERING_RULES.md` |
+| Algorithm (complex work phases) | `~/.pal/docs/ALGORITHM.md` |
 
 ## User Context (TELOS)
 
 | Topic | Path |
 |-------|------|
-| Projects & priorities | `~/.agents/PAL/telos/PROJECTS.md` |
-| Goals (short/medium/long-term) | `~/.agents/PAL/telos/GOALS.md` |
-| Beliefs & principles | `~/.agents/PAL/telos/BELIEFS.md` |
-| Current challenges | `~/.agents/PAL/telos/CHALLENGES.md` |
-| Mission & direction | `~/.agents/PAL/telos/MISSION.md` |
-| Strategies & approaches | `~/.agents/PAL/telos/STRATEGIES.md` |
-| Ideas to explore | `~/.agents/PAL/telos/IDEAS.md` |
-| Key lessons learned | `~/.agents/PAL/telos/LEARNED.md` |
-| Mental models | `~/.agents/PAL/telos/MODELS.md` |
-| Narrative context | `~/.agents/PAL/telos/NARRATIVES.md` |
+| Projects & priorities | `~/.pal/telos/PROJECTS.md` |
+| Goals (short/medium/long-term) | `~/.pal/telos/GOALS.md` |
+| Beliefs & principles | `~/.pal/telos/BELIEFS.md` |
+| Current challenges | `~/.pal/telos/CHALLENGES.md` |
+| Mission & direction | `~/.pal/telos/MISSION.md` |
+| Strategies & approaches | `~/.pal/telos/STRATEGIES.md` |
+| Ideas to explore | `~/.pal/telos/IDEAS.md` |
+| Key lessons learned | `~/.pal/telos/LEARNED.md` |
+| Mental models | `~/.pal/telos/MODELS.md` |
+| Narrative context | `~/.pal/telos/NARRATIVES.md` |

package/assets/templates/PAL/MEMORY_SYSTEM.md

@@ -4,11 +4,11 @@ PAL has its own memory system that persists across sessions AND across tools (Cl
 
 ## 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)
+- **Wisdom frames**: `~/.pal/memory/wisdom/frames/` — crystallized principles per domain (loaded every session)
+- **Relationship notes**: `~/.pal/memory/relationship/YYYY-MM/YYYY-MM-DD.md` — daily interaction observations (loaded every session)
+- **Session learnings**: `~/.pal/memory/learning/session/YYYY-MM/*.md` — reusable insights from sessions (loaded every session)
+- **Failure captures**: `~/.pal/memory/learning/failures/YYYY-MM/{timestamp}_{slug}/capture.md` — what went wrong and why
+- **Signals**: `~/.pal/memory/signals/ratings.jsonl` — append-only rating signal log (do not edit directly)
 
 ## Format