pi-extensions 0.1.9

package/.ralph/import-cc-codex.md

@@ -0,0 +1,31 @@
+# import-cc-codex implementation loop
+
+## Goals
+- Implement Phase 1 `pi --import <path>` CLI flow.
+- Build Claude Code + Codex transcript parsing + mapping.
+- Add usage exclusion + context estimate for imported ranges.
+- Preserve metadata, ordering, and labels per spec.
+- Prepare for Phase 2 `/import` selector (no UI changes yet unless required).
+
+## Checklist (interleaved)
+1. Wire CLI flags + import entrypoint (imp-001)
+2. Implement parsers + mapping utilities (imp-002)
+3. Add import metadata + labeling (imp-004)
+4. Implement usage exclusion + context estimate (imp-003)
+5. Add tool-output redaction (imp-005)
+6. **Reflection**: summarize what works/doesn’t, adjust plan
+7. **Cleanup**: refactor/simplify, remove redundancy, improve clarity
+8. **Testing**: targeted tests for parsers/mapping
+9. Repeat (1–5) as needed
+10. **Reflection** (periodic)
+11. **Cleanup** (periodic)
+12. **Testing**: broaden scope; move toward E2E once CLI flow is stable
+
+## Acceptance
+- `pi --import <path>` creates a valid Pi session JSONL and opens it.
+- Imported sessions are labeled, metadata preserved, and usage excluded.
+- Deterministic context % works before first new assistant response.
+- Tests cover key parsing and mapping behavior.
+
+## Progress Log
+- 2026-01-13: Wired `--import`/`--source` CLI flags, added core import module for CC/Codex parsing + mapping, updated README CLI docs, and added startup status banner plumbing. Pending: tests, usage exclusion/context estimate, redaction opt-out.

package/.ralph/import-cc-codex.state.json

@@ -0,0 +1,14 @@
+{
+  "name": "import-cc-codex",
+  "taskFile": ".ralph/import-cc-codex.md",
+  "iteration": 1,
+  "maxIterations": 50,
+  "itemsPerIteration": 3,
+  "reflectEvery": 3,
+  "reflectInstructions": "REFLECTION CHECKPOINT\n\nPause and reflect on your progress:\n1. What has been accomplished so far?\n2. What's working well?\n3. What's not working or blocking progress?\n4. Should the approach be adjusted?\n5. What are the next priorities?\n\nUpdate the task file with your reflection, then continue working.",
+  "active": false,
+  "status": "completed",
+  "startedAt": "2026-01-13T13:32:49.696Z",
+  "lastReflectionAt": 0,
+  "completedAt": "2026-01-13T13:33:21.479Z"
+}

package/.ralph/mario-not-impl.md

@@ -0,0 +1,69 @@
+# Badlogic Game Implementation
+
+## Goal
+Implement `/badlogic-game` per `badlogic-game/spec.md` with deterministic core logic, reliable tests (unit + integration + E2E), and incremental milestones.
+
+## Loop Protocol
+- Work on 1 feature per iteration (small, shippable, testable).
+- Each iteration MUST:
+  - Add or extend at least 1 regression test (unit or integration).
+  - Add or extend at least 1 E2E scripted scenario (headless run with golden frame or state snapshot).
+  - Record verification evidence (commands + results) in Reflection.
+- After each story, do a quick refactor pass to keep code concise and modular.
+- Keep diffs small; commit once the feature passes verification.
+- Self-reflect every iteration and adjust plan if needed.
+
+## Refactor Principles
+- Keep files under ~400 LOC; split by responsibility (engine, render, entities, input, levels).
+- Prefer pure functions and deterministic state updates; avoid hidden globals.
+- Consolidate constants (tiles, glyphs, physics) in one place.
+- Eliminate duplication by extracting helpers and data tables.
+
+## Typing Strategy
+- Use `// @ts-check` + JSDoc types for strict checks without a build step.
+- Add `badlogic-game/tsconfig.json` with `checkJs`, `strict`, `noEmit`.
+- Typecheck command: `npx tsc --noEmit -p badlogic-game/tsconfig.json` (record results).
+
+## Verifiability Standard
+- Unit tests: physics tick, jump apex, collision resolution, serialization.
+- Integration tests: deterministic input sequences -> expected positions/collisions/state transitions.
+- E2E tests: scripted input -> render frames or HUD/state snapshots; compare to golden fixtures.
+- Manual checks: milestone smoke test in a live TUI session (M1..M4).
+
+## Feature Checklist
+- [x] Story 0: Test harness + engine/core separation
+  - Decide runner (node:test vs custom) and structure
+  - Deterministic RNG + headless renderer
+- [x] Quality: strict typing setup (tsconfig + @ts-check)
+- [x] Story 1: Core loop (map, movement, gravity, collision, camera clamp, Level 1)
+- [x] Story 2: Enemies + stomp + hazards
+- [x] Story 3: Blocks + coins + scoring + HUD
+- [x] Story 4: Power-ups (mushroom) + big state
+- [x] Story 5: Save/resume + pause/quit
+- [x] Story 6: Polish (particles, text cues, camera dead-zone)
+- [x] Docs + wiring: `/badlogic-game` command registration and README update
+- [ ] Final: full test run + manual E2E checks; update harness logs
+
+## Milestone Gates
+- [x] M1: Story 1 + test harness + E2E scenario
+- [x] M2: Story 2 + tests + E2E scenario
+- [x] M3: Story 3/4 + tests + E2E scenario
+- [ ] M4: Story 5/6 + tests + manual run
+
+## References
+- Spec: `badlogic-game/spec.md`
+- Existing WIP: `arcade/wip/badlogic-game.ts`
+
+## Reflection (Iteration 35)
+1. What has been accomplished so far?
+   - Added invuln save regression test and paused cue frame E2E fixture.
+   - Verification: `node --test badlogic-game/tests/*.test.js` -> 77 pass; `npx tsc --noEmit -p badlogic-game/tsconfig.json` -> ok.
+2. What's working well?
+   - Invuln persistence and paused cue overlay are covered deterministically.
+3. What's not working or blocking progress?
+   - Manual M4 run still pending (interactive UI required).
+4. Should the approach be adjusted?
+   - No; keep manual run as final gate.
+5. What are the next priorities?
+   - M4 manual run.
+   - Final: update harness logs.

package/.ralph/mario-not-impl.state.json

@@ -0,0 +1,14 @@
+{
+  "name": "badlogic-game-impl",
+  "taskFile": ".ralph/badlogic-game-impl.md",
+  "iteration": 35,
+  "maxIterations": 80,
+  "itemsPerIteration": 1,
+  "reflectEvery": 1,
+  "reflectInstructions": "REFLECTION CHECKPOINT\n\nPause and reflect on your progress:\n1. What has been accomplished so far?\n2. What's working well?\n3. What's not working or blocking progress?\n4. Should the approach be adjusted?\n5. What are the next priorities?\n\nUpdate the task file with your reflection, then continue working.",
+  "active": false,
+  "status": "completed",
+  "startedAt": "2026-01-09T03:55:16.633Z",
+  "lastReflectionAt": 35,
+  "completedAt": "2026-01-09T09:09:36.947Z"
+}

package/.ralph/mario-not-spec.md

@@ -0,0 +1,163 @@
+# Badlogic Game Spec
+
+## Goal
+Create a comprehensive Mario-style TUI extension spec in `badlogic-game/spec.md` with list-based outline and detailed, verifiable content. Each sub-subsection must include design intent + implementation guidance so it is directly actionable for engineering.
+
+## Requirements
+- Use list items + subitems for the outline and content.
+- Draft section-by-section via ralph loop iterations.
+- Iterate at the level of every sub-subsection (e.g., target size, scroll rules).
+- After completing each sub-section (e.g., Player Experience & Feel), reflect on coherence and adjust if needed.
+- Final coherence reflection at end of doc; adjust as needed.
+- Commit after each major section: Core Gameplay, Presentation, Tech + Delivery.
+
+## Planned Sections
+1) Core Gameplay
+  - Player Experience & Feel
+    - Time-to-fun / quick boot
+    - Pace / difficulty ramp
+    - Failure/respawn cadence
+    - Feel targets vs SMB1
+  - Controls & Input
+    - Key mapping
+    - Input buffering
+    - Pausing/quitting/restart
+  - Game Loop & States
+    - State machine
+    - Transitions
+  - Level Design
+    - Tile palette
+    - Layout rules
+    - Level 1 (short)
+  - Entities & Interactions
+    - Player
+    - Blocks
+    - Items
+    - Enemies
+    - Hazards
+  - Physics & Movement
+    - Gravity / accel / friction
+    - Jump (variable)
+    - Collision resolution
+
+2) Presentation
+  - Camera & Viewport
+    - Target size
+    - Scroll rules
+    - Bounds/edges
+  - Rendering & Palette
+    - 256-color plan
+    - Glyphs / tiles
+  - HUD & Scoring
+    - HUD layout
+    - Score/lives/time/coins
+  - FX & Feedback (optional)
+    - Particles
+    - Text cues
+
+3) Tech + Delivery
+  - Save/Resume
+    - Autosave cadence
+    - Persisted fields
+    - Resume behavior
+  - Technical Architecture
+    - Data model
+    - Update order
+    - Collision handling
+    - Input handling
+    - Serialization
+  - Feature Stories & Sequencing
+  - Test Plan
+  - Milestones
+  - Open Questions
+
+## Checklist
+- [x] Create `badlogic-game/spec.md` with list-based scaffold
+- [x] Draft Core Gameplay subsections (reflect + adjust after each)
+  - [x] Player Experience & Feel > Time-to-fun / quick boot
+  - [x] Player Experience & Feel > Pace / difficulty ramp
+  - [x] Player Experience & Feel > Failure/respawn cadence
+  - [x] Player Experience & Feel > Feel targets vs SMB1
+  - [x] Controls & Input > Key mapping
+  - [x] Controls & Input > Input buffering
+  - [x] Controls & Input > Pausing/quitting/restart
+  - [x] Game Loop & States > State machine
+  - [x] Game Loop & States > Transitions
+  - [x] Level Design > Tile palette
+  - [x] Level Design > Layout rules
+  - [x] Level Design > Level 1 (short)
+  - [x] Entities & Interactions > Player
+  - [x] Entities & Interactions > Blocks
+  - [x] Entities & Interactions > Items
+  - [x] Entities & Interactions > Enemies
+  - [x] Entities & Interactions > Hazards
+  - [x] Physics & Movement > Gravity / accel / friction
+  - [x] Physics & Movement > Jump (variable)
+  - [x] Physics & Movement > Collision resolution
+- [x] Commit Core Gameplay section
+- [x] Draft Presentation subsections (reflect + adjust after each)
+  - [x] Camera & Viewport > Target size
+  - [x] Camera & Viewport > Scroll rules
+  - [x] Camera & Viewport > Bounds/edges
+  - [x] Rendering & Palette > 256-color plan
+  - [x] Rendering & Palette > Glyphs / tiles
+  - [x] HUD & Scoring > HUD layout
+  - [x] HUD & Scoring > Score/lives/time/coins
+  - [x] FX & Feedback > Particles
+  - [x] FX & Feedback > Text cues
+- [x] Commit Presentation section
+- [x] Draft Tech + Delivery subsections (reflect + adjust after each)
+  - [x] Save/Resume > Autosave cadence
+  - [x] Save/Resume > Persisted fields
+  - [x] Save/Resume > Resume behavior
+  - [x] Technical Architecture > Data model
+  - [x] Technical Architecture > Update order
+  - [x] Technical Architecture > Collision handling
+  - [x] Technical Architecture > Input handling
+  - [x] Technical Architecture > Serialization
+  - [x] Feature Stories & Sequencing
+  - [x] Test Plan
+  - [x] Milestones
+  - [x] Open Questions
+- [x] Commit Tech + Delivery section
+- [x] Final coherence reflection; adjust doc as needed
+
+## Reflection (Iteration 46)
+1. What has been accomplished so far?
+   - Completed final coherence pass; clarified player glyph sizing.
+2. What's working well?
+   - All sections align on sizes, timings, and rendering constraints.
+3. What's not working or blocking progress?
+   - Nothing blocked.
+4. Should the approach be adjusted?
+   - No; spec is complete.
+5. What are the next priorities?
+   - None; ready to stop loop.
+
+## Coherence Checks
+- Physics & Movement: collision ordering aligns with stomp and head-bump rules.
+
+## Tech + Delivery Coherence Check (Iteration 45)
+- Save cadence aligns with resume behavior and pause/quit rules.
+- Data model fields cover persisted fields list.
+- Serialization versioning aligns with SaveState schema.
+- Stories/milestones reflect the same delivery order.
+
+## Final Coherence Check (Iteration 46)
+- Glyph sizing clarified for player big state (1x3 tiles).
+- Run modifier, jump buffer, and physics values are consistent.
+- Save/resume flow matches input and state machine rules.
+
+## Presentation Coherence Check (Iteration 32)
+- Viewport size supports HUD lines and 2-char tile grid without wrap.
+- Camera rules align with bounds clamp and no vertical scroll assumption.
+- Glyphs/tiles use ASCII and 2-char width consistent with rendering plan.
+- HUD fields (score/coins/lives/time) match scoring spec values.
+- FX cues are lightweight and don't conflict with HUD overlays.
+
+## Core Gameplay Coherence Check (Iteration 22)
+- Consistency: run modifier defined in Controls; referenced in Physics and feel targets.
+- Timing: coyote/jump buffer values consistent between Input and Jump sections.
+- Level 1: pacing, layout rules, and hazards align with speed/jump targets.
+- Death loop: hazards, enemies, and respawn cadence agree on invuln timing and lives.
+- Tile palette: blocks/items/hazards align with symbols; ensure rendering uses same glyphs.

package/.ralph/mario-not-spec.state.json

@@ -0,0 +1,14 @@
+{
+  "name": "badlogic-game-spec",
+  "taskFile": ".ralph/badlogic-game-spec.md",
+  "iteration": 46,
+  "maxIterations": 60,
+  "itemsPerIteration": 1,
+  "reflectEvery": 1,
+  "reflectInstructions": "REFLECTION CHECKPOINT\n\nPause and reflect on your progress:\n1. What has been accomplished so far?\n2. What's working well?\n3. What's not working or blocking progress?\n4. Should the approach be adjusted?\n5. What are the next priorities?\n\nUpdate the task file with your reflection, then continue working.",
+  "active": false,
+  "status": "completed",
+  "startedAt": "2026-01-08T22:35:44.127Z",
+  "lastReflectionAt": 46,
+  "completedAt": "2026-01-08T23:04:52.947Z"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Mustier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# pi-extensions
+
+Personal extensions for the [Pi coding agent](https://github.com/badlogic/pi-mono).
+
+## Extensions
+
+| Extension | Description |
+|-----------|-------------|
+| [/files](files-widget/) | In-terminal file browser and viewer. Navigate files, view diffs, select code, send comments to agent - all without leaving Pi |
+| [tab-status](tab-status/) | Manage as many parallel sessions as your mind can handle. Terminal tab indicators for <br>✅ done / 🚧 stuck / 🛑 timed out |
+| [ralph-wiggum](ralph-wiggum/) | Run arbitrarily-long tasks without diluting model attention. Flat version without subagents like [ralph-loop](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop) |
+| [agent-guidance](agent-guidance/) | Switch between Claude/Codex/Gemini with model-specific guidance (CLAUDE.md, CODEX.md, GEMINI.md) |
+| [/usage](usage-extension/) | 📊 Usage statistics dashboard. See cost, tokens, and messages by provider/model across Today, This Week, All Time |
+| [/paste](raw-paste/) | Paste editable text, not [paste #1 +21 lines]. Running `/paste` with optional keybinding |
+| [/code](code-actions/) | Pick code blocks or inline snippets from assistant messages to copy, insert, or run with `/code` |
+| [arcade](arcade/) | Play minigames while your tests run: 👾 sPIce-invaders, 👻 picman, 🏓 ping, 🧩 tetris, 🍄 mario-not |
+
+## Install (pi package manager)
+
+```bash
+pi install git:github.com/tmustier/pi-extensions
+```
+
+To enable only a subset, replace the package entry in `~/.pi/agent/settings.json` with a filtered one:
+
+```json
+{
+  "packages": [
+    {
+      "source": "git:github.com/tmustier/pi-extensions",
+      "extensions": ["files-widget/index.ts"]
+    }
+  ]
+}
+```
+
+## Quick Setup
+
+If you keep a local clone, add extensions to your `~/.pi/agent/settings.json`:
+
+```json
+{
+  "extensions": [
+    "~/pi-extensions/files-widget",
+    "~/pi-extensions/tab-status/tab-status.ts",
+    "~/pi-extensions/arcade/spice-invaders.ts",
+    "~/pi-extensions/arcade/ping.ts",
+    "~/pi-extensions/arcade/picman.ts",
+    "~/pi-extensions/arcade/tetris.ts",
+    "~/pi-extensions/arcade/mario-not/mario-not.ts",
+    "~/pi-extensions/ralph-wiggum",
+    "~/pi-extensions/agent-guidance/agent-guidance.ts",
+    "~/pi-extensions/raw-paste",
+    "~/pi-extensions/code-actions",
+    "~/pi-extensions/usage-extension"
+  ]
+}
+```
+
+For agent-guidance, also run the setup script:
+```bash
+cd ~/pi-extensions/agent-guidance && ./setup.sh
+```
+
+See each extension's README for details.

package/RELEASING.md

@@ -0,0 +1,34 @@
+# Releasing
+
+This repo hosts multiple extensions. Releases are per extension, not per repo.
+
+## Tag Format
+
+Use `extension-name/vX.Y.Z` (example: `usage-extension/v0.1.2`).
+
+## Steps
+
+1. Update the extension's `CHANGELOG.md`.
+2. Optionally refresh compatibility notes in the extension README.
+3. Bump the extension version in its `package.json` and bump the repo version in the root `package.json` (ensure it is not marked `private` when publishing).
+4. Publish to npm (both packages):
+
+```bash
+# Extension-specific package
+cd <extension-dir>
+npm publish --access public
+
+# Repo-wide pi-extensions package
+cd <repo-root>
+npm publish --access public
+```
+
+5. Tag and push the release:
+
+```bash
+git tag -a usage-extension/v0.1.2 -m "usage-extension v0.1.2"
+git push origin usage-extension/v0.1.2
+```
+
+4. Create a GitHub release from the tag and paste the notes from the changelog.
+

package/agent-guidance/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0 - 2026-01-13
+- Initial release.

package/agent-guidance/README.md

@@ -0,0 +1,102 @@
+# agent-guidance
+
+Loads provider-specific context files (CLAUDE.md, CODEX.md, GEMINI.md) based on current model, supplementing Pi's AGENTS.md loading.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    S1["~/.pi/agent/"] --> B
+    S2["project/"] --> B
+    
+    subgraph Core ["Pi Core"]
+        B["Load all AGENTS.md<br/><sub>(CLAUDE.md as fallback)</sub>"]
+    end
+    
+    subgraph Ext ["agent-guidance extension"]
+        B --> C{Which provider?}
+        C -->|Anthropic| D[+ CLAUDE.md]
+        C -->|OpenAI/Codex| E[+ CODEX.md]
+        C -->|Google| F[+ GEMINI.md]
+    end
+    
+    D --> G[System Prompt]
+    E --> G
+    F --> G
+```
+
+| Provider | File |
+|----------|------|
+| Anthropic | CLAUDE.md |
+| OpenAI / Codex | CODEX.md |
+| Google | GEMINI.md |
+
+### Pi Core behavior
+
+Pi Core loads `AGENTS.md` from `~/.pi/agent/` and project directories (walking up from cwd). Falls back to `CLAUDE.md` if no `AGENTS.md` exists.
+
+### What this extension adds
+
+For each directory, loads the provider-specific file if:
+- `AGENTS.md` exists (so core didn't load the provider file as fallback)
+- Content differs from `AGENTS.md` (handles copy scenario)
+
+## Install
+
+### Pi package manager
+
+```bash
+pi install npm:@tmustier/pi-agent-guidance
+```
+
+```bash
+pi install git:github.com/tmustier/pi-extensions
+```
+
+Then filter to just this extension in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": [
+    {
+      "source": "git:github.com/tmustier/pi-extensions",
+      "extensions": ["agent-guidance/agent-guidance.ts"]
+    }
+  ]
+}
+```
+
+### Local clone (setup script)
+
+```bash
+./setup.sh
+```
+
+Links the extension to `~/.pi/agent/extensions/` and helps you set up `AGENTS.md`.
+
+## Templates
+
+Starter templates in `templates/`:
+- `CLAUDE.md` - Claude-specific guidelines
+- `CODEX.md` - OpenAI guidelines (from [steipete/agent-scripts](https://github.com/steipete/agent-scripts))
+- `GEMINI.md` - Gemini guidelines
+
+Install with:
+```bash
+ln -s ~/pi-extensions/agent-guidance/templates/CLAUDE.md ~/.pi/agent/
+```
+
+## Configuration (Optional)
+
+Create `~/.pi/agent/agent-guidance.json`:
+
+```json
+{
+  "providers": { "anthropic": ["CLAUDE.md"] },
+  "models": { "claude-3-5*": ["CLAUDE-3-5.md"] }
+}
+```
+
+## Changelog
+
+See `CHANGELOG.md`.

package/agent-guidance/agent-guidance.ts

@@ -0,0 +1,147 @@
+/**
+ * agent-guidance - Provider-specific context loading
+ *
+ * Loads CLAUDE.md, CODEX.md, or GEMINI.md based on current model provider,
+ * supplementing Pi Core's AGENTS.md loading.
+ *
+ * Deduplication:
+ * - Skips if core already loaded the file (CLAUDE.md fallback case)
+ * - Skips if AGENTS.md has identical content
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const PROVIDER_FILES: Record<string, string[]> = {
+	anthropic: ["CLAUDE.md"],
+	openai: ["CODEX.md"],
+	"openai-codex": ["CODEX.md"],
+	"github-copilot": ["CODEX.md"],
+	google: ["GEMINI.md"],
+	"google-gemini-cli": ["GEMINI.md"],
+	"google-antigravity": ["GEMINI.md"],
+	"google-vertex": ["GEMINI.md"],
+};
+
+interface Config {
+	providers?: Record<string, string[]>;
+	models?: Record<string, string[]>;
+}
+
+function loadConfig(agentDir: string): Config {
+	const configPath = path.join(agentDir, "agent-guidance.json");
+	if (fs.existsSync(configPath)) {
+		try {
+			return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+		} catch {
+			return {};
+		}
+	}
+	return {};
+}
+
+function globMatch(pattern: string, value: string): boolean {
+	return new RegExp(`^${pattern.replace(/\*/g, ".*")}$`, "i").test(value);
+}
+
+function getCandidateFiles(modelId: string | undefined, provider: string, config: Config): string[] {
+	// Model-specific patterns take priority
+	if (modelId && config.models) {
+		for (const [pattern, files] of Object.entries(config.models)) {
+			if (globMatch(pattern, modelId)) return files;
+		}
+	}
+	// Then provider config, then defaults
+	return config.providers?.[provider] ?? PROVIDER_FILES[provider] ?? [];
+}
+
+function shouldLoad(dir: string, providerFile: string): boolean {
+	const providerPath = path.join(dir, providerFile);
+	if (!fs.existsSync(providerPath)) return false;
+
+	const agentsPath = path.join(dir, "AGENTS.md");
+	const agentsExists = fs.existsSync(agentsPath);
+	const claudeExists = fs.existsSync(path.join(dir, "CLAUDE.md"));
+
+	// What did core load? (prefers AGENTS.md, falls back to CLAUDE.md)
+	const coreLoaded = agentsExists ? "AGENTS.md" : claudeExists ? "CLAUDE.md" : null;
+	if (coreLoaded === providerFile) return false;
+
+	// Skip if identical to AGENTS.md
+	if (agentsExists) {
+		try {
+			const agentsContent = fs.readFileSync(agentsPath, "utf-8");
+			const providerContent = fs.readFileSync(providerPath, "utf-8");
+			if (agentsContent === providerContent) return false;
+		} catch {
+			// Proceed with loading
+		}
+	}
+
+	return true;
+}
+
+function getDirectories(cwd: string, agentDir: string): string[] {
+	const dirs: string[] = [];
+	const seen = new Set<string>();
+
+	// Global agent dir first
+	if (fs.existsSync(agentDir)) {
+		dirs.push(agentDir);
+		seen.add(agentDir);
+	}
+
+	// Walk up from cwd to root
+	let current = cwd;
+	const ancestors: string[] = [];
+	while (true) {
+		if (!seen.has(current)) {
+			ancestors.unshift(current);
+			seen.add(current);
+		}
+		const parent = path.resolve(current, "..");
+		if (parent === current) break;
+		current = parent;
+	}
+
+	dirs.push(...ancestors);
+	return dirs;
+}
+
+export default function agentGuidance(pi: ExtensionAPI) {
+	const agentDir = path.join(process.env.HOME || "", ".pi", "agent");
+	const config = loadConfig(agentDir);
+
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const provider = ctx.model?.provider;
+		if (!provider) return;
+
+		const candidates = getCandidateFiles(ctx.model?.id, provider, config);
+		if (candidates.length === 0) return;
+
+		const files: Array<{ path: string; content: string }> = [];
+
+		for (const dir of getDirectories(ctx.cwd, agentDir)) {
+			for (const filename of candidates) {
+				if (shouldLoad(dir, filename)) {
+					const filePath = path.join(dir, filename);
+					try {
+						files.push({ path: filePath, content: fs.readFileSync(filePath, "utf-8") });
+					} catch {
+						// Skip unreadable files
+					}
+				}
+			}
+		}
+
+		if (files.length === 0) return;
+
+		let append = "\n\n# Provider-Specific Context\n\n";
+		for (const { path: p, content } of files) {
+			append += `## ${p}\n\n${content}\n\n`;
+		}
+
+		return { systemPromptAppend: append };
+	});
+}