portable-agent-layer 0.35.0 → 0.36.0

package/README.md

@@ -102,7 +102,7 @@ pal cli install               # all available (default)
 | Claude Code | Full | Yes | Yes | Yes | Yes |
 | opencode | Full | Yes | Yes (plugin) | Yes | Yes |
 | Cursor | Full | Yes | Yes | Yes (injected via hook) | Yes |
-| GitHub Copilot | Full | Yes | Yes | Yes (via copilot-instructions.md) | Yes |
+| GitHub Copilot | Full | Yes | Yes | Yes (via `~/.copilot/instructions/*.instructions.md`) | Yes |
 | Codex | Partial | Yes | No | Yes | No |
 
 ---

package/assets/skills/projects/SKILL.md

@@ -101,7 +101,6 @@ User: "mark <project> as complete"
 - **Don't dump the full JSON.** Summarize. The user can ask for the raw payload.
 - **Don't write without confirming the field choice on ambiguous "store" requests.** A "fact" sticks forever; a "next step" implies follow-up — these are different commitments.
 - **Don't edit the JSON files directly.** Always use the CLI — it timestamps `updated` and keeps the schema valid.
-- **Don't re-introduce `~/.pal/telos/PROJECTS.md`.** That file and its `update-projects.ts` tool are deprecated. The legacy `telos` skill carries a deprecation notice for this reason.
 - **Don't confuse `add-fact` with the `telos` skill's `LEARNED.md` or `IDEAS.md`.** Project facts are scoped to one project; TELOS lessons are cross-cutting.
 
 ## Rules

package/assets/skills/telos/SKILL.md

@@ -1,12 +1,9 @@
 ---
 name: telos
-description: Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, priorities, what do I believe, current obstacles, mission, or strategies.
+description: Personal context management. Use when discussing goals, beliefs, challenges, identity, updating telos, life context, changing a goal, what do I believe, current obstacles, mission, or strategies.
 argument-hint: [area to view or update]
 ---
 
-> ⚠️ **DEPRECATION NOTICE — Project management has moved.**
-> Project tracking is now handled by the `projects` skill, backed by `~/.pal/tools/project.ts` and per-project state in `~/.pal/memory/state/progress/`. **Do not use this skill for projects.** The `PROJECTS.md` references and `update-projects.ts` tool below are legacy and slated for removal — they remain only because the initial setup wizard (`src/cli/setup-telos.ts`) still depends on them. For anything project-related, invoke the `projects` skill.
-
 Manage the user's TELOS files — the persistent personal context that drives PAL.
 
 ## TELOS Files
@@ -16,7 +13,6 @@ All files live in `~/.pal/telos/`:
 | File | Contains |
 |------|----------|
 | `GOALS.md` | Short/medium/long-term goals |
-| `PROJECTS.md` | Active projects, status, priority |
 | `BELIEFS.md` | Core principles and values |
 | `CHALLENGES.md` | Current obstacles |
 | `MISSION.md` | Purpose and direction |
@@ -32,33 +28,18 @@ Read the file directly from `~/.pal/telos/` when the user asks about any area. S
 
 ## Updating
 
-### General TELOS files (append)
-
-For all files except PROJECTS.md — appends content, creates backup, logs the change:
+Appends content, creates backup, logs the change:
 
 ```bash
 bun ~/.pal/skills/telos/tools/update-telos.ts <FILE> "<content>" "<description>"
 ```
 
-### Projects (upsert by ID)
-
-For PROJECTS.md — upserts a row by the ID column. Replaces if the ID exists, appends if new:
-
-```bash
-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`).
-
 ## Routing
 
 | Intent | Action |
 |--------|--------|
-| "what am I working on", "my projects", "priorities" | Read `PROJECTS.md`, summarize active work |
 | "my goals", "what are my goals" | Read `GOALS.md`, present current state |
-| "update goals/projects/beliefs/challenges" | Read the target file, discuss changes with user, then run update tool |
-| "add a project", "new project" | Read `PROJECTS.md`, confirm with user, run update tool |
-| "complete/remove a project" | Read `PROJECTS.md`, confirm with user, update status via tool |
+| "update goals/beliefs/challenges" | Read the target file, discuss changes with user, then run update 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 |
@@ -67,38 +48,12 @@ The ID is the first column of the table. Use short, lowercase, kebab-case slugs
 
 ## 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 ~/.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**
-```
-User: "mark X as complete"
-→ Read PROJECTS.md, find the entry and its ID
-→ Show updated row, confirm
-→ 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
-```
-
-**Example 4: Updating goals**
+**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 with --id to update existing goal entry
+→ Run tool with updated content
 → Remind: CLAUDE.md regenerates next session
 ```
 
@@ -106,8 +61,8 @@ User: "I finished the migration, update my goals"
 
 - **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 create new TELOS files.** Only the 9 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, challenges.
 - **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

package/assets/templates/PAL/ALGORITHM.md

@@ -206,7 +206,32 @@ bun ~/.pal/tools/algorithm-reflect.ts --task "description" --criteria N --passed
   --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:
+**3. Relationship note** — write one Session entry capturing what was done this session:
+
+```bash
+bun ~/.pal/tools/relationship-note.ts --b "description"
+```
+
+- 1-2 sentences, first-person, specific — name the actual system/file/concept worked on
+- ✓ "Debugged the React Query cache split logic and resolved stuck message state in the onFinish callback"
+- ✗ "Helped with memory improvements" — too vague, no system named
+- Skip only if the session was a trivial lookup or typo fix (same rule as step 2)
+
+**4. Handoff note** — if work is unfinished, write what remains so the next session can pick up immediately:
+
+```bash
+# Work still in progress:
+bun ~/.pal/tools/handoff-note.ts --title "what we were doing" --text "what remains, decisions made, next steps"
+
+# Work finished — clear any previous in-progress handoff:
+bun ~/.pal/tools/handoff-note.ts --done --title "what we completed"
+```
+
+- Write if anything is left mid-flight: unfinished implementation, open decision, partially debugged issue
+- Skip if the session fully resolved everything it set out to do
+- `--text` should answer: what's next, what was decided, what to watch out for
+
+**5. 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"
@@ -218,7 +243,7 @@ Only add threads that genuinely need follow-up. Resolve existing threads if this
 bun ~/.pal/tools/thread.ts --resolve --id <id>
 ```
 
-**4. Opinion capture** — scan the conversation for moments where the user:
+**6. Opinion capture** — scan the conversation for moments where the user:
 - Confirmed something you did: "yes exactly", "keep doing that", "10 rated", accepted without pushback
 - Corrected something you did: "no", "don't do that", "stop", "that's not what I meant"
 - Revealed a preference by repeating a pattern (asked for concise answers twice, always checked PAI first, etc.)
@@ -237,7 +262,7 @@ bun ~/.pal/skills/opinion/tools/opinion.ts add "the preference" --category commu
 
 Skip if nothing in the conversation touched preferences or working style.
 
-**5. Wisdom Frame** (Extended+ only) — if the session produced a genuine, reusable insight:
+**7. 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]

package/assets/templates/PAL/PROJECT_LIFECYCLE.md

@@ -0,0 +1,48 @@
+# Project Lifecycle
+
+You (the AI) own the project lifecycle. Project state lives in `~/.pal/memory/state/progress/{slug}.json`, one file per project, managed via `bun ~/.pal/tools/project.ts`. Active projects are auto-injected into every SessionStart context regardless of cwd.
+
+## When to invoke the CLI
+
+**Proactive registration.** When SessionStart context says `💡 cwd <path> is not yet registered; suggest registering if substantive work begins`, AND the user starts substantive work (not just "hi"), surface the suggestion conversationally before the second tool call: *"I see we're in `<basename>` and it's not registered yet — want me to add it as a project?"*
+
+- **Default name** = the FULL last path segment of `cwd`, lowercased. For `/repos/portable-agent-layer` the default is `portable-agent-layer`. Never split on `-`.
+- **Confirm before creating.** Never auto-create without explicit user approval ("yes", "do it", "register").
+- **Capture objectives in conversation.** If the user accepts but doesn't volunteer objectives, ask one short question; or infer from the last few messages and confirm.
+
+**Append as you go.** When the user describes plans, blockers, or decisions during normal work, invoke the relevant subcommand to keep state current — that's the dynamism this system is built for.
+
+| user says | you call |
+|---|---|
+| "let's also add X" / "we should handle Y next" | `add-next <name> "..."` |
+| "we're blocked on Z" / "Z is blocking this" | `add-blocker <name> "..."` |
+| "the objective here is to ship X by Y" | `add-objective <name> "..."` |
+| "the API base is at Z" / "tech stack is Bun + TS" — stable, reference-flavored facts | `add-fact <name> "..."` |
+| "we decided to use A because B" | `add-decision <name> "A" "B"` |
+| "let's pause this" / "shelve it" | `pause <name>` |
+| "we shipped" / "this is done" | `complete <name>` |
+
+**Don't** invoke for fleeting comments, hypotheticals, or things the user is just thinking through. Wait for a clear declarative ("let's add X", "Z is blocking us"), not a question or musing.
+
+## When NOT to suggest registration
+
+- cwd has no project marker (`.git`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc.) — it's a notes folder, not a project.
+- The user is clearly browsing or doing a one-off task.
+- An ancestor of multiple registered projects is the cwd (e.g. `~/Development/git/`) — that's browse mode by design.
+- You're unsure. Err toward not registering.
+
+## CLI cheat sheet
+
+```
+list                                          show all projects
+create [name] [--path PATH] [--objectives X]  register (defaults: name=basename(cwd), path=cwd)
+resume <name>                                 print full project JSON
+complete | archive | pause | unpause <name>   change status
+add-fact | add-objective | add-next | add-blocker <name> "text"
+add-decision <name> "decision" "rationale"
+add-handoff <name> "text"
+rm-fact | rm-objective | rm-next | rm-blocker <name> <index>
+rm <name>                                     delete the project file (rare; prefer archive)
+```
+
+The Stop hook auto-touches `updated` (and optionally writes a `handoff`) whenever cwd resolves to an active project — you don't need to refresh timestamps manually.

package/assets/templates/PAL/README.md

@@ -21,7 +21,7 @@ PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows
   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,
+    MISSION.md, GOALS.md, BELIEFS.md,
     CHALLENGES.md, STRATEGIES.md, IDEAS.md, LEARNED.md,
     MODELS.md, NARRATIVES.md
 

package/assets/templates/PAL/STEERING_RULES.md

@@ -45,3 +45,7 @@ Correct: Review your recent actions → find the mistake → fix it → explain
 **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.
+
+**Don't trust, verify.** When adding a test or asserting a change works, prove it by making it fail first. A test that passes without ever being broken demonstrates nothing — it may be testing the wrong thing or nothing at all. Break it intentionally, confirm it fails for the right reason, then restore it.
+Bad: Add a test, see it green, move on. The test may pass vacuously.
+Correct: Add the test → run it green → break the code it covers → confirm it goes red → restore → now it's a real test.

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -233,6 +233,7 @@ Brief description.
 │                     │    - Work learning capture
 │                     │    - Failure logging
 │                     │    - Reflect trigger check
+│                     │    - Write context digests (semi-static sources)
 │                     │    - Auto-backup
 │                     │    - Count updates
 │                     │    - Tab reset
@@ -357,34 +358,44 @@ Relationship notes (O/B types)
 
 ## Context Loading Architecture
 
-### Two-Layer Design
+### Three-Tier Design
 
-**Static context** (loaded natively by the agent):
-- CLAUDE.md — identity, modes, context routing table
-- Loaded once at session start, always available
+**Tier 1 — Operational** (loaded natively at agent startup):
+- CLAUDE.md / AGENTS.md — identity, modes, context routing table
+- Loaded once per session, always available, never re-fetched
 
-**Dynamic context** (injected by LoadContext hook):
-- Changes per-session, can't live in a static file
-- Injected as `<system-reminder>` block to stdout
+**Tier 2 — Semi-static** (pre-compiled at previous session stop, loaded natively):
+- Self-model, wisdom, opinions, synthesis, failures, steering rules
+- Written to disk by `writeContextDigests()` at Stop time
+- Loaded natively per-agent: `@imports` in CLAUDE.md (Claude Code), `instructions[]` in opencode config, `.mdc` rules in `~/.cursor/rules/` (Cursor), `.instructions.md` in `~/.copilot/instructions/` (Copilot)
+- Content is global/user-level — safe to pre-compile (not project-scoped)
+
+**Tier 3 — Dynamic** (injected fresh each session by LoadContext hook):
+- Handoff notes, session intelligence, open threads, relationship notes, project history
+- Changes per-session or is project-scoped — can't be pre-compiled
+- Injected as `<system-reminder>` block via stdout
 - Each section independently toggleable in `pal-settings.json → dynamicContext`
 
-### Injection Order
+### Semi-Static Registry
+
+All semi-static sources are defined in `src/hooks/lib/semi-static.ts` via `getSemiStaticSources()`. Adding one entry there propagates automatically to every consumer — no other files need to change.
+
+### Dynamic Injection Order
 
 ```
 LoadContext.ts
   │
   ├─► Regenerate CLAUDE.md if template/telos changed
   │
-  └─► Build system-reminder:
+  └─► Build system-reminder (dynamic sections only):
       1. loadAtStartup files (user-configured)
-      2. Crystallized principles (wisdom frames)
-      3. Tracked opinions (≥85% confidence)
-      4. Recent interaction notes (last 2 days)
-      5. Learning digest (this project + other recent)
-      6. Pattern synthesis recommendations
-      7. Signal trends (today/week/trend)
-      8. Failure patterns (last 5 low-rating contexts)
-      9. Active work summary (sessions + projects)
+      2. Handoff note (in-progress work from last session)
+      3. Session intelligence (rating trend, algorithm performance)
+      4. Open threads (current project only)
+      5. Recent interaction notes (last 2 days)
+      6. Active projects
+      7. Project session history (this project)
+      8. Signal trends (today/week/trend)
 ```
 
 ### On-Demand Context
@@ -436,6 +447,9 @@ src/targets/
 ├── cursor/          # Cursor specific
 │   ├── install.ts   # Register hooks + skills in ~/.cursor/
 │   └── uninstall.ts
+├── copilot/         # GitHub Copilot specific
+│   ├── install.ts   # Write instruction files + update VS Code settings
+│   └── uninstall.ts
 └── lib.ts           # Shared: JSON read/write, settings merge, TELOS scaffold
 ```
 
@@ -452,6 +466,7 @@ All paths resolve through `src/hooks/lib/paths.ts`:
 | Claude config | `~/.claude` | `PAL_CLAUDE_DIR` |
 | opencode config | `~/.config/opencode` | `PAL_OPENCODE_DIR` |
 | Cursor config | `~/.cursor` | `PAL_CURSOR_DIR` |
+| Copilot config | `~/.copilot` | `PAL_COPILOT_DIR` |
 | Codex config | `~/.codex` | `PAL_CODEX_DIR` |
 | Agents dir | `~/.agents` | `PAL_AGENTS_DIR` |
 

package/assets/templates/PAL/WORK_TRACKING.md

@@ -4,4 +4,4 @@ PAL tracks your work across sessions in `memory/state/sessions.json` (auto-captu
 
 ## Projects
 
-Projects are managed in `telos/PROJECTS.md` and force-loaded at session startup via `pal-settings.json → loadAtStartup.files`.
+Projects are managed via the `/projects` skill. State lives in `~/.pal/memory/state/progress/{slug}.json`, one file per project. Inspect with `bun ~/.pal/tools/project.ts list`; manage via `~/.pal/docs/PROJECT_LIFECYCLE.md`.

package/assets/templates/pal-settings.json

@@ -13,9 +13,7 @@
   },
   "loadAtStartup": {
     "_docs": "Files force-loaded into session context at startup. Injected as <system-reminder> blocks.",
-    "files": [
-      "~/.pal/docs/STEERING_RULES.md"
-    ]
+    "files": []
   },
   "dynamicContext": {
     "_docs": "Dynamic context sections injected at session start. Set to false to disable.",

package/assets/templates/settings.claude.json

@@ -97,5 +97,6 @@
         ]
       }
     ]
-  }
+  },
+  "autoMemoryEnabled": false
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/setup-telos.ts

@@ -7,72 +7,9 @@
 import { writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import * as clack from "@clack/prompts";
-import { upsertProject } from "../../assets/skills/telos/tools/update-projects";
 import { palHome } from "../hooks/lib/paths";
 import { hasRealContent, SETUP_STEPS, STEP_ORDER } from "../hooks/lib/setup";
 
-function toKebabCase(name: string): string {
-  return name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-|-$/g, "");
-}
-
-async function promptProjectsLoop(): Promise<void> {
-  const addFirst = await clack.confirm({
-    message: "Do you want to add any projects now?",
-    initialValue: true,
-  });
-  if (clack.isCancel(addFirst) || !addFirst) return;
-
-  let addMore = true;
-  while (addMore) {
-    const name = await clack.text({
-      message: "Project name?",
-      placeholder: "e.g. PAL, My SaaS, Work Dashboard",
-    });
-    if (clack.isCancel(name)) return;
-
-    const status = await clack.select({
-      message: "Status?",
-      options: [
-        { value: "Active", label: "Active" },
-        { value: "Planning", label: "Planning" },
-        { value: "Paused", label: "Paused" },
-        { value: "Complete", label: "Complete" },
-      ],
-    });
-    if (clack.isCancel(status)) return;
-
-    const priority = await clack.select({
-      message: "Priority?",
-      options: [
-        { value: "High", label: "High" },
-        { value: "Medium", label: "Medium" },
-        { value: "Low", label: "Low" },
-      ],
-    });
-    if (clack.isCancel(priority)) return;
-
-    const notes = await clack.text({
-      message: "Notes? (optional — leave blank to skip)",
-      placeholder: "e.g. Building the v2 API, blocked on design review",
-    });
-    if (clack.isCancel(notes)) return;
-
-    const id = toKebabCase(name as string);
-    const row = `| ${id} | ${name} | ${status} | ${priority} | ${notes || ""} |`;
-    upsertProject(id, row, `Added ${name} during PAL setup`);
-    clack.log.success(`Added: ${name}`);
-
-    const again = await clack.confirm({
-      message: "Add another project?",
-      initialValue: false,
-    });
-    if (clack.isCancel(again) || !again) addMore = false;
-  }
-}
-
 /** Prompt for missing TELOS context. Skips any step whose file already has real content. */
 export async function promptTelos(): Promise<void> {
   // Skip interactive prompts in non-TTY environments (tests, CI)
@@ -95,25 +32,21 @@ export async function promptTelos(): Promise<void> {
   );
 
   for (const key of pending) {
-    if (key === "projects") {
-      await promptProjectsLoop();
-    } else {
-      const step = SETUP_STEPS[key];
-      const title = key.charAt(0).toUpperCase() + key.slice(1);
-
-      const answer = await clack.text({
-        message: step.question,
-        placeholder: step.hint,
-      });
+    const step = SETUP_STEPS[key];
+    const title = key.charAt(0).toUpperCase() + key.slice(1);
 
-      if (clack.isCancel(answer)) {
-        clack.cancel("Setup cancelled");
-        return;
-      }
+    const answer = await clack.text({
+      message: step.question,
+      placeholder: step.hint,
+    });
 
-      const filePath = resolve(home, step.file);
-      writeFileSync(filePath, `# ${title}\n\n${answer}\n`, "utf-8");
+    if (clack.isCancel(answer)) {
+      clack.cancel("Setup cancelled");
+      return;
     }
+
+    const filePath = resolve(home, step.file);
+    writeFileSync(filePath, `# ${title}\n\n${answer}\n`, "utf-8");
   }
 
   clack.outro("Personal context saved ✓");

package/src/hooks/LoadContext.ts

@@ -9,10 +9,10 @@
  * context directly to ~/.copilot/copilot-instructions.md so it is picked up on load.
  */
 
-import { existsSync, lstatSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { buildClaudeMd, regenerateIfNeeded } from "./lib/claude-md";
-import { buildSystemReminder } from "./lib/context";
+import { type AgentTarget, buildSystemReminder } from "./lib/context";
 import { logDebug, logError } from "./lib/log";
 import { platform } from "./lib/paths";
 
@@ -36,21 +36,33 @@ try {
 
 // --- Context to stdout (or file for Copilot) ---
 try {
-  const reminder = buildSystemReminder();
+  // Determine agent target — controls which sections are skipped (loaded natively instead).
+  let agent: AgentTarget = "claude";
+  if (process.env.PAL_AGENT === "copilot") agent = "copilot";
+  else if (process.env.CURSOR_VERSION) agent = "cursor";
+  const reminder = buildSystemReminder({ agent });
   if (!reminder) process.exit(0);
 
   if (process.env.PAL_AGENT === "copilot") {
-    // Copilot: sessionStart output is ignored — write merged context to copilot-instructions.md
-    const instructionsPath = resolve(platform.copilotDir(), "copilot-instructions.md");
+    // Copilot: semi-static in ~/.copilot/instructions/pal-*.instructions.md (written at stop).
+    // Write AGENTS.md + dynamic context to pal-session.instructions.md on each session start.
+    const instructionsDir = resolve(platform.copilotDir(), "instructions");
+    mkdirSync(instructionsDir, { recursive: true });
     const agentsMd = buildClaudeMd();
     const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
-    if (existsSync(instructionsPath) && lstatSync(instructionsPath).isSymbolicLink()) {
-      unlinkSync(instructionsPath);
+    if (context) {
+      writeFileSync(
+        resolve(instructionsDir, "pal-session.instructions.md"),
+        `---\napplyTo: "**"\n---\n\n${context}`,
+        "utf-8"
+      );
     }
-    writeFileSync(instructionsPath, context, "utf-8");
-    logDebug("LoadContext", `Copilot instructions written: ${context.length} chars`);
+    logDebug(
+      "LoadContext",
+      `Copilot session instructions written: ${context.length} chars`
+    );
   } else if (process.env.CURSOR_VERSION) {
-    // Cursor: no native user-level rules — inject AGENTS.md + dynamic context
+    // Cursor: semi-static in ~/.cursor/rules/pal-context.mdc; inject AGENTS.md + dynamic here
     const agentsMd = buildClaudeMd();
     const context = [agentsMd, reminder].filter(Boolean).join("\n\n");
     process.stdout.write(JSON.stringify({ additional_context: context }));

package/src/hooks/handlers/context-digests.ts

@@ -0,0 +1,74 @@
+/**
+ * Handler: write pre-compiled context digest files for @import / instructions[].
+ *
+ * Runs at session stop so that CLAUDE.md can @import these files natively
+ * at the next session start, keeping hook stdout small.
+ *
+ * Sources are defined in src/hooks/lib/semi-static.ts — add one entry there
+ * to extend coverage to all consumers (CLAUDE.md, opencode, Cursor, Copilot).
+ */
+
+import { existsSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { ensureDir, platform } from "../lib/paths";
+import {
+  copilotFilename,
+  cursorFilename,
+  getSemiStaticSources,
+} from "../lib/semi-static";
+
+export function writeContextDigests(): void {
+  const sources = getSemiStaticSources();
+
+  // Resolve Cursor/Copilot destination dirs once (null if agent not installed)
+  let rulesDir: string | null = null;
+  let instructionsDir: string | null = null;
+
+  try {
+    const cursorDir = platform.cursorDir();
+    if (existsSync(cursorDir)) {
+      rulesDir = ensureDir(resolve(cursorDir, "rules"));
+    }
+  } catch {
+    /* non-fatal */
+  }
+
+  try {
+    const copilotDir = platform.copilotDir();
+    if (existsSync(copilotDir)) {
+      instructionsDir = ensureDir(resolve(copilotDir, "instructions"));
+    }
+  } catch {
+    /* non-fatal */
+  }
+
+  for (const src of sources) {
+    try {
+      const content = src.load();
+      if (!content) continue;
+
+      if (src.writesDigest) {
+        ensureDir(dirname(src.path));
+        writeFileSync(src.path, content, "utf-8");
+      }
+
+      if (rulesDir) {
+        writeFileSync(
+          resolve(rulesDir, cursorFilename(src)),
+          `---\ndescription: ${src.description}\nalwaysApply: true\n---\n\n${content}`,
+          "utf-8"
+        );
+      }
+
+      if (instructionsDir) {
+        writeFileSync(
+          resolve(instructionsDir, copilotFilename(src)),
+          `---\napplyTo: "**"\n---\n\n${content}`,
+          "utf-8"
+        );
+      }
+    } catch {
+      /* non-fatal */
+    }
+  }
+}