portable-agent-layer 0.11.0 → 0.12.0

package/assets/skills/telos/SKILL.md

@@ -16,7 +16,6 @@ All files live in `~/.agents/PAL/telos/`:
 | `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 |
@@ -26,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.
+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
 
@@ -36,25 +35,60 @@ Use the update tool for all changes. It validates the file, creates a backup, ap
 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 |
+| "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

@@ -30,7 +30,6 @@ const VALID_FILES = [
   "CHALLENGES.md",
   "GOALS.md",
   "IDEAS.md",
-  "IDENTITY.md",
   "LEARNED.md",
   "MISSION.md",
   "MODELS.md",

package/assets/templates/AGENTS.md.template

@@ -1,8 +1,62 @@
 # PAL — Portable Agent Layer
 
-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.
+## Identity
 
-When TELOS is populated, you already know the user. When it's empty, first-run setup is required — follow the setup instructions below.
+You are {{IDENTITY_NAME}} ({{IDENTITY_DISPLAY}}). Your user is {{PRINCIPAL_NAME}}. Greet with: {{IDENTITY_CATCHPHRASE}}
+
+## Modes
+
+Every response uses exactly one mode. Classify the request BEFORE responding:
+
+- **Greetings, ratings, acknowledgments** → MINIMAL
+- **Single-step, quick tasks (under 2 minutes of work)** → NATIVE
+- **Everything else** → ALGORITHM
+
+Your first output MUST be the mode header. No freeform output. No skipping this step.
+
+### MINIMAL
+
+For greetings and brief acknowledgments only.
+
+```
+══════════════ PAL ══════════════
+🗣️ {{IDENTITY_NAME}}: [response]
+```
+
+### NATIVE
+
+FOR: Simple tasks that won't take much effort or time. More advanced tasks use ALGORITHM below.
+
+```
+══════════════ PAL | NATIVE ══════════════
+🗒️ TASK: [brief description]
+[work]
+🔄 ITERATION on: [16 words of context if this is a follow-up]
+📃 CONTENT: [Up to 128 lines of the content, if there is any]
+🔧 CHANGE: [what changed, if applicable]
+✅ VERIFY: [how we verified, if applicable]
+🗣️ {{IDENTITY_NAME}}: [brief summary]
+```
+
+On follow-ups, include the ITERATION line. On first response to a new request, omit it.
+
+### ALGORITHM
+
+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.
+
+Start your response with the following header in this mode:
+══════════════ PAL | ALGORITHM ══════════════
+
+---
+
+### Critical Rules (Zero Exceptions)
+
+- **Mandatory output format** — Every response MUST use exactly one of the output formats above (ALGORITHM, NATIVE, or MINIMAL). No freeform output.
+- **Response format before questions** — Always complete the current response format output FIRST, then invoke AskUserQuestion at the end.
+
+---
 
 {{SETUP_PROMPT}}
 ## Context Routing

package/assets/templates/PAL/ALGORITHM.md

@@ -0,0 +1,120 @@
+# The Algorithm
+
+Core: transition from CURRENT STATE to IDEAL STATE using verifiable criteria. Every criterion is atomic, binary testable, and checked off with evidence.
+
+## The Four Phases
+
+All work happens inside these phases. No work outside the phase structure until the Algorithm completes.
+
+### ━━━ 👁️ OBSERVE ━━━ 1/4
+
+Thinking-only. No tool calls except context recovery (Grep/Glob/Read).
+
+**1. Reverse engineer the request:**
+
+🔎 REVERSE ENGINEERING:
+- What did they explicitly say they wanted?
+- What is implied that they wanted but didn't say?
+- What did they explicitly say they don't want?
+- What is obvious they don't want that they didn't say?
+- What are common gotchas for this type of work?
+
+**2. Define verifiable criteria:**
+
+Write atomic criteria — each one is a single testable end-state. Apply the splitting test:
+- **"And"/"With" test**: Joins two verifiable things? → Split them.
+- **Independent failure test**: Part A can pass while Part B fails? → Separate criteria.
+- **Scope word test**: "All", "every", "complete" → Enumerate what "all" means.
+
+Format:
+```
+- [ ] C-1: [8-12 word atomic criterion]
+- [ ] C-2: [8-12 word atomic criterion]
+- [ ] C-A1: [anti-criterion — what must NOT happen]
+```
+
+Include at least one anti-criterion (C-A prefix).
+
+**3. Select capabilities:**
+
+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.
+
+Output:
+```
+🏹 CAPABILITIES: [list each selected skill/tool and why]
+```
+
+### ━━━ 🧠 PLAN ━━━ 2/4
+
+**Pressure test the criteria:**
+
+🧠 RISKS: What are the riskiest assumptions?
+🧠 PREMORTEM: How could this approach fail?
+🧠 PREREQUISITES: What must be true before we start?
+
+Refine criteria if the pressure test reveals gaps. Add criteria for uncovered failure modes.
+
+**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
+
+### ━━━ ⚡ EXECUTE ━━━ 3/4
+
+Do the work. Invoke selected capabilities via tool calls.
+
+- Check off criteria as they're satisfied: `- [x] C-1: ...`
+- If a criterion can't be met, flag it immediately — don't defer to VERIFY
+- Make decisions explicit — state why you chose approach A over B
+
+### ━━━ ✅ VERIFY ━━━ 4/4
+
+No rubber-stamping. Each criterion needs specific evidence.
+
+For EACH criterion:
+- Test that it's actually complete
+- Cite the evidence (test output, file content, diff, tool result)
+- Mark pass or fail
+
+```
+✅ VERIFICATION:
+- [x] C-1: [criterion] — PASS: [evidence]
+- [x] C-2: [criterion] — PASS: [evidence]
+- [ ] C-3: [criterion] — FAIL: [what went wrong]
+- [x] C-A1: [anti-criterion] — PASS: [confirmed not present]
+```
+
+**Capability check:** Confirm every selected capability was actually invoked via tool call. Text output alone does not count.
+
+If any criteria failed, fix and re-verify before completing.
+
+## Output Format
+
+```
+♻️ ALGORITHM ═══════════════════════════
+🗒️ TASK: [brief description]
+
+━━━ 👁️ OBSERVE ━━━ 1/4
+🔎 REVERSE ENGINEERING:
+[reverse engineering output]
+
+📋 CRITERIA:
+[criteria checklist]
+
+🏹 CAPABILITIES: [selected capabilities]
+
+━━━ 🧠 PLAN ━━━ 2/4
+🧠 RISKS: [risks]
+🧠 PREMORTEM: [failure modes]
+📐 APPROACH: [execution plan]
+
+━━━ ⚡ EXECUTE ━━━ 3/4
+[work happens here]
+
+━━━ ✅ VERIFY ━━━ 4/4
+✅ VERIFICATION:
+[criterion-by-criterion evidence]
+
+🔧 CHANGE: [what changed]
+🗣️ {{IDENTITY_NAME}}: [summary]
+```

package/assets/templates/PAL/CONTEXT_ROUTING.md

@@ -10,3 +10,19 @@ Load context on-demand by reading the file at the path listed. Only load what th
 | 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` |
+
+## 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` |

package/assets/templates/PAL/STEERING_RULES.md

@@ -3,21 +3,41 @@
 Behavioral directives — act on these, don't just know them.
 
 **Surgical fixes only.** When debugging, make precise corrections to the broken behavior. Never delete or rearchitect components as a fix. If you believe a component is the root cause, explain your reasoning and ask before removing it.
+Bad: Hook throws error → remove the entire hook. Build fails → delete and rewrite the config.
+Correct: Hook throws error → read it, trace the error, fix the specific line.
 
 **Never assert without verification.** Don't say something "is" a certain way unless you've verified it with your tools. After making changes, verify the result before claiming success. Evidence required — tests, diffs, tool output. Never "Done!" without proof.
+Bad: "The file is correct" without reading it. "Tests pass" without running them. "The deploy succeeded" without checking.
+Correct: Read the file → confirm contents. Run tests → report actual output. Check deploy status → report what you see.
 
 **First principles over bolt-ons.** Most problems are symptoms. Understand → Simplify → Reduce → Add (last resort). Don't accrue technical debt through band-aid solutions.
+Bad: Page slow → add caching layer. Actual issue: bad SQL query.
+Correct: Profile → find the slow query → fix it. No new components.
 
 **Read before modifying.** Understand existing code, imports, and patterns before suggesting changes.
+Bad: Add rate limiting without reading existing middleware → break session management.
+Correct: Read the handler, imports, and patterns first → integrate with what's already there.
 
 **One change when debugging.** Isolate, verify, proceed. Don't change multiple things at once.
+Bad: Page broken → change CSS, API, config, and routes at once. Still broken, now you don't know which change helped or hurt.
+Correct: Dev tools → 404 on API → fix the route → verify → move to next issue.
 
 **Minimal scope.** Only change what was asked. No bonus refactoring, no extra cleanup, no unsolicited improvements.
+Bad: Fix bug on line 42, also refactor the whole file → 200-line diff for a one-line fix.
+Correct: Fix the bug → 1-line diff.
 
 **Ask before destructive actions.** Deletes, force pushes, production deploys — always ask first.
+Bad: "Clean up cruft" → delete 15 files including backups without asking.
+Correct: List candidates → explain consequences → ask approval first.
 
 **Plan means stop.** "Create a plan" = present and STOP. No execution without approval.
+Bad: User says "plan the migration" → you plan it AND start executing it.
+Correct: Present the plan → wait for explicit "go ahead" before writing any code.
 
 **Error recovery.** When told you did something wrong — review the session, identify the violation, fix it, then explain what happened and capture the learning. Don't ask "What did I do wrong?"
+Bad: User says "you broke it" → "What did I do wrong?" or "Can you clarify?"
+Correct: Review your recent actions → find the mistake → fix it → explain what happened.
 
 **Act on what you know.** When tracked opinions or relationship notes reveal user preferences, apply them to your behavior. If you know the user prefers concise responses, be concise. If they prefer manual commits, never offer to commit.
+Bad: Memory says user dislikes verbose summaries → you write a 3-paragraph recap after every change.
+Correct: Memory says user dislikes verbose summaries → you keep the summary to one line.

package/assets/templates/pal-settings.json

@@ -0,0 +1,32 @@
+{
+  "identity": {
+    "ai": {
+      "name": "",
+      "fullName": "",
+      "displayName": "",
+      "catchphrase": ""
+    },
+    "principal": {
+      "name": "",
+      "timezone": ""
+    }
+  },
+  "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"
+    ]
+  },
+  "dynamicContext": {
+    "_docs": "Dynamic context sections injected at session start. Set to false to disable.",
+    "wisdom": true,
+    "opinions": true,
+    "relationship": true,
+    "learningDigest": true,
+    "synthesis": true,
+    "signalTrends": true,
+    "failurePatterns": true,
+    "activeWork": true
+  }
+}

package/assets/templates/settings.claude.json

@@ -1,24 +1,24 @@
 {
   "permissions": {
     "allow": [
-      "Read",
-      "Grep",
-      "Glob",
+      "Read(//*)",
+      "Grep(//*)",
+      "Glob(//*)",
       "WebFetch",
       "WebSearch",
-      "Bash(cat *)",
-      "Bash(head *)",
-      "Bash(tail *)",
-      "Bash(ls *)",
-      "Bash(find *)",
+      "Bash(cat //*)",
+      "Bash(head //*)",
+      "Bash(tail //*)",
+      "Bash(ls //*)",
+      "Bash(find //*)",
       "Bash(grep *)",
-      "Bash(rg *)",
+      "Bash(rg //*)",
       "Bash(wc *)",
-      "Bash(diff *)",
-      "Bash(which *)",
-      "Bash(file *)",
-      "Bash(stat *)",
-      "Bash(readlink *)",
+      "Bash(diff //*)",
+      "Bash(which //*)",
+      "Bash(file //*)",
+      "Bash(stat //*)",
+      "Bash(readlink //*)",
       "Bash(bun ~/.agents/skills/*/tools/*.ts *)"
     ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -42,8 +42,8 @@
     "check-write": "biome check --write",
     "lint-staged": "lint-staged",
     "prepare": "husky",
-    "install:all": "bun run src/cli/install.ts",
-    "uninstall": "bun run src/cli/uninstall.ts",
+    "install:all": "bun run src/cli/index.ts cli install",
+    "uninstall": "bun run src/cli/index.ts cli uninstall",
     "tool:analyze": "bun run src/tools/analyze.ts",
     "tool:opinion": "bun run src/tools/opinion.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",
@@ -73,6 +73,7 @@
     "typescript": "^5.9.0"
   },
   "dependencies": {
+    "@clack/prompts": "^1.1.0",
     "adm-zip": "^0.5.16"
   }
 }

package/src/cli/index.ts

@@ -425,6 +425,13 @@ async function init(args: string[]) {
 }
 
 async function install(targets: { claude: boolean; opencode: boolean }) {
+  // Scaffold TELOS + PAL settings, then prompt for missing identity
+  const { scaffoldTelos, scaffoldPalSettings } = await import("../targets/lib");
+  const { promptIdentity } = await import("./setup-identity");
+  scaffoldTelos();
+  scaffoldPalSettings();
+  await promptIdentity();
+
   if (targets.claude) {
     console.log("━━━ Claude Code ━━━");
     await import("../targets/claude/install");

package/src/cli/setup-identity.ts

@@ -0,0 +1,119 @@
+/**
+ * Interactive identity setup — prompts for missing fields in pal-settings.json.
+ * Called during `pal install`. Skips fields that already have values.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import * as clack from "@clack/prompts";
+import { palHome } from "../hooks/lib/paths";
+
+interface PalSettings {
+  identity?: {
+    ai?: { name?: string; fullName?: string; displayName?: string; catchphrase?: string };
+    principal?: { name?: string; timezone?: string };
+  };
+  [key: string]: unknown;
+}
+
+function settingsPath(): string {
+  return resolve(palHome(), "memory", "pal-settings.json");
+}
+
+function readSettings(): PalSettings {
+  const p = settingsPath();
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(settings: PalSettings): void {
+  writeFileSync(settingsPath(), `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
+}
+
+/** Prompt for missing identity fields. Skips any field that already has a value. */
+export async function promptIdentity(): Promise<void> {
+  // Skip interactive prompts in non-TTY environments (tests, CI)
+  if (!process.stdin.isTTY) return;
+
+  const settings = readSettings();
+  if (!settings.identity) settings.identity = {};
+  if (!settings.identity.ai) settings.identity.ai = {};
+  if (!settings.identity.principal) settings.identity.principal = {};
+
+  const ai = settings.identity.ai;
+  const principal = settings.identity.principal;
+
+  // Check if anything is missing
+  const needsPrincipal = !principal.name;
+  const needsAi = !ai.name;
+  const needsCatchphrase = !ai.catchphrase;
+  const needsTimezone = !principal.timezone;
+
+  if (!needsPrincipal && !needsAi && !needsCatchphrase && !needsTimezone) {
+    clack.log.info("Identity already configured");
+    return;
+  }
+
+  clack.intro("Identity Setup");
+
+  if (needsPrincipal) {
+    const name = await clack.text({
+      message: "What's your name?",
+      placeholder: "e.g. John",
+      validate: (v) => (!v || v.length === 0 ? "Name is required" : undefined),
+    });
+    if (clack.isCancel(name)) {
+      clack.cancel("Setup cancelled");
+      return;
+    }
+    principal.name = name;
+  }
+
+  if (needsAi) {
+    const name = await clack.text({
+      message: "Name your AI",
+      defaultValue: "Assistant",
+      placeholder: "e.g. Jarvis, Friday, Atlas",
+    });
+    if (clack.isCancel(name)) {
+      clack.cancel("Setup cancelled");
+      return;
+    }
+    ai.name = name;
+    ai.fullName = `${name} — Personal AI`;
+    ai.displayName = name.toUpperCase();
+  }
+
+  if (needsCatchphrase) {
+    const catchphrase = await clack.text({
+      message: "Startup catchphrase ({name} gets replaced with AI name)",
+      defaultValue: "{name} here, ready when you are.",
+      placeholder: "{name} online. What's the mission?",
+    });
+    if (clack.isCancel(catchphrase)) {
+      clack.cancel("Setup cancelled");
+      return;
+    }
+    ai.catchphrase = catchphrase;
+  }
+
+  if (needsTimezone) {
+    const guess = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const tz = await clack.text({
+      message: "Your timezone",
+      defaultValue: guess,
+    });
+    if (clack.isCancel(tz)) {
+      clack.cancel("Setup cancelled");
+      return;
+    }
+    principal.timezone = tz;
+  }
+
+  writeSettings(settings);
+  clack.outro("Identity saved ✓");
+}

package/src/hooks/lib/claude-md.ts

@@ -17,7 +17,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
-import { assets, ensureDir, paths, platform } from "./paths";
+import { assets, ensureDir, palHome, paths, platform } from "./paths";
 import { buildSetupPrompt, readSetupState } from "./setup";
 
 const TEMPLATE_PATH = assets.agentsMdTemplate();
@@ -70,8 +70,12 @@ export function needsRebuild(): boolean {
 
   const outputMtime = statSync(outputPath).mtimeMs;
 
-  // Collect source files: template + setup.json + PAL docs
-  const sources: string[] = [TEMPLATE_PATH, resolve(paths.state(), "setup.json")];
+  // Collect source files: template + setup.json + identity + PAL docs
+  const sources: string[] = [
+    TEMPLATE_PATH,
+    resolve(paths.state(), "setup.json"),
+    palSettingsPath(),
+  ];
 
   // Track PAL doc sources for rebuild detection
   const palDocsDir = assets.palDocs();
@@ -84,6 +88,47 @@ export function needsRebuild(): boolean {
   return latestMtime(...sources) > outputMtime;
 }
 
+interface Identity {
+  ai: { name: string; displayName: string; catchphrase: string };
+  principal: { name: string };
+}
+
+const IDENTITY_DEFAULTS: Identity = {
+  ai: { name: "Assistant", displayName: "ASSISTANT", catchphrase: "" },
+  principal: { name: "" },
+};
+
+function palSettingsPath(): string {
+  return resolve(palHome(), "memory", "pal-settings.json");
+}
+
+/** Load identity from pal-settings.json */
+export function loadIdentity(): Identity {
+  const p = palSettingsPath();
+  if (!existsSync(p)) return IDENTITY_DEFAULTS;
+
+  try {
+    const data = JSON.parse(readFileSync(p, "utf-8"));
+    const ai = data.identity?.ai ?? {};
+    const principal = data.identity?.principal ?? {};
+    const name = ai.name || IDENTITY_DEFAULTS.ai.name;
+    const catchphrase = (ai.catchphrase || "").replace("{name}", name);
+
+    return {
+      ai: {
+        name,
+        displayName: ai.displayName || IDENTITY_DEFAULTS.ai.displayName,
+        catchphrase,
+      },
+      principal: {
+        name: principal.name || IDENTITY_DEFAULTS.principal.name,
+      },
+    };
+  } catch {
+    return IDENTITY_DEFAULTS;
+  }
+}
+
 /** Render AGENTS.md from the template using current state */
 export function buildClaudeMd(): string {
   const template = existsSync(TEMPLATE_PATH)
@@ -92,8 +137,14 @@ export function buildClaudeMd(): string {
 
   const state = readSetupState();
   const setupPrompt = state ? buildSetupPrompt(state) : null;
+  const identity = loadIdentity();
 
-  return template.replace("{{SETUP_PROMPT}}", setupPrompt ? `${setupPrompt}\n` : "");
+  return template
+    .replace("{{SETUP_PROMPT}}", setupPrompt ? `${setupPrompt}\n` : "")
+    .replaceAll("{{IDENTITY_NAME}}", identity.ai.name)
+    .replaceAll("{{IDENTITY_DISPLAY}}", identity.ai.displayName)
+    .replaceAll("{{IDENTITY_CATCHPHRASE}}", identity.ai.catchphrase)
+    .replaceAll("{{PRINCIPAL_NAME}}", identity.principal.name);
 }
 
 /** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */

package/src/hooks/lib/context.ts

@@ -4,6 +4,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { parse } from "./frontmatter";
 import { readFailures, readLearnings } from "./learning-store";
@@ -21,6 +22,49 @@ import {
   staleProjects,
 } from "./work-tracking";
 
+interface PalSettings {
+  loadAtStartup?: { files?: string[] };
+  dynamicContext?: Record<string, boolean>;
+}
+
+/** Load pal-settings.json from memory/ */
+function loadPalSettings(): PalSettings {
+  const p = resolve(paths.memory(), "pal-settings.json");
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+/** Check if a dynamic context section is enabled (defaults to true) */
+function isEnabled(settings: PalSettings, key: string): boolean {
+  return settings.dynamicContext?.[key] !== false;
+}
+
+/** Load and concatenate loadAtStartup files */
+function loadStartupFiles(settings: PalSettings): string {
+  const files = settings.loadAtStartup?.files;
+  if (!files || files.length === 0) return "";
+
+  const home = homedir();
+  const sections: string[] = [];
+
+  for (const file of files) {
+    const resolved = file.replace("~", home);
+    if (!existsSync(resolved)) continue;
+    try {
+      const content = readFileSync(resolved, "utf-8").trim();
+      if (content) sections.push(content);
+    } catch {
+      /* skip unreadable files */
+    }
+  }
+
+  return sections.join("\n\n---\n\n");
+}
+
 /** Count lines in a signals JSONL file */
 export function countSignals(filename: string): number {
   const filepath = resolve(paths.signals(), filename);
@@ -321,15 +365,22 @@ export function loadRelationshipContext(): string {
  * things that change per-session and can't live in a static file.
  */
 export function buildSystemReminder(): string {
-  const work = loadActiveWork();
-  const wisdom = loadWisdomContext();
-  const relationship = loadRelationshipContext();
-  const digest = loadLearningDigest();
-  const trends = loadSignalTrends();
-  const failures = loadFailurePatterns();
-  const synthesis = loadSynthesisRecommendations();
-  const opinions = loadOpinionContext();
+  const settings = loadPalSettings();
+  const startup = loadStartupFiles(settings);
+  const work = isEnabled(settings, "activeWork") ? loadActiveWork() : null;
+  const wisdom = isEnabled(settings, "wisdom") ? loadWisdomContext() : "";
+  const relationship = isEnabled(settings, "relationship")
+    ? loadRelationshipContext()
+    : "";
+  const digest = isEnabled(settings, "learningDigest") ? loadLearningDigest() : "";
+  const trends = isEnabled(settings, "signalTrends") ? loadSignalTrends() : "";
+  const failures = isEnabled(settings, "failurePatterns") ? loadFailurePatterns() : "";
+  const synthesis = isEnabled(settings, "synthesis")
+    ? loadSynthesisRecommendations()
+    : "";
+  const opinions = isEnabled(settings, "opinions") ? loadOpinionContext() : "";
   const parts: string[] = [];
+  if (startup) parts.push(startup);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);
   if (relationship) parts.push(relationship);

package/src/hooks/lib/security.ts

@@ -33,6 +33,7 @@ export const HOOK_MANAGED_FILES = [
   "update-available.json",
   "debug.log.prev",
   "opinions.json",
+  "pal-settings.json",
 ];
 
 /** Hook-managed directories — AI must not write to or delete from these */

package/src/hooks/lib/setup.ts

@@ -26,20 +26,8 @@ export interface SetupState {
 const SETUP_STEPS: Record<string, Omit<SetupStep, "done">> = {
   mission: {
     file: "telos/MISSION.md",
-    question: "What's your name and what do you do?",
-    hint: "Write their name, role, and core purpose to telos/MISSION.md",
-  },
-  ai_name: {
-    file: "telos/IDENTITY.md",
-    question:
-      "What would you like to call your AI? (Pick a name — this is how I'll identify myself.)",
-    hint: "Write the chosen AI name and identity to telos/IDENTITY.md with fields: name, fullName (name — Personal AI), displayName (UPPERCASED)",
-  },
-  catchphrase: {
-    file: "telos/IDENTITY.md",
-    question:
-      'What should your AI\'s startup catchphrase be? (e.g. "{name} here, ready to go" — {name} gets replaced with the AI name.)',
-    hint: "Append the catchphrase to telos/IDENTITY.md under a ## Catchphrase heading. Support {name} as a placeholder.",
+    question: "What do you do? What's your role and core purpose?",
+    hint: "Write their role and core purpose to telos/MISSION.md",
   },
   goals: {
     file: "telos/GOALS.md",
@@ -152,8 +140,8 @@ export function buildSetupPrompt(state: SetupState): string | null {
   const lines: string[] = [
     "## IMPORTANT: PAL First-Run Setup Required",
     "",
-    "TELOS files are empty — this user has not been set up yet.",
-    "You MUST start the setup process immediately, regardless of what the user says.",
+    "TELOS files are empty — the user's identity is already configured (via the installer),",
+    "but personal context is still needed. You MUST start the setup process immediately.",
     "Greet them, explain that PAL needs to learn about them to personalize future sessions,",
     "and ask the first remaining question below. Do NOT wait for the user to ask about setup.",
     "",

package/src/targets/claude/install.ts

@@ -19,6 +19,7 @@ import {
   log,
   mergeSettings,
   readJson,
+  scaffoldPalSettings,
   writeJson,
 } from "../lib";
 
@@ -57,6 +58,9 @@ copyAgents();
 const palDocsCount = copyPalDocs();
 log.success(`Installed ${palDocsCount} PAL docs to ~/.agents/PAL/`);
 
+// --- Scaffold PAL settings ---
+scaffoldPalSettings();
+
 // --- Generate ~/.claude/AGENTS.md and symlink ~/.claude/CLAUDE.md → AGENTS.md ---
 regenerateIfNeeded();
 log.success("Generated ~/.config/opencode/AGENTS.md (→ ~/.claude/CLAUDE.md symlink)");

package/src/targets/lib.ts

@@ -155,6 +155,23 @@ export function scaffoldTelos(): void {
   }
 }
 
+// --- PAL settings scaffolding ---
+
+/** Copy pal-settings.json template to memory/ without overwriting */
+export function scaffoldPalSettings(): void {
+  const src = resolve(assets.skills(), "..", "templates", "pal-settings.json");
+  if (!existsSync(src)) return;
+
+  const memDir = resolve(palHome(), "memory");
+  mkdirSync(memDir, { recursive: true });
+
+  const dst = resolve(memDir, "pal-settings.json");
+  if (!existsSync(dst)) {
+    copyFileSync(src, dst);
+    log.info("Created pal-settings.json from template");
+  }
+}
+
 // --- PAL docs (modular context routing files) ---
 
 const PAL_DOCS_DIR = resolve(platform.agentsDir(), "PAL");

package/assets/templates/telos/IDENTITY.md

@@ -1,4 +0,0 @@
-# AI Identity
-
-<!-- The name and identity of your personal AI assistant. -->
-

package/src/cli/install.ts

@@ -1,86 +0,0 @@
-/**
- * PAL — main installer entry point (TypeScript)
- * Usage: bun run install.ts [--claude] [--opencode] [--all]
- * Default: installs for both targets.
- */
-
-import { ensureSetupState, isSetupComplete } from "../hooks/lib/setup";
-import { log, scaffoldTelos } from "../targets/lib";
-
-// --- Parse args ---
-const args = process.argv.slice(2);
-let installClaude = false;
-let installOpencode = false;
-
-if (args.length === 0) {
-  installClaude = true;
-  installOpencode = true;
-}
-
-for (const arg of args) {
-  if (arg === "--claude") installClaude = true;
-  else if (arg === "--opencode") installOpencode = true;
-  else if (arg === "--all") {
-    installClaude = true;
-    installOpencode = true;
-  } else if (arg === "--help" || arg === "-h") {
-    console.log("Usage: bun run install.ts [--claude] [--opencode] [--all]");
-    console.log("");
-    console.log("  --claude    Install hooks/skills for Claude Code");
-    console.log("  --opencode  Install context/skills for opencode");
-    console.log("  --all       Install for both (default)");
-    process.exit(0);
-  } else {
-    log.error(`Unknown option: ${arg}`);
-    process.exit(1);
-  }
-}
-
-// --- Check bun ---
-if (installClaude) {
-  try {
-    Bun.version; // always available in bun
-  } catch {
-    log.error("bun is required: curl -fsSL https://bun.sh/install | bash");
-    process.exit(1);
-  }
-}
-
-console.log("");
-console.log("  ╔═══════════════════════════════════╗");
-console.log("  ║  PAL — Portable Agent Layer       ║");
-console.log("  ║  Non-destructive · Modular        ║");
-console.log("  ╚═══════════════════════════════════╝");
-console.log("");
-
-// --- Scaffold TELOS + seed setup state ---
-scaffoldTelos();
-ensureSetupState();
-
-// --- Run target installers ---
-if (installClaude) {
-  console.log("━━━ Claude Code ━━━");
-  await import("../targets/claude/install");
-  console.log("");
-}
-
-if (installOpencode) {
-  console.log("━━━ opencode ━━━");
-  await import("../targets/opencode/install");
-  console.log("");
-}
-
-log.success("Done. Existing config was preserved — only new entries were added.");
-console.log("");
-log.info("Next steps:");
-
-const state = ensureSetupState();
-if (!isSetupComplete(state)) {
-  log.info("  1. Start a session — PAL will guide you through first-run setup");
-  log.info("  2. Or fill in telos/*.md manually, then re-run install.ts");
-} else {
-  log.info("  1. Fill in telos/*.md with your info (if not already done)");
-  log.info("  2. Re-run install.ts to regenerate context files");
-}
-log.info("  3. Add skills by dropping .md files into skills/");
-log.info("  4. Uninstall: bun run uninstall.ts [--claude] [--opencode]");

package/src/cli/uninstall.ts

@@ -1,45 +0,0 @@
-/**
- * PAL — main uninstaller entry point (TypeScript)
- * Usage: bun run uninstall.ts [--claude] [--opencode] [--all]
- */
-
-import { palHome } from "../hooks/lib/paths";
-import { log } from "../targets/lib";
-
-const args = process.argv.slice(2);
-let removeClaude = false;
-let removeOpencode = false;
-
-if (args.length === 0) {
-  removeClaude = true;
-  removeOpencode = true;
-}
-
-for (const arg of args) {
-  if (arg === "--claude") removeClaude = true;
-  else if (arg === "--opencode") removeOpencode = true;
-  else if (arg === "--all") {
-    removeClaude = true;
-    removeOpencode = true;
-  } else if (arg === "--help" || arg === "-h") {
-    console.log("Usage: bun run uninstall.ts [--claude] [--opencode] [--all]");
-    process.exit(0);
-  } else {
-    log.error(`Unknown option: ${arg}`);
-    process.exit(1);
-  }
-}
-
-if (removeClaude) {
-  console.log("━━━ Claude Code ━━━");
-  await import("../targets/claude/uninstall");
-  console.log("");
-}
-
-if (removeOpencode) {
-  console.log("━━━ opencode ━━━");
-  await import("../targets/opencode/uninstall");
-  console.log("");
-}
-
-log.success(`PAL uninstalled. Your TELOS, skills, and memory are still in ${palHome()}.`);