portable-agent-layer 0.22.0 → 0.23.0

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

@@ -11,19 +11,19 @@ When you need to access the user's Fyzz Chat conversations or projects, use the
 ### 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

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:
@@ -78,7 +121,14 @@ Scan ALL 14 capabilities below. For each, assign exactly one disposition:
 
 **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:
+Output — scales by effort level:
+
+**Standard:**
+```
+🏹 CAPABILITIES: #1 Task, #3 Skills (matched: research) | 14/14 scanned, USE: 2
+```
+
+**Extended+:**
 ```
 🏹 CAPABILITIES (14/14):
 USE: [#, #, #] — [reason (phase: WHICH)]
@@ -99,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
 
@@ -132,7 +182,9 @@ 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):
 
@@ -148,14 +200,26 @@ Focus: reasoning approach, problem decomposition, anticipation, blind spots.
 **2. Reflection Log** — record algorithm performance:
 
 ```bash
-bun ~/.agents/PAL/tools/algorithm-reflect.ts --task "description" --criteria N --passed N --failed N --sentiment 1-10 \
+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. Wisdom Frame** — if the session produced a genuine, reusable insight:
+**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"
+```
+
+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.
@@ -166,18 +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 (14/14):
-USE: [#, #] — [reason]
-DECLINE: [#] — [reason]
-N/A: [rest]
+🏹 CAPABILITIES: [format scales by effort level]
 
 ━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]

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
 

package/assets/templates/PAL/README.md

@@ -6,18 +6,21 @@ PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows
 
 **CLAUDE.md** (or the agent equivalent) is the entry point — generated from a template by the CLI installer. It defines execution modes, The Algorithm routing, and the context routing table. The agent loads it natively every session. A SessionStart hook keeps it fresh automatically.
 
-**The PAL home directory (`~/.agents/PAL/`)** contains all system documentation, user context (TELOS), and routing files. The rest of the system lives in the PAL package (`src/`) and the agent's config directory (`~/.claude/`, `~/.config/opencode/`, `~/.cursor/`, or `~/.codex/`).
+**The PAL home directory (`~/.pal/`)** contains all system documentation, user context (TELOS), memory, and tools. The rest of the system lives in the PAL package (`src/`) and the agent's config directory (`~/.claude/`, `~/.config/opencode/`, `~/.cursor/`, or `~/.codex/`).
 
 ## Directory Structure
 
 ```
-~/.agents/PAL/                     # PAL home — user context + routing
-  ALGORITHM.md                     # The execution engine (4-phase)
-  CONTEXT_ROUTING.md               # On-demand context routing table
-  MEMORY_SYSTEM.md                 # Memory guidelines
-  OPINION_TRACKING.md              # Opinion system reference
-  STEERING_RULES.md                # Behavioral rules
-  WORK_TRACKING.md                 # Work tracking reference
+~/.pal/                            # PAL home
+  docs/                            # System documentation (engine-managed)
+    ALGORITHM.md                   # The execution engine (4-phase)
+    CONTEXT_ROUTING.md             # On-demand context routing table
+    MEMORY_SYSTEM.md               # Memory guidelines
+    OPINION_TRACKING.md            # Opinion system reference
+    STEERING_RULES.md              # Behavioral rules
+    WORK_TRACKING.md               # Work tracking reference
+  tools/                           # Agent CLI tools (symlink → repo src/tools/agent/)
+  skills/                          # Installed skills (symlinks → assets/skills/)
   telos/                           # User life context (TELOS)
     MISSION.md, GOALS.md, PROJECTS.md, BELIEFS.md,
     CHALLENGES.md, STRATEGIES.md, IDEAS.md, LEARNED.md,
@@ -124,5 +127,5 @@ PAL is designed to work identically across:
 
 - **Add a skill:** Use the `create-skill` skill or manually create `assets/skills/<name>/SKILL.md`
 - **Add startup files:** Append to `pal-settings.json → loadAtStartup.files`
-- **Add user context:** Create files in `~/.agents/PAL/telos/`
+- **Add user context:** Create files in `~/.pal/telos/`
 - **Toggle dynamic context:** Set keys in `pal-settings.json → dynamicContext` to `false`

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -447,7 +447,7 @@ All paths resolve through `src/hooks/lib/paths.ts`:
 
 | Path | Default | Override |
 |------|---------|----------|
-| PAL home | `~/.agents/PAL` | `PAL_HOME` |
+| PAL home | `~/.pal` | `PAL_HOME` |
 | PAL package | Auto-detected from source | `PAL_PKG` |
 | Claude config | `~/.claude` | `PAL_CLAUDE_DIR` |
 | opencode config | `~/.config/opencode` | `PAL_OPENCODE_DIR` |

package/assets/templates/pal-settings.json

@@ -14,8 +14,8 @@
   "loadAtStartup": {
     "_docs": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
     "files": [
-      "~/.agents/PAL/STEERING_RULES.md",
-      "~/.agents/PAL/telos/PROJECTS.md"
+      "~/.pal/docs/STEERING_RULES.md",
+      "~/.pal/telos/PROJECTS.md"
     ]
   },
   "dynamicContext": {
@@ -27,6 +27,9 @@
     "synthesis": true,
     "signalTrends": true,
     "failurePatterns": true,
-    "activeWork": true
+    "activeWork": true,
+    "projectHistory": true,
+    "sessionIntelligence": true,
+    "handoff": true
   }
 }

package/assets/templates/settings.claude.json

@@ -19,8 +19,8 @@
       "Bash(file //*)",
       "Bash(stat //*)",
       "Bash(readlink //*)",
-      "Bash(bun ~/.agents/skills/*/tools/*.ts *)",
-      "Bash(bun ~/.agents/PAL/tools/*.ts *)"
+      "Bash(bun ~/.pal/skills/*/tools/*.ts *)",
+      "Bash(bun ~/.pal/tools/*.ts *)"
     ]
   },
   "hooks": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -44,6 +44,8 @@
     "prepare": "husky",
     "install:all": "bun run src/cli/index.ts cli install",
     "uninstall": "bun run src/cli/index.ts cli uninstall",
+    "tool:synthesize": "bun run src/tools/agent/synthesize.ts",
+    "tool:thread": "bun run src/tools/agent/thread.ts",
     "tool:analyze": "bun run src/tools/agent/analyze.ts",
     "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",