switch release workflow to binary only

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.astro/content.d.ts

@@ -0,0 +1,154 @@
+declare module 'astro:content' {
+	export interface RenderResult {
+		Content: import('astro/runtime/server/index.js').AstroComponentFactory;
+		headings: import('astro').MarkdownHeading[];
+		remarkPluginFrontmatter: Record<string, any>;
+	}
+	interface Render {
+		'.md': Promise<RenderResult>;
+	}
+
+	export interface RenderedContent {
+		html: string;
+		metadata?: {
+			imagePaths: Array<string>;
+			[key: string]: unknown;
+		};
+	}
+
+	type Flatten<T> = T extends { [K: string]: infer U } ? U : never;
+
+	export type CollectionKey = keyof DataEntryMap;
+	export type CollectionEntry<C extends CollectionKey> = Flatten<DataEntryMap[C]>;
+
+	type AllValuesOf<T> = T extends any ? T[keyof T] : never;
+
+	export type ReferenceDataEntry<
+		C extends CollectionKey,
+		E extends keyof DataEntryMap[C] = string,
+	> = {
+		collection: C;
+		id: E;
+	};
+
+	export type ReferenceLiveEntry<C extends keyof LiveContentConfig['collections']> = {
+		collection: C;
+		id: string;
+	};
+
+	export function getCollection<C extends keyof DataEntryMap, E extends CollectionEntry<C>>(
+		collection: C,
+		filter?: (entry: CollectionEntry<C>) => entry is E,
+	): Promise<E[]>;
+	export function getCollection<C extends keyof DataEntryMap>(
+		collection: C,
+		filter?: (entry: CollectionEntry<C>) => unknown,
+	): Promise<CollectionEntry<C>[]>;
+
+	export function getLiveCollection<C extends keyof LiveContentConfig['collections']>(
+		collection: C,
+		filter?: LiveLoaderCollectionFilterType<C>,
+	): Promise<
+		import('astro').LiveDataCollectionResult<LiveLoaderDataType<C>, LiveLoaderErrorType<C>>
+	>;
+
+	export function getEntry<
+		C extends keyof DataEntryMap,
+		E extends keyof DataEntryMap[C] | (string & {}),
+	>(
+		entry: ReferenceDataEntry<C, E>,
+	): E extends keyof DataEntryMap[C]
+		? Promise<DataEntryMap[C][E]>
+		: Promise<CollectionEntry<C> | undefined>;
+	export function getEntry<
+		C extends keyof DataEntryMap,
+		E extends keyof DataEntryMap[C] | (string & {}),
+	>(
+		collection: C,
+		id: E,
+	): E extends keyof DataEntryMap[C]
+		? string extends keyof DataEntryMap[C]
+			? Promise<DataEntryMap[C][E]> | undefined
+			: Promise<DataEntryMap[C][E]>
+		: Promise<CollectionEntry<C> | undefined>;
+	export function getLiveEntry<C extends keyof LiveContentConfig['collections']>(
+		collection: C,
+		filter: string | LiveLoaderEntryFilterType<C>,
+	): Promise<import('astro').LiveDataEntryResult<LiveLoaderDataType<C>, LiveLoaderErrorType<C>>>;
+
+	/** Resolve an array of entry references from the same collection */
+	export function getEntries<C extends keyof DataEntryMap>(
+		entries: ReferenceDataEntry<C, keyof DataEntryMap[C]>[],
+	): Promise<CollectionEntry<C>[]>;
+
+	export function render<C extends keyof DataEntryMap>(
+		entry: DataEntryMap[C][string],
+	): Promise<RenderResult>;
+
+	export function reference<
+		C extends
+			| keyof DataEntryMap
+			// Allow generic `string` to avoid excessive type errors in the config
+			// if `dev` is not running to update as you edit.
+			// Invalid collection names will be caught at build time.
+			| (string & {}),
+	>(
+		collection: C,
+	): import('astro/zod').ZodPipe<
+		import('astro/zod').ZodString,
+		import('astro/zod').ZodTransform<
+			C extends keyof DataEntryMap
+				? {
+						collection: C;
+						id: string;
+					}
+				: never,
+			string
+		>
+	>;
+
+	type ReturnTypeOrOriginal<T> = T extends (...args: any[]) => infer R ? R : T;
+	type InferEntrySchema<C extends keyof DataEntryMap> = import('astro/zod').infer<
+		ReturnTypeOrOriginal<Required<ContentConfig['collections'][C]>['schema']>
+	>;
+	type ExtractLoaderConfig<T> = T extends { loader: infer L } ? L : never;
+	type InferLoaderSchema<
+		C extends keyof DataEntryMap,
+		L = ExtractLoaderConfig<ContentConfig['collections'][C]>,
+	> = L extends { schema: import('astro/zod').ZodSchema }
+		? import('astro/zod').infer<L['schema']>
+		: any;
+
+	type DataEntryMap = {
+		
+	};
+
+	type ExtractLoaderTypes<T> = T extends import('astro/loaders').LiveLoader<
+		infer TData,
+		infer TEntryFilter,
+		infer TCollectionFilter,
+		infer TError
+	>
+		? { data: TData; entryFilter: TEntryFilter; collectionFilter: TCollectionFilter; error: TError }
+		: { data: never; entryFilter: never; collectionFilter: never; error: never };
+	type ExtractEntryFilterType<T> = ExtractLoaderTypes<T>['entryFilter'];
+	type ExtractCollectionFilterType<T> = ExtractLoaderTypes<T>['collectionFilter'];
+	type ExtractErrorType<T> = ExtractLoaderTypes<T>['error'];
+
+	type LiveLoaderDataType<C extends keyof LiveContentConfig['collections']> =
+		LiveContentConfig['collections'][C]['schema'] extends undefined
+			? ExtractDataType<LiveContentConfig['collections'][C]['loader']>
+			: import('astro/zod').infer<
+					Exclude<LiveContentConfig['collections'][C]['schema'], undefined>
+				>;
+	type LiveLoaderEntryFilterType<C extends keyof LiveContentConfig['collections']> =
+		ExtractEntryFilterType<LiveContentConfig['collections'][C]['loader']>;
+	type LiveLoaderCollectionFilterType<C extends keyof LiveContentConfig['collections']> =
+		ExtractCollectionFilterType<LiveContentConfig['collections'][C]['loader']>;
+	type LiveLoaderErrorType<C extends keyof LiveContentConfig['collections']> = ExtractErrorType<
+		LiveContentConfig['collections'][C]['loader']
+	>;
+
+	export type ContentConfig = never;
+	export type LiveContentConfig = never;
+}

.astro/types.d.ts

@@ -0,0 +1,2 @@
+/// <reference types="astro/client" />
+/// <reference path="content.d.ts" />

.env.example

@@ -6,3 +6,21 @@ FEYNMAN_THINKING=medium
 
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
+OPENROUTER_API_KEY=
+ZAI_API_KEY=
+KIMI_API_KEY=
+MINIMAX_API_KEY=
+MINIMAX_CN_API_KEY=
+MISTRAL_API_KEY=
+GROQ_API_KEY=
+XAI_API_KEY=
+CEREBRAS_API_KEY=
+HF_TOKEN=
+OPENCODE_API_KEY=
+AI_GATEWAY_API_KEY=
+AZURE_OPENAI_API_KEY=
+
+RUNPOD_API_KEY=
+MODAL_TOKEN_ID=
+MODAL_TOKEN_SECRET=

.feynman/SYSTEM.md

@@ -9,7 +9,7 @@ Operating rules:
 - State uncertainty explicitly.
 - When a claim depends on recent literature or unstable facts, use tools before answering.
 - When discussing papers, cite title, year, and identifier or URL when possible.
-- Use the alpha-backed research tools for academic paper search, paper reading, paper Q&A, repository inspection, and persistent annotations.
+- Use the `alpha` CLI for academic paper search, paper reading, paper Q&A, repository inspection, and persistent annotations.
 - Use `web_search`, `fetch_content`, and `get_search_content` first for current topics: products, companies, markets, regulations, software releases, model availability, model pricing, benchmarks, docs, or anything phrased as latest/current/recent/today.
 - For mixed topics, combine both: use web sources for current reality and paper sources for background literature.
 - Never answer a latest/current question from arXiv or alpha-backed paper search alone.
@@ -30,7 +30,6 @@ Operating rules:
 - Use the visualization packages when a chart, diagram, or interactive widget would materially improve understanding. Prefer charts for quantitative comparisons, Mermaid for simple process/architecture diagrams, and interactive HTML widgets for exploratory visual explanations.
 - Persistent memory is package-backed. Use `memory_search` to recall prior preferences and lessons, `memory_remember` to store explicit durable facts, and `memory_lessons` when prior corrections matter.
 - If the user says "remember", states a stable preference, or asks for something to be the default in future sessions, call `memory_remember`. Do not just say you will remember it.
-- Session recall is package-backed. Use `session_search` when the user references prior work, asks what has been done before, or when you suspect relevant past context exists.
 - Feynman is intended to support always-on research work. Use the scheduling package when recurring or deferred work is appropriate instead of telling the user to remember manually.
 - Use `schedule_prompt` for recurring scans, delayed follow-ups, reminders, and periodic research jobs.
 - If the user asks you to remind, check later, run something nightly, or keep watching something over time, call `schedule_prompt`. Do not just promise to do it later.
@@ -38,11 +37,9 @@ Operating rules:
 - Prefer the smallest investigation or experiment that can materially reduce uncertainty before escalating to broader work.
 - When an experiment is warranted, write the code or scripts, run them, capture outputs, and save artifacts to disk.
 - Before pausing long-running work, update the durable state on disk first: plan artifact, `CHANGELOG.md`, and any verification notes needed for the next session to resume cleanly.
-- Before recommending an execution environment, consider the system resources shown in the header (CPU, RAM, GPU, Docker availability). Recommend Docker when isolation on the current machine helps, and say explicitly when the workload exceeds local capacity. Do not suggest GPU workloads locally if no GPU is detected.
 - Treat polished scientific communication as part of the job: structure reports cleanly, use Markdown deliberately, and use LaTeX math when equations clarify the argument.
 - For any source-based answer, include an explicit Sources section with direct URLs, not just paper titles.
 - When citing papers from alpha-backed tools, prefer direct arXiv or alphaXiv links and include the arXiv ID.
-- After writing a polished artifact, use `preview_file` only when the user wants review or export. Prefer browser preview by default; use PDF only when explicitly requested.
 - Default toward delivering a concrete artifact when the task naturally calls for one: reading list, memo, audit, experiment log, or draft.
 - For user-facing workflows, produce exactly one canonical durable Markdown artifact unless the user explicitly asks for multiple deliverables.
 - Do not create extra user-facing intermediate markdown files just because the workflow has multiple reasoning stages.

.feynman/agents/researcher.md

@@ -21,7 +21,7 @@ You are Feynman's evidence-gathering subagent.
 1. **Start wide.** Begin with short, broad queries to map the landscape. Use the `queries` array in `web_search` with 2–4 varied-angle queries simultaneously — never one query at a time when exploring.
 2. **Evaluate availability.** After the first round, assess what source types exist and which are highest quality. Adjust strategy accordingly.
 3. **Progressively narrow.** Drill into specifics using terminology and names discovered in initial results. Refine queries, don't repeat them.
-4. **Cross-source.** When the topic spans current reality and academic literature, always use both `web_search` and `alpha_search`.
+4. **Cross-source.** When the topic spans current reality and academic literature, always use both `web_search` and the `alpha` CLI (`alpha search`).
 
 Use `recencyFilter` on `web_search` for fast-moving topics. Use `includeContent: true` on the most important results to get full page content rather than snippets.
 

.feynman/settings.json

@@ -1,5 +1,6 @@
 {
   "packages": [
+    "npm:@companion-ai/alpha-hub",
     "npm:pi-subagents",
     "npm:pi-btw",
     "npm:pi-docparser",

.github/workflows/publish.yml

@@ -13,8 +13,7 @@ jobs:
     runs-on: blacksmith-4vcpu-ubuntu-2404
     outputs:
       version: ${{ steps.version.outputs.version }}
-      should_publish: ${{ steps.version.outputs.should_publish }}
-      should_build_release: ${{ steps.version.outputs.should_build_release }}
+      should_release: ${{ steps.version.outputs.should_release }}
     steps:
       - uses: actions/checkout@v6
       - uses: actions/setup-node@v5
@@ -22,49 +21,26 @@ jobs:
           node-version: 24.14.0
       - id: version
         shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          CURRENT=$(npm view @companion-ai/feynman version 2>/dev/null || echo "0.0.0")
           LOCAL=$(node -p "require('./package.json').version")
           echo "version=$LOCAL" >> "$GITHUB_OUTPUT"
-          if [ "$CURRENT" != "$LOCAL" ]; then
-            echo "should_publish=true" >> "$GITHUB_OUTPUT"
-            echo "should_build_release=true" >> "$GITHUB_OUTPUT"
-          elif [ "${GITHUB_EVENT_NAME}" = "workflow_dispatch" ]; then
-            echo "should_publish=false" >> "$GITHUB_OUTPUT"
-            echo "should_build_release=true" >> "$GITHUB_OUTPUT"
+          if gh release view "v$LOCAL" >/dev/null 2>&1; then
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
           else
-            echo "should_publish=false" >> "$GITHUB_OUTPUT"
-            echo "should_build_release=false" >> "$GITHUB_OUTPUT"
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
           fi
 
-  publish-npm:
-    needs: version-check
-    if: needs.version-check.outputs.should_publish == 'true'
-    runs-on: blacksmith-4vcpu-ubuntu-2404
-    permissions:
-      contents: read
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v5
-        with:
-          node-version: 24.14.0
-          registry-url: https://registry.npmjs.org
-      - run: npm ci --ignore-scripts
-      - run: npm run build
-      - run: npm test
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
   build-native-bundles:
     needs: version-check
-    if: needs.version-check.outputs.should_build_release == 'true'
+    if: needs.version-check.outputs.should_release == 'true'
     strategy:
       fail-fast: false
       matrix:
         include:
           - id: linux-x64
-            os: ubuntu-latest
+            os: blacksmith-4vcpu-ubuntu-2404
           - id: darwin-x64
             os: macos-15-intel
           - id: darwin-arm64
@@ -97,7 +73,8 @@ jobs:
           $tmp = Join-Path $env:RUNNER_TEMP ("feynman-smoke-" + [guid]::NewGuid().ToString("N"))
           New-Item -ItemType Directory -Path $tmp | Out-Null
           Expand-Archive -LiteralPath "dist/release/feynman-$version-win32-x64.zip" -DestinationPath $tmp -Force
-          & "$tmp/feynman-$version-win32-x64/feynman.cmd" --help | Select-Object -First 20
+          $bundleRoot = Join-Path $tmp "feynman-$version-win32-x64"
+          & (Join-Path $bundleRoot "feynman.cmd") --help | Select-Object -First 20
       - uses: actions/upload-artifact@v4
         with:
           name: native-${{ matrix.id }}
@@ -106,9 +83,8 @@ jobs:
   release-github:
     needs:
       - version-check
-      - publish-npm
       - build-native-bundles
-    if: needs.version-check.outputs.should_build_release == 'true' && needs.build-native-bundles.result == 'success' && (needs.publish-npm.result == 'success' || needs.publish-npm.result == 'skipped')
+    if: needs.version-check.outputs.should_release == 'true' && needs.build-native-bundles.result == 'success'
     runs-on: blacksmith-4vcpu-ubuntu-2404
     permissions:
       contents: write
@@ -119,6 +95,7 @@ jobs:
           merge-multiple: true
       - shell: bash
         env:
+          GH_REPO: ${{ github.repository }}
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VERSION: ${{ needs.version-check.outputs.version }}
         run: |
@@ -127,7 +104,8 @@ jobs:
             gh release edit "v$VERSION" \
               --title "v$VERSION" \
               --notes "Standalone Feynman bundles for native installation." \
-              --draft=false
+              --draft=false \
+              --target "$GITHUB_SHA"
           else
             gh release create "v$VERSION" release-assets/* \
               --title "v$VERSION" \

.nvmrc

@@ -0,0 +1 @@
+20.19.0

CHANGELOG.md

@@ -14,3 +14,156 @@ Use this file to track chronology, not release notes. Keep entries short, factua
 - Failed / learned: ...
 - Blockers: ...
 - Next: ...
+
+### 2026-03-25 00:00 local — scaling-laws
+
+- Objective: Set up a deep research workflow for scaling laws.
+- Changed: Created plan artifact at `outputs/.plans/scaling-laws.md`; defined 4 disjoint researcher dimensions and acceptance criteria.
+- Verified: Read `CHANGELOG.md` and checked prior memory for related plan `scaling-laws-implications`.
+- Failed / learned: No prior run-specific changelog entries existed beyond the template.
+- Blockers: Waiting for user confirmation before launching researcher round 1.
+- Next: On confirmation, spawn 4 parallel researcher subagents and begin evidence collection.
+
+### 2026-03-25 00:30 local — scaling-laws (T4 inference/time-scale pass)
+
+- Objective: Complete T4 on inference/test-time scaling and reasoning-time compute, scoped to 2023–2026.
+- Changed: Wrote `notes/scaling-laws-research-inference.md`; updated `outputs/.plans/scaling-laws.md` to mark T4 done and log the inference-scaling verification pass.
+- Verified: Cross-read 13 primary/official sources covering Tree-of-Thoughts, PRMs, repeated sampling, compute-optimal test-time scaling, provable laws, o1, DeepSeek-R1, s1, verifier failures, Anthropic extended thinking, and OpenAI reasoning API docs.
+- Failed / learned: OpenAI blog fetch for `learning-to-reason-with-llms` returned malformed content, so the note leans on the o1 system card and API docs instead of that blog post.
+- Blockers: T2 and T5 remain open before final synthesis; no single unified law for inference-time scaling emerged from public sources.
+- Next: Complete T5 implications synthesis, then reconcile T3/T4 with foundational T2 before drafting the cited brief.
+
+### 2026-03-25 11:20 local — scaling-laws (T6 draft synthesis)
+
+- Objective: Synthesize the four research notes into a single user-facing draft brief for the scaling-laws workflow.
+- Changed: Wrote `outputs/.drafts/scaling-laws-draft.md` with an executive summary, curated reading list, qualitative meta-analysis, core-paper comparison table, explicit training-vs-inference distinction, and numbered inline citations with direct-URL sources.
+- Verified: Cross-checked the draft against `notes/scaling-laws-research-foundations.md`, `notes/scaling-laws-research-revisions.md`, `notes/scaling-laws-research-inference.md`, and `notes/scaling-laws-research-implications.md` to ensure the brief explicitly states the literature is too heterogeneous for a pooled effect-size estimate.
+- Failed / learned: The requested temp-run `context.md` and `plan.md` were absent, so the synthesis used `outputs/.plans/scaling-laws.md` plus the four note files as the working context.
+- Blockers: Citation/claim verification pass still pending; this draft should be treated as pre-verification.
+- Next: Run verifier/reviewer passes, then promote the draft into the final cited brief and provenance sidecar.
+
+### 2026-03-25 11:28 local — scaling-laws (final brief + pdf)
+
+- Objective: Deliver a paper guide and qualitative meta-analysis on AI scaling laws.
+- Changed: Finalized `outputs/scaling-laws.md` and sidecar `outputs/scaling-laws.provenance.md`; rendered preview PDF at `outputs/scaling-laws.pdf`; updated plan ledger and verification log in `outputs/.plans/scaling-laws.md`.
+- Verified: Ran a reviewer pass recorded in `notes/scaling-laws-verification.md`; spot-checked key primary papers via alpha-backed reads for Kaplan 2020, Chinchilla 2022, and Snell 2024; confirmed PDF render output exists.
+- Failed / learned: A pooled statistical meta-analysis would be misleading because the literature mixes heterogeneous outcomes, scaling axes, and evaluation regimes; final deliverable uses a qualitative meta-analysis instead.
+- Blockers: None for this brief.
+- Next: If needed, extend into a narrower sub-survey (e.g. only pretraining laws, only inference-time scaling, or only post-Chinchilla data-quality revisions).
+
+### 2026-03-25 14:52 local — skills-only-install
+
+- Objective: Let users download the Feynman research skills without installing the full terminal runtime.
+- Changed: Added standalone skills-only installers at `scripts/install/install-skills.sh` and `scripts/install/install-skills.ps1`; synced website-public copies; documented user-level and repo-local install flows in `README.md`, `website/src/content/docs/getting-started/installation.md`, and `website/src/pages/index.astro`.
+- Verified: Ran `sh -n scripts/install/install-skills.sh`; ran `node scripts/sync-website-installers.mjs`; ran `cd website && npm run build`; executed `sh scripts/install/install-skills.sh --dir <tmp>` and confirmed extracted `SKILL.md` files land in the target directory.
+- Failed / learned: PowerShell installer behavior was not executed locally because PowerShell is not installed in this environment.
+- Blockers: None for the Unix installer flow; Windows remains syntax-only by inspection.
+- Next: If users want this exposed more prominently, add a dedicated docs/reference page and a homepage-specific skills-only CTA instead of a text link.
+
+### 2026-03-26 18:08 PDT — installer-release-unification
+
+- Objective: Remove the moving `edge` installer channel and unify installs on tagged releases only.
+- Changed: Updated `scripts/install/install.sh`, `scripts/install/install.ps1`, `scripts/install/install-skills.sh`, and `scripts/install/install-skills.ps1` so the default target is the latest tagged release, latest-version resolution uses public GitHub release pages instead of `api.github.com`, and explicit `edge` requests now fail with a removal message; removed the `release-edge` job from `.github/workflows/publish.yml`; updated `README.md` and `website/src/content/docs/getting-started/installation.md`; re-synced `website/public/install*`.
+- Verified: Ran `sh -n` on the Unix installer copies; confirmed `sh scripts/install/install.sh edge` and `sh scripts/install/install-skills.sh edge --dir <tmp>` fail with the intended removal message; executed `sh scripts/install/install.sh` into temp dirs and confirmed the installed binary reports `0.2.14`; executed `sh scripts/install/install-skills.sh --dir <tmp>` and confirmed extracted `SKILL.md` files; ran `cd website && npm run build`.
+- Failed / learned: The install failure was caused by unauthenticated GitHub API rate limiting on the `edge` path, so renaming channels without removing the API dependency would not have fixed the root cause.
+- Blockers: `npm run build` still emits a pre-existing duplicate-content warning for `getting-started/installation`; the build succeeds.
+- Next: If desired, remove the now-unused `stable` alias too and clean up the duplicate docs-content warning separately.
+
+### 2026-03-27 11:58 PDT — release-0.2.15
+
+- Objective: Make the non-Anthropic subagent/auth fixes and contributor-guide updates releasable to tagged-install users instead of leaving them only on `main`.
+- Changed: Bumped the package version from `0.2.14` to `0.2.15` in `package.json` and `package-lock.json`; updated pinned installer examples in `README.md` and `website/src/content/docs/getting-started/installation.md`; aligned the local-development docs example to the npm-based root workflow; added `CONTRIBUTING.md` plus the bundled `skills/contributing/SKILL.md`.
+- Verified: Confirmed the publish workflow keys off `package.json` versus the currently published npm version; confirmed local `npm test`, `npm run typecheck`, and `npm run build` pass before the release bump.
+- Failed / learned: The open subagent issue is fixed on `main` but still user-visible on tagged installs until a fresh release is cut.
+- Blockers: Need the GitHub publish workflow to finish successfully before the issue can be honestly closed as released.
+- Next: Push `0.2.15`, monitor the publish workflow, then update and close the relevant GitHub issue/PR once the release is live.
+
+### 2026-03-28 15:15 PDT — pi-subagents-agent-dir-compat
+
+- Objective: Debug why tagged installs can still fail subagent/auth flows after `0.2.15` when users are not on Anthropic.
+- Changed: Added `scripts/lib/pi-subagents-patch.mjs` plus type declarations and wired `scripts/patch-embedded-pi.mjs` to rewrite vendored `pi-subagents` runtime files so they resolve user-scoped paths from `PI_CODING_AGENT_DIR` instead of hardcoded `~/.pi/agent`; added `tests/pi-subagents-patch.test.ts`.
+- Verified: Materialized `.feynman/npm`, inspected the shipped `pi-subagents@0.11.11` sources, confirmed the hardcoded `~/.pi/agent` paths in `index.ts`, `agents.ts`, `artifacts.ts`, `run-history.ts`, `skills.ts`, and `chain-clarify.ts`; ran `node scripts/patch-embedded-pi.mjs`; ran `npm test`, `npm run typecheck`, and `npm run build`.
+- Failed / learned: The earlier `0.2.15` fix only proved that Feynman exported `PI_CODING_AGENT_DIR` to the top-level Pi child; it did not cover vendored extension code that still hardcoded `.pi` paths internally.
+- Blockers: Users still need a release containing this patch before tagged installs benefit from it.
+- Next: Cut the next release and verify a tagged install exercises subagents without reading from `~/.pi/agent`.
+
+### 2026-03-28 21:46 PDT — release-0.2.16
+
+- Objective: Ship the vendored `pi-subagents` agent-dir compatibility fix to tagged installs.
+- Changed: Bumped the package version from `0.2.15` to `0.2.16` in `package.json` and `package-lock.json`; updated pinned installer examples in `README.md` and `website/src/content/docs/getting-started/installation.md`.
+- Verified: Re-ran `npm test`, `npm run typecheck`, and `npm run build`; ran `cd website && npm run build`; ran `npm pack` and confirmed the `0.2.16` tarball includes the new `scripts/lib/pi-subagents-patch.*` files.
+- Failed / learned: An initial local `build:native-bundle` check failed because `npm pack` and `build:native-bundle` were run in parallel, and `prepack` intentionally removes `dist/release`; rerunning `npm run build:native-bundle` sequentially succeeded.
+- Blockers: None in the repo; publishing still depends on the GitHub workflow running on the bumped version.
+- Next: Push the `0.2.16` release bump and monitor npm/GitHub release publication.
+
+### 2026-03-31 10:45 PDT — pi-maintenance-issues-prs
+
+- Objective: Triage open Pi-related issues/PRs, fix the concrete package update regression, and refresh Pi dependencies against current upstream releases.
+- Changed: Pinned direct package-manager operations (`feynman update`, `feynman packages install`) to Feynman's npm prefix by exporting `FEYNMAN_NPM_PREFIX`, `NPM_CONFIG_PREFIX`, and `npm_config_prefix` before invoking Pi's `DefaultPackageManager`; bumped `@mariozechner/pi-ai` and `@mariozechner/pi-coding-agent` from `0.62.0` to `0.64.0`; adapted `src/model/registry.ts` to the new `ModelRegistry.create(...)` factory; integrated PR #15's `/feynman-model` command on top of current `main`.
+- Verified: Ran `npm test`, `npm run typecheck`, and `npm run build` successfully after the dependency bump and PR integration; confirmed upstream `pi-coding-agent@0.64.0` still uses `npm install -g` for user-scope package updates, so the Feynman-side prefix fix is still required.
+- Failed / learned: PR #14 is a stale branch with no clean merge path against current `main`; the only user-facing delta is the ValiChord prompt/skill addition, and the branch also carries unrelated release churn plus demo-style material, so it was not merged in this pass.
+- Blockers: None in the local repo state; remote merge/push still depends on repository credentials and branch policy.
+- Next: If remote write access is available, commit and push the validated maintenance changes, then close issue #22 and resolve PR #15 as merged while leaving PR #14 unmerged pending a cleaned-up, non-promotional resubmission.
+
+### 2026-03-31 12:05 PDT — pi-backlog-cleanup-round-2
+
+- Objective: Finish the remaining high-confidence open tracker items after the Pi 0.64.0 upgrade instead of leaving the issue list half-reconciled.
+- Changed: Added a Windows extension-loader patch helper so Feynman rewrites Pi extension imports to `file://` URLs on Windows before interactive startup; added `/commands`, `/tools`, and `/capabilities` discovery commands and surfaced `/hotkeys` plus `/service-tier` in help metadata; added explicit service-tier support via `feynman model tier`, `--service-tier`, status/doctor output, and a provider-payload hook that passes `service_tier` only to supported OpenAI/OpenAI Codex/Anthropic models; added Exa provider recognition to Feynman's web-search status layer and vendored `pi-web-access`.
+- Verified: Ran `npm test`, `npm run typecheck`, and `npm run build`; smoke-imported the modified vendored `pi-web-access` modules with `node --import tsx`.
+- Failed / learned: The remaining ValiChord PR is still stale and mixes a real prompt/skill update with unrelated branch churn; it is a review/triage item, not a clean merge candidate.
+- Blockers: No local build blockers remain; issue/PR closure still depends on the final push landing on `main`.
+- Next: Push the verified cleanup commit, then close issues fixed by the dependency bump plus the new discoverability/service-tier/Windows patches, and close the stale ValiChord PR explicitly instead of leaving it open indefinitely.
+
+### 2026-04-09 09:37 PDT — windows-startup-import-specifiers
+
+- Objective: Fix Windows startup failures where `feynman` exits before the Pi child process initializes.
+- Changed: Converted the Node preload module paths passed via `node --import` in `src/pi/launch.ts` to `file://` specifiers using a new `toNodeImportSpecifier(...)` helper in `src/pi/runtime.ts`; expanded `scripts/patch-embedded-pi.mjs` so it also patches the bundled workspace copy of Pi's extension loader when present.
+- Verified: Added a regression test in `tests/pi-runtime.test.ts` covering absolute-path to `file://` conversion for preload imports; ran `npm test`, `npm run typecheck`, and `npm run build`.
+- Failed / learned: The raw Windows `ERR_UNSUPPORTED_ESM_URL_SCHEME` stack is more consistent with Node rejecting the child-process `--import C:\\...` preload before Pi starts than with a normal in-app extension load failure.
+- Blockers: Windows runtime execution was not available locally, so the fix is verified by code path inspection and automated tests rather than an actual Windows shell run.
+- Next: Ask the affected user to reinstall or update to the next published package once released, and confirm the Windows REPL now starts from a normal PowerShell session.
+
+### 2026-04-09 11:02 PDT — tracker-hardening-pass
+
+- Objective: Triage the open repo backlog, land the highest-signal fixes locally, and add guardrails against stale promotional workflow content.
+- Changed: Hardened Windows launch paths in `bin/feynman.js`, `scripts/build-native-bundle.mjs`, and `scripts/install/install.ps1`; set npm prefix overrides earlier in `scripts/patch-embedded-pi.mjs`; added a `pi-web-access` runtime patch helper plus `FEYNMAN_WEB_SEARCH_CONFIG` env wiring so bundled web search reads the same `~/.feynman/web-search.json` that doctor/status report; taught `src/pi/web-access.ts` to honor the legacy `route` key; fixed bundled skill references and expanded the skills-only installers/docs to ship the prompt and guidance files those skills reference; added regression tests for config paths, catalog snapshot edges, skill-path packaging, `pi-web-access` patching, and blocked promotional content.
+- Verified: Ran `npm test`, `npm run typecheck`, and `npm run build` successfully after the full maintenance pass.
+- Failed / learned: The skills-only install issue was not just docs drift; the shipped `SKILL.md` files referenced prompt paths that only made sense after installation, so the repo needed both path normalization and packaging changes.
+- Blockers: Remote issue/PR closure and merge actions still depend on the final reviewed branch state being pushed.
+- Next: Push the validated fixes, close the duplicate Windows/reporting issues they supersede, reject the promotional ValiChord PR explicitly, and then review whether the remaining docs-only or feature PRs should be merged separately.
+
+### 2026-04-09 10:28 PDT — verification-and-security-pass
+
+- Objective: Run a deeper install/security verification pass against the post-cleanup `0.2.17` tree instead of assuming the earlier targeted fixes covered the shipped artifacts.
+- Changed: Reworked `extensions/research-tools/header.ts` to use `@mariozechner/pi-tui` width-aware helpers for truncation/wrapping so wide Unicode text does not overflow custom header rows; changed `src/pi/launch.ts` to stop mirroring child crash signals back onto the parent process and instead emit a conventional exit code; added `FEYNMAN_INSTALL_SKILLS_ARCHIVE_URL` overrides to the skills installers for pre-release smoke testing; aligned root and website dependency trees with patched transitive versions using npm `overrides`; fixed `src/pi/web-access.ts` so `search status` respects `FEYNMAN_HOME` semantics instead of hardcoding the current shell home directory; added `tests/pi-launch.test.ts`.
+- Verified: Ran `npm test`, `npm run typecheck`, `npm run build`, `cd website && npm run build`, `npm run build:native-bundle`; smoke-tested `scripts/install/install.sh` against a locally served `dist/release/feynman-0.2.17-darwin-arm64.tar.gz`; smoke-tested `scripts/install/install-skills.sh` against a local source archive; confirmed installed `feynman --version`, `feynman --help`, `feynman doctor`, and packaged `feynman search status` work from the installed bundle; `npm audit --omit=dev` is clean in the root app and website after overrides.
+- Failed / learned: The first packaged `search status` smoke test still showed the user home path because the native bundle had been built before the `FEYNMAN_HOME` path fix; rebuilding the native bundle resolved that mismatch.
+- Blockers: PowerShell runtime was unavailable locally, so Windows installer execution remained code-path validated rather than actually executed.
+- Next: Push the second-pass hardening commit, then keep issue `#46` and issue `#47` open until users on the affected Linux/CJK environments confirm whether the launcher/header fixes fully resolve them.
+
+### 2026-04-09 10:36 PDT — remaining-tracker-triage-pass
+
+- Objective: Reduce the remaining open tracker items by landing the lowest-risk missing docs/catalog updates and a targeted Cloud Code Assist compatibility patch instead of only hand-triaging them.
+- Changed: Added MiniMax M2.7 recommendation preferences in `src/model/catalog.ts`; documented model switching, authenticated-provider visibility, and `/feynman-model` subagent overrides in `website/src/content/docs/getting-started/configuration.md` and `website/src/content/docs/reference/slash-commands.md`; added a runtime patch helper in `scripts/lib/pi-google-legacy-schema-patch.mjs` and wired `scripts/patch-embedded-pi.mjs` to normalize JSON Schema `const` into `enum` for the legacy `parameters` field used by Cloud Code Assist Claude models.
+- Verified: Ran `npm test`, `npm run typecheck`, `npm run build`, and `cd website && npm run build` after the patch/helper/docs changes.
+- Failed / learned: The MiniMax provider catalog in Pi already uses canonical IDs like `MiniMax-M2.7`, so the only failure during validation was a test assertion using the wrong casing rather than a runtime bug.
+- Blockers: The Cloud Code Assist fix is validated by targeted patch tests and code-path review rather than an end-to-end Google account repro in this environment.
+- Next: Push the tracker-triage commit, close the docs/MiniMax PRs as superseded by main, close the support-style model issues against the new docs, and decide whether the remaining feature requests should be left open or closed as not planned/upstream-dependent.
+
+### 2026-04-10 10:22 PDT — web-access-stale-override-fix
+
+- Objective: Fix the new `ctx.modelRegistry.getApiKeyAndHeaders is not a function` / stale `search-filter.js` report without reintroducing broad vendor drift.
+- Changed: Removed the stale `.feynman/vendor-overrides/pi-web-access/*` files and removed `syncVendorOverride` from `scripts/patch-embedded-pi.mjs`; kept the targeted `pi-web-access` runtime config-path patch; added `feynman search set <provider> [api-key]` and `feynman search clear` commands with a shared save path in `src/pi/web-access.ts`.
+- Verified: Ran `npm test`, `npm run typecheck`, `npm run build`; ran `node scripts/patch-embedded-pi.mjs`, confirmed the installed `pi-web-access/index.ts` has no `search-filter` / condense helper references, and smoke-imported `./.feynman/npm/node_modules/pi-web-access/index.ts`; ran `npm pack --dry-run` and confirmed stale `vendor-overrides` files are no longer in the package tarball.
+- Failed / learned: The public Linux installer Docker test was attempted but Docker Desktop became unresponsive even for simple `docker run node:22-bookworm node -v` commands; the earlier Linux npm-artifact container smoke remains valid, but this specific public-installer run is blocked by the local Docker daemon.
+- Blockers: Issue `#54` is too underspecified to fix directly without logs; public Linux installer behavior still needs a stable Docker daemon or a real Linux shell to reproduce the user's exact npm errors.
+- Next: Push the stale-override fix, close PR `#52` and PR `#53` as superseded/merged-by-main once pushed, and ask for logs on issue `#54` instead of guessing.
+
+### 2026-04-10 10:49 PDT — rpc-and-website-verification-pass
+
+- Objective: Exercise the Feynman wrapper's RPC mode and the website quality gates that were not fully covered by the prior passes.
+- Changed: Added `--mode <text|json|rpc>` pass-through support in the Feynman wrapper and skipped terminal clearing in RPC mode; added `@astrojs/check` to the website dev dependencies, fixed React Refresh lint violations in the generated UI components by exporting only components, and added safe website dependency overrides for dev-audit findings.
+- Verified: Ran a JSONL RPC smoke test through `node bin/feynman.js --mode rpc` with `get_state`; ran `npm test`, `npm run typecheck`, `npm run build`, `cd website && npm run lint`, `cd website && npm run typecheck`, `cd website && npm run build`, full root `npm audit`, full website `npm audit`, and `npm run build:native-bundle`.
+- Failed / learned: Website typecheck was previously a no-op prompt because `@astrojs/check` was missing; installing it exposed dev-audit findings that needed explicit overrides before the full website audit was clean.
+- Blockers: Docker Desktop remained unreliable after restart attempts, so this pass still does not include a second successful public-installer Linux Docker run.
+- Next: Push the RPC/website verification commit and keep future Docker/public-installer validation separate from repo correctness unless Docker is stable.

CONTRIBUTING.md

@@ -0,0 +1,115 @@
+# Contributing to Feynman
+
+Feynman is a research-first CLI built on Pi and alphaXiv. This guide is for humans and agents contributing code, prompts, skills, docs, installers, or workflow behavior to the repository.
+
+## Quick Links
+
+- GitHub: https://github.com/getcompanion-ai/feynman
+- Docs: https://feynman.is/docs
+- Repo agent contract: [AGENTS.md](AGENTS.md)
+- Issues: https://github.com/getcompanion-ai/feynman/issues
+
+## What Goes Where
+
+- CLI/runtime code: `src/`
+- Bundled prompt templates: `prompts/`
+- Bundled Pi skills: `skills/`
+- Bundled Pi subagent prompts: `.feynman/agents/`
+- Docs site: `website/`
+- Build/release scripts: `scripts/`
+- Generated research artifacts: `outputs/`, `papers/`, `notes/`
+
+If you need to change how bundled subagents behave, edit `.feynman/agents/*.md`. Do not duplicate that behavior in `AGENTS.md`.
+
+## Before You Open a PR
+
+1. Start from the latest `main`.
+2. Use Node.js `20.19.0` or newer. The repo expects `.nvmrc`, `package.json` engines, `website/package.json` engines, and the runtime version guard to stay aligned.
+3. Install dependencies from the repo root:
+
+```bash
+nvm use || nvm install
+npm install
+```
+
+4. Run the required checks before asking for review:
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```
+
+5. If you changed the docs site, also validate the website:
+
+```bash
+cd website
+npm install
+npm run build
+```
+
+6. Keep the PR focused. Do not mix unrelated cleanup with the real change.
+7. Add or update tests when behavior changes.
+8. Update docs, prompts, or skills when the user-facing workflow changes.
+
+## Contribution Rules
+
+- Bugs, docs fixes, installer fixes, and focused workflow improvements are good PRs.
+- Large feature changes should start with an issue or a concrete implementation discussion before code lands.
+- Avoid refactor-only PRs unless they are necessary to unblock a real fix or requested by a maintainer.
+- Do not silently change release behavior, installer behavior, or runtime defaults without documenting the reason in the PR.
+- Use American English in docs, comments, prompts, UI copy, and examples.
+- Do not add bundled prompts, skills, or docs whose primary purpose is to market, endorse, or funnel users toward a third-party product or service. Product integrations must be justified by user-facing utility and written in neutral language.
+
+## Repo-Specific Checks
+
+### Prompt and skill changes
+
+- New workflows usually live in `prompts/*.md`.
+- New reusable capabilities usually live in `skills/<name>/SKILL.md`.
+- Keep skill files concise. Put detailed operational rules in the prompt or in focused reference files only when needed.
+- If a new workflow should be invokable from the CLI, make sure its prompt frontmatter includes the correct metadata and that the command works through the normal prompt discovery path.
+
+### Agent and artifact conventions
+
+- `AGENTS.md` is the repo-level contract for workspace conventions, handoffs, provenance, and output naming.
+- Long-running research flows should write plan artifacts to `outputs/.plans/` and use `CHANGELOG.md` as a lab notebook when the work is substantial.
+- Do not update `CHANGELOG.md` for trivial one-shot changes.
+
+### Release and versioning discipline
+
+- The curl installer and release docs point users at tagged releases, not arbitrary commits on `main`.
+- If you ship user-visible fixes after a tag, do not leave the repo in a state where `main` and the latest release advertise the same version string while containing different behavior.
+- When changing release-sensitive behavior, check the version story across:
+  - `.nvmrc`
+  - `package.json`
+  - `website/package.json`
+  - `scripts/check-node-version.mjs`
+  - install docs in `README.md` and `website/src/content/docs/getting-started/installation.md`
+
+## AI-Assisted Contributions
+
+AI-assisted PRs are fine. The contributor is still responsible for the diff.
+
+- Understand the code you are submitting.
+- Run the local checks yourself instead of assuming generated code is correct.
+- Include enough context in the PR description for a reviewer to understand the change quickly.
+- If an agent updated prompts or skills, verify the instructions match the actual repo behavior.
+
+## Review Expectations
+
+- Explain what changed and why.
+- Call out tradeoffs, follow-up work, and anything intentionally not handled.
+- Include screenshots for UI changes.
+- Resolve review comments you addressed before requesting review again.
+
+## Good First Areas
+
+Useful contributions usually land in one of these areas:
+
+- installation and upgrade reliability
+- research workflow quality
+- model/provider setup ergonomics
+- docs clarity
+- preview and export stability
+- packaging and release hygiene

README.md

@@ -1,44 +1,96 @@
-# Feynman
+<p align="center">
+  <a href="https://feynman.is">
+    <img src="assets/hero.png" alt="Feynman CLI" width="800" />
+  </a>
+</p>
+<p align="center">The open source AI research agent.</p>
+<p align="center">
+  <a href="https://feynman.is/docs"><img alt="Docs" src="https://img.shields.io/badge/docs-feynman.is-0d9668?style=flat-square" /></a>
+  <a href="https://github.com/getcompanion-ai/feynman/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/getcompanion-ai/feynman?style=flat-square" /></a>
+</p>
 
-The open source AI research agent
+---
+
+### Installation
+
+**macOS / Linux:**
 
 ```bash
 curl -fsSL https://feynman.is/install | bash
 ```
 
+**Windows (PowerShell):**
+
 ```powershell
 irm https://feynman.is/install.ps1 | iex
 ```
 
-Or install the npm fallback:
+The one-line installer fetches the latest tagged release. To pin a version, pass it explicitly, for example `curl -fsSL https://feynman.is/install | bash -s -- 0.2.17`.
+
+The installer downloads a standalone native bundle with its own Node.js runtime.
+
+Local models are supported through the custom-provider flow. For Ollama, run `feynman setup`, choose `Custom provider (baseUrl + API key)`, use `openai-completions`, and point it at `http://localhost:11434/v1`.
+
+### Skills Only
+
+If you want just the research skills without the full terminal app:
+
+**macOS / Linux:**
 
 ```bash
-npm install -g @companion-ai/feynman
+curl -fsSL https://feynman.is/install-skills | bash
 ```
 
+**Windows (PowerShell):**
+
+```powershell
+irm https://feynman.is/install-skills.ps1 | iex
+```
+
+That installs the skill library into `~/.codex/skills/feynman`.
+
+For a repo-local install instead:
+
+**macOS / Linux:**
+
 ```bash
-feynman setup
-feynman
+curl -fsSL https://feynman.is/install-skills | bash -s -- --repo
 ```
 
-Feynman works directly inside your folder or repo. For long-running work, keep the stable repo contract in `AGENTS.md`, the current task brief in `outputs/.plans/`, and the chronological lab notebook in `CHANGELOG.md`.
+**Windows (PowerShell):**
+
+```powershell
+& ([scriptblock]::Create((irm https://feynman.is/install-skills.ps1))) -Scope Repo
+```
+
+That installs into `.agents/skills/feynman` under the current repository.
+
+These installers download the bundled `skills/` and `prompts/` trees plus the repo guidance files referenced by those skills. They do not install the Feynman terminal, bundled Node runtime, auth storage, or Pi packages.
 
 ---
 
-## What you type → what happens
+### What you type → what happens
 
-| Prompt | Result |
-| --- | --- |
-| `feynman "what do we know about scaling laws"` | Searches papers and web, produces a cited research brief |
-| `feynman deepresearch "mechanistic interpretability"` | Multi-agent investigation with parallel researchers, synthesis, verification |
-| `feynman lit "RLHF alternatives"` | Literature review with consensus, disagreements, open questions |
-| `feynman audit 2401.12345` | Compares paper claims against the public codebase |
-| `feynman replicate "chain-of-thought improves math"` | Asks where to run, then builds a replication plan |
-| `feynman "summarize this PDF" --prompt paper.pdf` | One-shot mode, no REPL |
+```
+$ feynman "what do we know about scaling laws"
+→ Searches papers and web, produces a cited research brief
+
+$ feynman deepresearch "mechanistic interpretability"
+→ Multi-agent investigation with parallel researchers, synthesis, verification
+
+$ feynman lit "RLHF alternatives"
+→ Literature review with consensus, disagreements, open questions
+
+$ feynman audit 2401.12345
+→ Compares paper claims against the public codebase
+
+$ feynman replicate "chain-of-thought improves math"
+→ Replicates experiments on local or cloud GPUs
+```
 
 ---
 
-## Workflows
+### Workflows
 
 Ask naturally or use slash commands as shortcuts.
 
@@ -48,17 +100,18 @@ Ask naturally or use slash commands as shortcuts.
 | `/lit <topic>` | Literature review from paper search and primary sources |
 | `/review <artifact>` | Simulated peer review with severity and revision plan |
 | `/audit <item>` | Paper vs. codebase mismatch audit |
-| `/replicate <paper>` | Replication plan with environment selection |
+| `/replicate <paper>` | Replicate experiments on local or cloud GPUs |
 | `/compare <topic>` | Source comparison matrix |
 | `/draft <topic>` | Paper-style draft from research findings |
 | `/autoresearch <idea>` | Autonomous experiment loop |
 | `/watch <topic>` | Recurring research watch |
+| `/outputs` | Browse all research artifacts |
 
 ---
 
-## Agents
+### Agents
 
-Four bundled research agents, dispatched automatically or via subagent commands.
+Four bundled research agents, dispatched automatically.
 
 - **Researcher** — gather evidence across papers, web, repos, docs
 - **Reviewer** — simulated peer review with severity-graded feedback
@@ -67,46 +120,36 @@ Four bundled research agents, dispatched automatically or via subagent commands.
 
 ---
 
-## Tools
+### Skills & Tools
 
-- **[AlphaXiv](https://www.alphaxiv.org/)** — paper search, Q&A, code reading, persistent annotations
+- **[AlphaXiv](https://www.alphaxiv.org/)** — paper search, Q&A, code reading, annotations (via `alpha` CLI)
 - **Docker** — isolated container execution for safe experiments on your machine
-- **Web search** — Gemini or Perplexity, zero-config default via signed-in Chromium
-- **Session search** — optional indexed recall across prior research sessions
+- **Web search** — Gemini or Perplexity, zero-config default
+- **Session search** — indexed recall across prior research sessions
 - **Preview** — browser and PDF export of generated artifacts
+- **Modal** — serverless GPU compute for burst training and inference
+- **RunPod** — persistent GPU pods with SSH access for long-running experiments
 
 ---
 
-## CLI
+### How it works
 
-```bash
-feynman                             # REPL
-feynman setup                       # guided setup
-feynman doctor                      # diagnose everything
-feynman status                      # current config summary
-feynman model login [provider]      # model auth
-feynman model set <provider/model>  # set default model
-feynman alpha login                 # alphaXiv auth
-feynman packages list               # core vs optional packages
-feynman packages install memory     # opt into heavier packages on demand
-feynman search status               # web search config
-```
+Built on [Pi](https://github.com/badlogic/pi-mono) for the agent runtime, [alphaXiv](https://www.alphaxiv.org/) for paper search and analysis, and CLI tools for compute and execution. Capabilities are delivered as [Pi skills](https://github.com/badlogic/pi-skills) — Markdown instruction files synced to `~/.feynman/agent/skills/` on startup. Every output is source-grounded — claims link to papers, docs, or repos with direct URLs.
 
 ---
 
-## How it works
+### Contributing
 
-Built on [Pi](https://github.com/badlogic/pi-mono) for the agent runtime, [alphaXiv](https://www.alphaxiv.org/) for paper search and analysis, and [Docker](https://www.docker.com/) for isolated local execution
-
-Every output is source-grounded — claims link to papers, docs, or repos with direct URLs
-
----
-
-## Contributing
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide.
 
 ```bash
 git clone https://github.com/getcompanion-ai/feynman.git
-cd feynman && npm install && npm run start
+cd feynman
+nvm use || nvm install
+npm install
+npm test
+npm run typecheck
+npm run build
 ```
 
 [Docs](https://feynman.is/docs) · [MIT License](LICENSE)

bin/feynman.js

@@ -1,8 +1,36 @@
 #!/usr/bin/env node
-const v = process.versions.node.split(".").map(Number);
-if (v[0] < 20) {
-  console.error(`feynman requires Node.js 20 or later (you have ${process.versions.node})`);
-  console.error("upgrade: https://nodejs.org or nvm install 20");
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const MIN_NODE_VERSION = "20.19.0";
+
+function parseNodeVersion(version) {
+  const [major = "0", minor = "0", patch = "0"] = version.replace(/^v/, "").split(".");
+  return {
+    major: Number.parseInt(major, 10) || 0,
+    minor: Number.parseInt(minor, 10) || 0,
+    patch: Number.parseInt(patch, 10) || 0,
+  };
+}
+
+function compareNodeVersions(left, right) {
+  if (left.major !== right.major) return left.major - right.major;
+  if (left.minor !== right.minor) return left.minor - right.minor;
+  return left.patch - right.patch;
+}
+
+if (compareNodeVersions(parseNodeVersion(process.versions.node), parseNodeVersion(MIN_NODE_VERSION)) < 0) {
+  const isWindows = process.platform === "win32";
+  console.error(`feynman requires Node.js ${MIN_NODE_VERSION} or later (detected ${process.versions.node}).`);
+  console.error(isWindows
+    ? "Install a newer Node.js from https://nodejs.org, or use the standalone installer:"
+    : "Switch to Node 20 with `nvm install 20 && nvm use 20`, or use the standalone installer:");
+  console.error(isWindows
+    ? "irm https://feynman.is/install.ps1 | iex"
+    : "curl -fsSL https://feynman.is/install | bash");
   process.exit(1);
 }
-import("../dist/index.js");
+const here = import.meta.dirname;
+
+await import(pathToFileURL(resolve(here, "..", "scripts", "patch-embedded-pi.mjs")).href);
+await import(pathToFileURL(resolve(here, "..", "dist", "index.js")).href);

extensions/research-tools.ts

@@ -1,9 +1,12 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
-import { registerAlphaCommands, registerAlphaTools } from "./research-tools/alpha.js";
+import { registerAlphaTools } from "./research-tools/alpha.js";
+import { registerDiscoveryCommands } from "./research-tools/discovery.js";
+import { registerFeynmanModelCommand } from "./research-tools/feynman-model.js";
 import { installFeynmanHeader } from "./research-tools/header.js";
 import { registerHelpCommand } from "./research-tools/help.js";
-import { registerInitCommand, registerPreviewTool, registerSessionSearchTool } from "./research-tools/project.js";
+import { registerInitCommand, registerOutputsCommand } from "./research-tools/project.js";
+import { registerServiceTierControls } from "./research-tools/service-tier.js";
 
 export default function researchTools(pi: ExtensionAPI): void {
 	const cache: { agentSummaryPromise?: Promise<{ agents: string[]; chains: string[] }> } = {};
@@ -16,10 +19,11 @@ export default function researchTools(pi: ExtensionAPI): void {
 		await installFeynmanHeader(pi, ctx, cache);
 	});
 
-	registerAlphaCommands(pi);
+	registerAlphaTools(pi);
+	registerDiscoveryCommands(pi);
+	registerFeynmanModelCommand(pi);
 	registerHelpCommand(pi);
 	registerInitCommand(pi);
-	registerSessionSearchTool(pi);
-	registerAlphaTools(pi);
-	registerPreviewTool(pi);
+	registerOutputsCommand(pi);
+	registerServiceTierControls(pi);
 }

extensions/research-tools/alpha.ts

@@ -1,136 +1,63 @@
 import {
-	annotatePaper,
 	askPaper,
+	annotatePaper,
 	clearPaperAnnotation,
-	disconnect,
 	getPaper,
-	getUserName as getAlphaUserName,
-	isLoggedIn as isAlphaLoggedIn,
 	listPaperAnnotations,
-	login as loginAlpha,
-	logout as logoutAlpha,
 	readPaperCode,
 	searchPapers,
 } from "@companion-ai/alpha-hub/lib";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
-import { getExtensionCommandSpec } from "../../metadata/commands.mjs";
-import { formatToolText } from "./shared.js";
-
-export function registerAlphaCommands(pi: ExtensionAPI): void {
-	pi.registerCommand("alpha-login", {
-		description: getExtensionCommandSpec("alpha-login")?.description ?? "Sign in to alphaXiv from inside Feynman.",
-		handler: async (_args, ctx) => {
-			if (isAlphaLoggedIn()) {
-				const name = getAlphaUserName();
-				ctx.ui.notify(name ? `alphaXiv already connected as ${name}` : "alphaXiv already connected", "info");
-				return;
-			}
-
-			await loginAlpha();
-			const name = getAlphaUserName();
-			ctx.ui.notify(name ? `alphaXiv connected as ${name}` : "alphaXiv login complete", "info");
-		},
-	});
-
-	pi.registerCommand("alpha-logout", {
-		description: getExtensionCommandSpec("alpha-logout")?.description ?? "Clear alphaXiv auth from inside Feynman.",
-		handler: async (_args, ctx) => {
-			logoutAlpha();
-			ctx.ui.notify("alphaXiv auth cleared", "info");
-		},
-	});
-
-	pi.registerCommand("alpha-status", {
-		description: getExtensionCommandSpec("alpha-status")?.description ?? "Show alphaXiv authentication status.",
-		handler: async (_args, ctx) => {
-			if (!isAlphaLoggedIn()) {
-				ctx.ui.notify("alphaXiv not connected", "warning");
-				return;
-			}
-
-			const name = getAlphaUserName();
-			ctx.ui.notify(name ? `alphaXiv connected as ${name}` : "alphaXiv connected", "info");
-		},
-	});
+function formatText(value: unknown): string {
+	if (typeof value === "string") return value;
+	return JSON.stringify(value, null, 2);
 }
 
 export function registerAlphaTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "alpha_search",
 		label: "Alpha Search",
-		description: "Search papers through alphaXiv using semantic, keyword, both, agentic, or all retrieval modes.",
+		description:
+			"Search research papers through alphaXiv. Modes: semantic (default, use 2-3 sentence queries), keyword (exact terms), agentic (broad multi-turn retrieval), both, or all.",
 		parameters: Type.Object({
-			query: Type.String({ description: "Paper search query." }),
+			query: Type.String({ description: "Search query." }),
 			mode: Type.Optional(
-				Type.String({
-					description: "Search mode: semantic, keyword, both, agentic, or all.",
-				}),
+				Type.String({ description: "Search mode: semantic, keyword, both, agentic, or all." }),
 			),
 		}),
 		async execute(_toolCallId, params) {
-			try {
-				const result = await searchPapers(params.query, params.mode?.trim() || "all");
-				return {
-					content: [{ type: "text", text: formatToolText(result) }],
-					details: result,
-				};
-			} finally {
-				await disconnect();
-			}
+			const result = await searchPapers(params.query, params.mode?.trim() || "semantic");
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
 		},
 	});
 
 	pi.registerTool({
 		name: "alpha_get_paper",
 		label: "Alpha Get Paper",
-		description: "Fetch a paper report or full text, plus any local annotation, using alphaXiv.",
+		description: "Fetch a paper's AI-generated report (or raw full text) plus any local annotation.",
 		parameters: Type.Object({
-			paper: Type.String({
-				description: "arXiv ID, arXiv URL, or alphaXiv URL.",
-			}),
-			fullText: Type.Optional(
-				Type.Boolean({
-					description: "Return raw full text instead of the AI report.",
-				}),
-			),
+			paper: Type.String({ description: "arXiv ID, arXiv URL, or alphaXiv URL." }),
+			fullText: Type.Optional(Type.Boolean({ description: "Return raw full text instead of AI report." })),
 		}),
 		async execute(_toolCallId, params) {
-			try {
-				const result = await getPaper(params.paper, { fullText: params.fullText });
-				return {
-					content: [{ type: "text", text: formatToolText(result) }],
-					details: result,
-				};
-			} finally {
-				await disconnect();
-			}
+			const result = await getPaper(params.paper, { fullText: params.fullText });
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
 		},
 	});
 
 	pi.registerTool({
 		name: "alpha_ask_paper",
 		label: "Alpha Ask Paper",
-		description: "Ask a targeted question about a paper using alphaXiv's PDF analysis.",
+		description: "Ask a targeted question about a paper. Uses AI to analyze the PDF and answer.",
 		parameters: Type.Object({
-			paper: Type.String({
-				description: "arXiv ID, arXiv URL, or alphaXiv URL.",
-			}),
-			question: Type.String({
-				description: "Question to ask about the paper.",
-			}),
+			paper: Type.String({ description: "arXiv ID, arXiv URL, or alphaXiv URL." }),
+			question: Type.String({ description: "Question about the paper." }),
 		}),
 		async execute(_toolCallId, params) {
-			try {
-				const result = await askPaper(params.paper, params.question);
-				return {
-					content: [{ type: "text", text: formatToolText(result) }],
-					details: result,
-				};
-			} finally {
-				await disconnect();
-			}
+			const result = await askPaper(params.paper, params.question);
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
 		},
 	});
 
@@ -139,33 +66,17 @@ export function registerAlphaTools(pi: ExtensionAPI): void {
 		label: "Alpha Annotate Paper",
 		description: "Write or clear a persistent local annotation for a paper.",
 		parameters: Type.Object({
-			paper: Type.String({
-				description: "Paper ID to annotate.",
-			}),
-			note: Type.Optional(
-				Type.String({
-					description: "Annotation text. Omit when clear=true.",
-				}),
-			),
-			clear: Type.Optional(
-				Type.Boolean({
-					description: "Clear the existing annotation instead of writing one.",
-				}),
-			),
+			paper: Type.String({ description: "Paper ID (arXiv ID or URL)." }),
+			note: Type.Optional(Type.String({ description: "Annotation text. Omit when clear=true." })),
+			clear: Type.Optional(Type.Boolean({ description: "Clear the existing annotation." })),
 		}),
 		async execute(_toolCallId, params) {
 			const result = params.clear
 				? await clearPaperAnnotation(params.paper)
 				: params.note
 					? await annotatePaper(params.paper, params.note)
-					: (() => {
-							throw new Error("Provide either note or clear=true.");
-						})();
-
-			return {
-				content: [{ type: "text", text: formatToolText(result) }],
-				details: result,
-			};
+					: (() => { throw new Error("Provide either note or clear=true."); })();
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
 		},
 	});
 
@@ -176,37 +87,21 @@ export function registerAlphaTools(pi: ExtensionAPI): void {
 		parameters: Type.Object({}),
 		async execute() {
 			const result = await listPaperAnnotations();
-			return {
-				content: [{ type: "text", text: formatToolText(result) }],
-				details: result,
-			};
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
 		},
 	});
 
 	pi.registerTool({
 		name: "alpha_read_code",
 		label: "Alpha Read Code",
-		description: "Read files from a paper's GitHub repository through alphaXiv.",
+		description: "Read files from a paper's GitHub repository. Use '/' for repo overview.",
 		parameters: Type.Object({
-			githubUrl: Type.String({
-				description: "GitHub repository URL for the paper implementation.",
-			}),
-			path: Type.Optional(
-				Type.String({
-					description: "Repository path to inspect. Use / for the repo overview.",
-				}),
-			),
+			githubUrl: Type.String({ description: "GitHub repository URL." }),
+			path: Type.Optional(Type.String({ description: "File or directory path. Default: '/'" })),
 		}),
 		async execute(_toolCallId, params) {
-			try {
-				const result = await readPaperCode(params.githubUrl, params.path?.trim() || "/");
-				return {
-					content: [{ type: "text", text: formatToolText(result) }],
-					details: result,
-				};
-			} finally {
-				await disconnect();
-			}
+			const result = await readPaperCode(params.githubUrl, params.path?.trim() || "/");
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
 		},
 	});
 }

extensions/research-tools/discovery.ts

@@ -0,0 +1,130 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+
+import type { ExtensionAPI, SlashCommandInfo, ToolInfo } from "@mariozechner/pi-coding-agent";
+
+function resolveFeynmanSettingsPath(): string {
+	const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+	const agentDir = configured
+		? configured.startsWith("~/")
+			? resolve(homedir(), configured.slice(2))
+			: resolve(configured)
+		: resolve(homedir(), ".feynman", "agent");
+	return resolve(agentDir, "settings.json");
+}
+
+function readConfiguredPackages(): string[] {
+	const settingsPath = resolveFeynmanSettingsPath();
+	if (!existsSync(settingsPath)) return [];
+
+	try {
+		const parsed = JSON.parse(readFileSync(settingsPath, "utf8")) as { packages?: unknown[] };
+		return Array.isArray(parsed.packages)
+			? parsed.packages
+					.map((entry) => {
+						if (typeof entry === "string") return entry;
+						if (!entry || typeof entry !== "object") return undefined;
+						const record = entry as { source?: unknown };
+						return typeof record.source === "string" ? record.source : undefined;
+					})
+					.filter((entry): entry is string => Boolean(entry))
+			: [];
+	} catch {
+		return [];
+	}
+}
+
+function formatSourceLabel(sourceInfo: { source: string; path: string }): string {
+	if (sourceInfo.source === "local") {
+		if (sourceInfo.path.includes("/prompts/")) return "workflow";
+		if (sourceInfo.path.includes("/extensions/")) return "extension";
+		return "local";
+	}
+	return sourceInfo.source.replace(/^npm:/, "").replace(/^git:/, "");
+}
+
+function formatCommandLine(command: SlashCommandInfo): string {
+	const source = formatSourceLabel(command.sourceInfo);
+	return `/${command.name} — ${command.description ?? ""} [${source}]`;
+}
+
+function summarizeToolParameters(tool: ToolInfo): string {
+	const properties =
+		tool.parameters &&
+		typeof tool.parameters === "object" &&
+		"properties" in tool.parameters &&
+		tool.parameters.properties &&
+		typeof tool.parameters.properties === "object"
+			? Object.keys(tool.parameters.properties as Record<string, unknown>)
+			: [];
+	return properties.length > 0 ? properties.join(", ") : "no parameters";
+}
+
+function formatToolLine(tool: ToolInfo): string {
+	const source = formatSourceLabel(tool.sourceInfo);
+	return `${tool.name} — ${tool.description ?? ""} [${source}]`;
+}
+
+export function registerDiscoveryCommands(pi: ExtensionAPI): void {
+	pi.registerCommand("commands", {
+		description: "Browse all available slash commands, including package and built-in commands.",
+		handler: async (_args, ctx) => {
+			const commands = pi
+				.getCommands()
+				.slice()
+				.sort((left, right) => left.name.localeCompare(right.name));
+			const items = commands.map((command) => formatCommandLine(command));
+			const selected = await ctx.ui.select("Slash Commands", items);
+			if (!selected) return;
+			ctx.ui.setEditorText(selected.split(" — ")[0] ?? "");
+			ctx.ui.notify(`Prefilled ${selected.split(" — ")[0]}`, "info");
+		},
+	});
+
+	pi.registerCommand("tools", {
+		description: "Browse all callable tools with their source and parameter summary.",
+		handler: async (_args, ctx) => {
+			const tools = pi
+				.getAllTools()
+				.slice()
+				.sort((left, right) => left.name.localeCompare(right.name));
+			const selected = await ctx.ui.select("Tools", tools.map((tool) => formatToolLine(tool)));
+			if (!selected) return;
+
+			const toolName = selected.split(" — ")[0] ?? selected;
+			const tool = tools.find((entry) => entry.name === toolName);
+			if (!tool) return;
+			ctx.ui.notify(`${tool.name}: ${summarizeToolParameters(tool)}`, "info");
+		},
+	});
+
+	pi.registerCommand("capabilities", {
+		description: "Show installed packages, discovery entrypoints, and high-level runtime capability counts.",
+		handler: async (_args, ctx) => {
+			const commands = pi.getCommands();
+			const tools = pi.getAllTools();
+			const workflows = commands.filter((command) => formatSourceLabel(command.sourceInfo) === "workflow");
+			const packages = readConfiguredPackages();
+			const items = [
+				`Commands: ${commands.length}`,
+				`Workflows: ${workflows.length}`,
+				`Tools: ${tools.length}`,
+				`Packages: ${packages.length}`,
+				"--- Discovery ---",
+				"/commands — browse slash commands",
+				"/tools — inspect callable tools",
+				"/hotkeys — view keyboard shortcuts",
+				"/service-tier — set request tier for supported providers",
+				"--- Installed Packages ---",
+				...packages.map((pkg) => pkg),
+			];
+			const selected = await ctx.ui.select("Capabilities", items);
+			if (!selected || selected.startsWith("---")) return;
+			if (selected.startsWith("/")) {
+				ctx.ui.setEditorText(selected.split(" — ")[0] ?? selected);
+				ctx.ui.notify(`Prefilled ${selected.split(" — ")[0]}`, "info");
+			}
+		},
+	});
+}

extensions/research-tools/feynman-model.ts

@@ -0,0 +1,309 @@
+import { type Dirent, existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const FRONTMATTER_PATTERN = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+const INHERIT_MAIN = "__inherit_main__";
+
+type FrontmatterDocument = {
+	lines: string[];
+	body: string;
+	eol: string;
+	trailingNewline: boolean;
+};
+
+type SubagentModelConfig = {
+	agent: string;
+	model?: string;
+	filePath: string;
+};
+
+type SelectOption<T> = {
+	label: string;
+	value: T;
+};
+
+type CommandContext = Parameters<Parameters<ExtensionAPI["registerCommand"]>[1]["handler"]>[1];
+
+type TargetChoice =
+	| { type: "main" }
+	| { type: "subagent"; agent: string; model?: string };
+
+function expandHomePath(value: string): string {
+	if (value === "~") return homedir();
+	if (value.startsWith("~/")) return resolve(homedir(), value.slice(2));
+	return value;
+}
+
+function resolveFeynmanAgentDir(): string {
+	const configured = process.env.PI_CODING_AGENT_DIR ?? process.env.FEYNMAN_CODING_AGENT_DIR;
+	if (configured?.trim()) {
+		return resolve(expandHomePath(configured.trim()));
+	}
+	return resolve(homedir(), ".feynman", "agent");
+}
+
+function formatModelSpec(model: { provider: string; id: string }): string {
+	return `${model.provider}/${model.id}`;
+}
+
+function detectEol(text: string): string {
+	return text.includes("\r\n") ? "\r\n" : "\n";
+}
+
+function normalizeLineEndings(text: string): string {
+	return text.replace(/\r\n/g, "\n");
+}
+
+function parseFrontmatterDocument(text: string): FrontmatterDocument | null {
+	const normalized = normalizeLineEndings(text);
+	const match = normalized.match(FRONTMATTER_PATTERN);
+	if (!match) return null;
+
+	return {
+		lines: match[1].split("\n"),
+		body: match[2] ?? "",
+		eol: detectEol(text),
+		trailingNewline: normalized.endsWith("\n"),
+	};
+}
+
+function serializeFrontmatterDocument(document: FrontmatterDocument): string {
+	const normalized = `---\n${document.lines.join("\n")}\n---\n${document.body}`;
+	const withTrailingNewline =
+		document.trailingNewline && !normalized.endsWith("\n") ? `${normalized}\n` : normalized;
+	return document.eol === "\n" ? withTrailingNewline : withTrailingNewline.replace(/\n/g, "\r\n");
+}
+
+function parseFrontmatterKey(line: string): string | undefined {
+	const match = line.match(/^\s*([A-Za-z0-9_-]+)\s*:/);
+	return match?.[1]?.toLowerCase();
+}
+
+function getFrontmatterValue(lines: string[], key: string): string | undefined {
+	const normalizedKey = key.toLowerCase();
+	for (const line of lines) {
+		const parsedKey = parseFrontmatterKey(line);
+		if (parsedKey !== normalizedKey) continue;
+		const separatorIndex = line.indexOf(":");
+		if (separatorIndex === -1) return undefined;
+		const value = line.slice(separatorIndex + 1).trim();
+		return value.length > 0 ? value : undefined;
+	}
+	return undefined;
+}
+
+function upsertFrontmatterValue(lines: string[], key: string, value: string): string[] {
+	const normalizedKey = key.toLowerCase();
+	const nextLines = [...lines];
+	const existingIndex = nextLines.findIndex((line) => parseFrontmatterKey(line) === normalizedKey);
+	const serialized = `${key}: ${value}`;
+
+	if (existingIndex !== -1) {
+		nextLines[existingIndex] = serialized;
+		return nextLines;
+	}
+
+	const descriptionIndex = nextLines.findIndex((line) => parseFrontmatterKey(line) === "description");
+	const nameIndex = nextLines.findIndex((line) => parseFrontmatterKey(line) === "name");
+	const insertIndex = descriptionIndex !== -1 ? descriptionIndex + 1 : nameIndex !== -1 ? nameIndex + 1 : nextLines.length;
+	nextLines.splice(insertIndex, 0, serialized);
+	return nextLines;
+}
+
+function removeFrontmatterKey(lines: string[], key: string): string[] {
+	const normalizedKey = key.toLowerCase();
+	return lines.filter((line) => parseFrontmatterKey(line) !== normalizedKey);
+}
+
+function normalizeAgentName(name: string): string {
+	return name.trim().toLowerCase();
+}
+
+function getAgentsDir(agentDir: string): string {
+	return join(agentDir, "agents");
+}
+
+function listAgentFiles(agentsDir: string): string[] {
+	if (!existsSync(agentsDir)) return [];
+
+	return readdirSync(agentsDir, { withFileTypes: true })
+		.filter((entry: Dirent) => (entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith(".md"))
+		.filter((entry) => !entry.name.endsWith(".chain.md"))
+		.map((entry) => join(agentsDir, entry.name));
+}
+
+function readAgentConfig(filePath: string): SubagentModelConfig {
+	const content = readFileSync(filePath, "utf8");
+	const parsed = parseFrontmatterDocument(content);
+	const fallbackName = basename(filePath, ".md");
+	if (!parsed) return { agent: fallbackName, filePath };
+
+	return {
+		agent: getFrontmatterValue(parsed.lines, "name") ?? fallbackName,
+		model: getFrontmatterValue(parsed.lines, "model"),
+		filePath,
+	};
+}
+
+function listSubagentModelConfigs(agentDir: string): SubagentModelConfig[] {
+	return listAgentFiles(getAgentsDir(agentDir))
+		.map((filePath) => readAgentConfig(filePath))
+		.sort((left, right) => left.agent.localeCompare(right.agent));
+}
+
+function findAgentConfig(configs: SubagentModelConfig[], agentName: string): SubagentModelConfig | undefined {
+	const normalized = normalizeAgentName(agentName);
+	return (
+		configs.find((config) => normalizeAgentName(config.agent) === normalized) ??
+		configs.find((config) => normalizeAgentName(basename(config.filePath, ".md")) === normalized)
+	);
+}
+
+function getAgentConfigOrThrow(agentDir: string, agentName: string): SubagentModelConfig {
+	const configs = listSubagentModelConfigs(agentDir);
+	const target = findAgentConfig(configs, agentName);
+	if (target) return target;
+
+	if (configs.length === 0) {
+		throw new Error(`No subagent definitions found in ${getAgentsDir(agentDir)}.`);
+	}
+
+	const availableAgents = configs.map((config) => config.agent).join(", ");
+	throw new Error(`Unknown subagent: ${agentName}. Available agents: ${availableAgents}`);
+}
+
+function setSubagentModel(agentDir: string, agentName: string, modelSpec: string): void {
+	const normalizedModelSpec = modelSpec.trim();
+	if (!normalizedModelSpec) throw new Error("Model spec cannot be empty.");
+
+	const target = getAgentConfigOrThrow(agentDir, agentName);
+	const content = readFileSync(target.filePath, "utf8");
+	const parsed = parseFrontmatterDocument(content);
+
+	if (!parsed) {
+		const eol = detectEol(content);
+		const injected = `---${eol}name: ${target.agent}${eol}model: ${normalizedModelSpec}${eol}---${eol}${content}`;
+		writeFileSync(target.filePath, injected, "utf8");
+		return;
+	}
+
+	const nextLines = upsertFrontmatterValue(parsed.lines, "model", normalizedModelSpec);
+	if (nextLines.join("\n") !== parsed.lines.join("\n")) {
+		writeFileSync(target.filePath, serializeFrontmatterDocument({ ...parsed, lines: nextLines }), "utf8");
+	}
+}
+
+function unsetSubagentModel(agentDir: string, agentName: string): void {
+	const target = getAgentConfigOrThrow(agentDir, agentName);
+	const content = readFileSync(target.filePath, "utf8");
+	const parsed = parseFrontmatterDocument(content);
+	if (!parsed) return;
+
+	const nextLines = removeFrontmatterKey(parsed.lines, "model");
+	if (nextLines.join("\n") !== parsed.lines.join("\n")) {
+		writeFileSync(target.filePath, serializeFrontmatterDocument({ ...parsed, lines: nextLines }), "utf8");
+	}
+}
+
+async function selectOption<T>(
+	ctx: CommandContext,
+	title: string,
+	options: SelectOption<T>[],
+): Promise<T | undefined> {
+	const selected = await ctx.ui.select(
+		title,
+		options.map((option) => option.label),
+	);
+	if (!selected) return undefined;
+	return options.find((option) => option.label === selected)?.value;
+}
+
+export function registerFeynmanModelCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("feynman-model", {
+		description: "Open Feynman model menu (main + per-subagent overrides).",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("feynman-model requires interactive mode.", "error");
+				return;
+			}
+
+			try {
+				ctx.modelRegistry.refresh();
+				const availableModels = [...ctx.modelRegistry.getAvailable()].sort((left, right) =>
+					formatModelSpec(left).localeCompare(formatModelSpec(right)),
+				);
+				if (availableModels.length === 0) {
+					ctx.ui.notify("No models available.", "error");
+					return;
+				}
+
+				const agentDir = resolveFeynmanAgentDir();
+				const subagentConfigs = listSubagentModelConfigs(agentDir);
+				const currentMain = ctx.model ? formatModelSpec(ctx.model) : "(none)";
+
+				const targetOptions: SelectOption<TargetChoice>[] = [
+					{ label: `main (default): ${currentMain}`, value: { type: "main" } },
+					...subagentConfigs.map((config) => ({
+						label: `${config.agent}: ${config.model ?? "default"}`,
+						value: { type: "subagent" as const, agent: config.agent, model: config.model },
+					})),
+				];
+
+				const target = await selectOption(ctx, "Choose target", targetOptions);
+				if (!target) return;
+
+				if (target.type === "main") {
+					const selectedModel = await selectOption(
+						ctx,
+						"Select main model",
+						availableModels.map((model) => {
+							const spec = formatModelSpec(model);
+							const suffix = spec === currentMain ? " (current)" : "";
+							return { label: `${spec}${suffix}`, value: model };
+						}),
+					);
+					if (!selectedModel) return;
+
+					const success = await pi.setModel(selectedModel);
+					if (!success) {
+						ctx.ui.notify(`No API key found for ${selectedModel.provider}.`, "error");
+						return;
+					}
+					ctx.ui.notify(`Main model set to ${formatModelSpec(selectedModel)}.`, "info");
+					return;
+				}
+
+				const selectedSubagentModel = await selectOption(
+					ctx,
+					`Select model for ${target.agent}`,
+					[
+						{
+							label: target.model ? "(inherit main default)" : "(inherit main default) (current)",
+							value: INHERIT_MAIN,
+						},
+						...availableModels.map((model) => {
+							const spec = formatModelSpec(model);
+							const suffix = spec === target.model ? " (current)" : "";
+							return { label: `${spec}${suffix}`, value: spec };
+						}),
+					],
+				);
+				if (!selectedSubagentModel) return;
+
+				if (selectedSubagentModel === INHERIT_MAIN) {
+					unsetSubagentModel(agentDir, target.agent);
+					ctx.ui.notify(`${target.agent} now inherits the main model.`, "info");
+					return;
+				}
+
+				setSubagentModel(agentDir, target.agent, selectedSubagentModel);
+				ctx.ui.notify(`${target.agent} model set to ${selectedSubagentModel}.`, "info");
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+}

extensions/research-tools/header.ts

@@ -4,6 +4,7 @@ import { execSync } from "node:child_process";
 import { resolve as resolvePath } from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 
 import {
 	APP_ROOT,
@@ -11,10 +12,8 @@ import {
 	FEYNMAN_VERSION,
 } from "./shared.js";
 
-const ANSI_RE = /\x1b\[[0-9;]*m/g;
-
 function visibleLength(text: string): number {
-	return text.replace(ANSI_RE, "").length;
+	return visibleWidth(text);
 }
 
 function formatHeaderPath(path: string): string {
@@ -23,10 +22,8 @@ function formatHeaderPath(path: string): string {
 }
 
 function truncateVisible(text: string, maxVisible: number): string {
-	const raw = text.replace(ANSI_RE, "");
-	if (raw.length <= maxVisible) return text;
-	if (maxVisible <= 3) return ".".repeat(maxVisible);
-	return `${raw.slice(0, maxVisible - 3)}...`;
+	if (visibleWidth(text) <= maxVisible) return text;
+	return truncateToWidth(text, maxVisible, maxVisible <= 3 ? "" : "...");
 }
 
 function wrapWords(text: string, maxW: number): string[] {
@@ -34,12 +31,12 @@ function wrapWords(text: string, maxW: number): string[] {
 	const lines: string[] = [];
 	let cur = "";
 	for (let word of words) {
-		if (word.length > maxW) {
+		if (visibleWidth(word) > maxW) {
 			if (cur) { lines.push(cur); cur = ""; }
-			word = maxW > 3 ? `${word.slice(0, maxW - 1)}…` : word.slice(0, maxW);
+			word = truncateToWidth(word, maxW, maxW > 3 ? "…" : "");
 		}
 		const test = cur ? `${cur} ${word}` : word;
-		if (cur && test.length > maxW) {
+		if (cur && visibleWidth(test) > maxW) {
 			lines.push(cur);
 			cur = word;
 		} else {
@@ -56,9 +53,10 @@ function padRight(text: string, width: number): string {
 }
 
 function centerText(text: string, width: number): string {
-	if (text.length >= width) return text.slice(0, width);
-	const left = Math.floor((width - text.length) / 2);
-	const right = width - text.length - left;
+	const textWidth = visibleWidth(text);
+	if (textWidth >= width) return truncateToWidth(text, width, "");
+	const left = Math.floor((width - textWidth) / 2);
+	const right = width - textWidth - left;
 	return `${" ".repeat(left)}${text}${" ".repeat(right)}`;
 }
 
@@ -287,8 +285,8 @@ export function installFeynmanHeader(
 
 					if (activity) {
 						const maxActivityLen = leftW * 2;
-						const trimmed = activity.length > maxActivityLen
-							? `${activity.slice(0, maxActivityLen - 1)}…`
+						const trimmed = visibleWidth(activity) > maxActivityLen
+							? truncateToWidth(activity, maxActivityLen, "…")
 							: activity;
 						leftLines.push("");
 						leftLines.push(theme.fg("accent", theme.bold("Last Activity")));

extensions/research-tools/preview.ts

@@ -1,183 +0,0 @@
-import { execFile, spawn } from "node:child_process";
-import { mkdir, mkdtemp, readFile, stat, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { basename, dirname, extname, join } from "node:path";
-import { pathToFileURL } from "node:url";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
-
-function isMarkdownPath(path: string): boolean {
-	return [".md", ".markdown", ".txt"].includes(extname(path).toLowerCase());
-}
-
-function isLatexPath(path: string): boolean {
-	return extname(path).toLowerCase() === ".tex";
-}
-
-function wrapCodeAsMarkdown(source: string, filePath: string): string {
-	const language = extname(filePath).replace(/^\./, "") || "text";
-	return `# ${basename(filePath)}\n\n\`\`\`${language}\n${source}\n\`\`\`\n`;
-}
-
-export async function openWithDefaultApp(targetPath: string): Promise<void> {
-	const target = pathToFileURL(targetPath).href;
-	if (process.platform === "darwin") {
-		await execFileAsync("open", [target]);
-		return;
-	}
-	if (process.platform === "win32") {
-		await execFileAsync("cmd", ["/c", "start", "", target]);
-		return;
-	}
-	await execFileAsync("xdg-open", [target]);
-}
-
-async function runCommandWithInput(
-	command: string,
-	args: string[],
-	input: string,
-): Promise<{ stdout: string; stderr: string }> {
-	return await new Promise((resolve, reject) => {
-		const child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
-		const stdoutChunks: Buffer[] = [];
-		const stderrChunks: Buffer[] = [];
-
-		child.stdout.on("data", (chunk: Buffer | string) => {
-			stdoutChunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
-		});
-		child.stderr.on("data", (chunk: Buffer | string) => {
-			stderrChunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
-		});
-
-		child.once("error", reject);
-		child.once("close", (code) => {
-			const stdout = Buffer.concat(stdoutChunks).toString("utf8");
-			const stderr = Buffer.concat(stderrChunks).toString("utf8");
-			if (code === 0) {
-				resolve({ stdout, stderr });
-				return;
-			}
-			reject(new Error(`${command} failed with exit code ${code}${stderr ? `: ${stderr.trim()}` : ""}`));
-		});
-
-		child.stdin.end(input);
-	});
-}
-
-export async function renderHtmlPreview(filePath: string): Promise<string> {
-	const source = await readFile(filePath, "utf8");
-	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
-	const inputFormat = isLatexPath(filePath)
-		? "latex"
-		: "markdown+lists_without_preceding_blankline+tex_math_dollars+autolink_bare_uris-raw_html";
-	const markdown = isLatexPath(filePath) || isMarkdownPath(filePath) ? source : wrapCodeAsMarkdown(source, filePath);
-	const args = ["-f", inputFormat, "-t", "html5", "--mathml", "--wrap=none", `--resource-path=${dirname(filePath)}`];
-	const { stdout } = await runCommandWithInput(pandocCommand, args, markdown);
-	const html = `<!doctype html><html><head><meta charset="utf-8" /><base href="${pathToFileURL(dirname(filePath) + "/").href}" /><title>${basename(filePath)}</title><style>
-:root{
-  --bg:#faf7f2;
-  --paper:#fffdf9;
-  --border:#d7cec1;
-  --text:#1f1c18;
-  --muted:#6c645a;
-  --code:#f3eee6;
-  --link:#0f6d8c;
-  --quote:#8b7f70;
-}
-@media (prefers-color-scheme: dark){
-  :root{
-    --bg:#161311;
-    --paper:#1d1916;
-    --border:#3b342d;
-    --text:#ebe3d6;
-    --muted:#b4ab9f;
-    --code:#221d19;
-    --link:#8ac6d6;
-    --quote:#a89d8f;
-  }
-}
-body{
-  font-family:Charter,"Iowan Old Style","Palatino Linotype","Book Antiqua",Palatino,Georgia,serif;
-  margin:0;
-  background:var(--bg);
-  color:var(--text);
-  line-height:1.7;
-}
-main{
-  max-width:900px;
-  margin:2rem auto 4rem;
-  padding:2.5rem 3rem;
-  background:var(--paper);
-  border:1px solid var(--border);
-  border-radius:18px;
-  box-shadow:0 12px 40px rgba(0,0,0,.06);
-}
-h1,h2,h3,h4,h5,h6{
-  font-family:"Helvetica Neue",Helvetica,Arial,sans-serif;
-  line-height:1.2;
-  margin-top:1.5em;
-}
-h1{font-size:2.2rem;border-bottom:1px solid var(--border);padding-bottom:.35rem;}
-h2{font-size:1.6rem;border-bottom:1px solid var(--border);padding-bottom:.25rem;}
-p,ul,ol,blockquote,table{margin:1rem 0;}
-pre,code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
-pre{
-  background:var(--code);
-  border:1px solid var(--border);
-  border-radius:12px;
-  padding:1rem 1.1rem;
-  overflow:auto;
-}
-code{
-  background:var(--code);
-  padding:.12rem .28rem;
-  border-radius:6px;
-}
-a{color:var(--link);text-decoration:none}
-a:hover{text-decoration:underline}
-img{max-width:100%}
-blockquote{
-  border-left:4px solid var(--border);
-  padding-left:1rem;
-  color:var(--quote);
-}
-table{border-collapse:collapse;width:100%}
-th,td{border:1px solid var(--border);padding:.55rem .7rem;text-align:left}
-</style></head><body><main>${stdout}</main></body></html>`;
-	const tempDir = await mkdtemp(join(tmpdir(), "feynman-preview-"));
-	const htmlPath = join(tempDir, `${basename(filePath)}.html`);
-	await writeFile(htmlPath, html, "utf8");
-	return htmlPath;
-}
-
-export async function renderPdfPreview(filePath: string): Promise<string> {
-	const source = await readFile(filePath, "utf8");
-	const pandocCommand = process.env.PANDOC_PATH?.trim() || "pandoc";
-	const pdfEngine = process.env.PANDOC_PDF_ENGINE?.trim() || "xelatex";
-	const inputFormat = isLatexPath(filePath)
-		? "latex"
-		: "markdown+lists_without_preceding_blankline+tex_math_dollars+autolink_bare_uris-raw_html";
-	const markdown = isLatexPath(filePath) || isMarkdownPath(filePath) ? source : wrapCodeAsMarkdown(source, filePath);
-	const tempDir = await mkdtemp(join(tmpdir(), "feynman-preview-"));
-	const pdfPath = join(tempDir, `${basename(filePath)}.pdf`);
-	const args = [
-		"-f",
-		inputFormat,
-		"-o",
-		pdfPath,
-		`--pdf-engine=${pdfEngine}`,
-		`--resource-path=${dirname(filePath)}`,
-	];
-	await runCommandWithInput(pandocCommand, args, markdown);
-	return pdfPath;
-}
-
-export async function pathExists(path: string): Promise<boolean> {
-	try {
-		await stat(path);
-		return true;
-	} catch {
-		return false;
-	}
-}

extensions/research-tools/project.ts

@@ -1,14 +1,70 @@
-import { mkdir, stat, writeFile } from "node:fs/promises";
-import { dirname, resolve as resolvePath } from "node:path";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative, resolve as resolvePath } from "node:path";
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
 
 import { getExtensionCommandSpec } from "../../metadata/commands.mjs";
-import { renderHtmlPreview, renderPdfPreview, openWithDefaultApp, pathExists } from "./preview.js";
 import { buildProjectAgentsTemplate, buildSessionLogsReadme } from "./project-scaffold.js";
-import { formatToolText } from "./shared.js";
-import { searchSessionTranscripts } from "./session-search.js";
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+const ARTIFACT_DIRS = ["papers", "outputs", "experiments", "notes"];
+const ARTIFACT_EXTS = new Set([".md", ".tex", ".pdf", ".py", ".csv", ".json", ".html", ".txt", ".log"]);
+
+async function collectArtifacts(cwd: string): Promise<{ label: string; path: string }[]> {
+	const items: { label: string; path: string; mtime: number }[] = [];
+
+	for (const dir of ARTIFACT_DIRS) {
+		const dirPath = resolvePath(cwd, dir);
+		if (!(await pathExists(dirPath))) continue;
+
+		const walk = async (current: string): Promise<void> => {
+			let entries;
+			try {
+				entries = await readdir(current, { withFileTypes: true });
+			} catch {
+				return;
+			}
+			for (const entry of entries) {
+				const full = join(current, entry.name);
+				if (entry.isDirectory()) {
+					await walk(full);
+				} else if (ARTIFACT_EXTS.has(entry.name.slice(entry.name.lastIndexOf(".")))) {
+					const rel = relative(cwd, full);
+					let title = "";
+					try {
+						const head = await readFile(full, "utf8").then((c) => c.slice(0, 200));
+						const match = head.match(/^#\s+(.+)/m);
+						if (match) title = match[1]!.trim();
+					} catch {}
+					const info = await stat(full).catch(() => null);
+					const mtime = info?.mtimeMs ?? 0;
+					const size = info ? formatSize(info.size) : "";
+					const titlePart = title ? ` — ${title}` : "";
+					items.push({ label: `${rel}${titlePart}  (${size})`, path: rel, mtime });
+				}
+			}
+		};
+
+		await walk(dirPath);
+	}
+
+	items.sort((a, b) => b.mtime - a.mtime);
+	return items;
+}
+
+function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)}KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
 
 export function registerInitCommand(pi: ExtensionAPI): void {
 	pi.registerCommand("init", {
@@ -45,73 +101,23 @@ export function registerInitCommand(pi: ExtensionAPI): void {
 	});
 }
 
-export function registerSessionSearchTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "session_search",
-		label: "Session Search",
-		description: "Search prior Feynman session transcripts to recover what was done, said, or written before.",
-		parameters: Type.Object({
-			query: Type.String({
-				description: "Search query to look for in past sessions.",
-			}),
-			limit: Type.Optional(
-				Type.Number({
-					description: "Maximum number of sessions to return. Defaults to 3.",
-				}),
-			),
-		}),
-		async execute(_toolCallId, params) {
-			const result = await searchSessionTranscripts(params.query, Math.max(1, Math.min(params.limit ?? 3, 8)));
-			return {
-				content: [{ type: "text", text: formatToolText(result) }],
-				details: result,
-			};
-		},
-	});
-}
-
-export function registerPreviewTool(pi: ExtensionAPI): void {
-	pi.registerTool({
-		name: "preview_file",
-		label: "Preview File",
-		description: "Open a markdown, LaTeX, PDF, or code artifact in the browser or a PDF viewer for human review. Rendered HTML/PDF previews are temporary and do not replace the source artifact.",
-		parameters: Type.Object({
-			path: Type.String({
-				description: "Path to the file to preview.",
-			}),
-			target: Type.Optional(
-				Type.String({
-					description: "Preview target: browser or pdf. Defaults to browser.",
-				}),
-			),
-		}),
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const target = (params.target?.trim().toLowerCase() || "browser");
-			if (target !== "browser" && target !== "pdf") {
-				throw new Error("target must be browser or pdf");
+export function registerOutputsCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("outputs", {
+		description: "Browse all research artifacts (papers, outputs, experiments, notes).",
+		handler: async (_args, ctx) => {
+			const items = await collectArtifacts(ctx.cwd);
+			if (items.length === 0) {
+				ctx.ui.notify("No artifacts found. Use /lit, /draft, /review, or /deepresearch to create some.", "info");
+				return;
 			}
 
-			const resolvedPath = resolvePath(ctx.cwd, params.path);
-			const openedPath =
-				resolvePath(resolvedPath).toLowerCase().endsWith(".pdf") && target === "pdf"
-					? resolvedPath
-					: target === "pdf"
-						? await renderPdfPreview(resolvedPath)
-						: await renderHtmlPreview(resolvedPath);
+			const selected = await ctx.ui.select(`Artifacts (${items.length})`, items.map((i) => i.label));
+			if (!selected) return;
 
-			await mkdir(dirname(openedPath), { recursive: true }).catch(() => {});
-			await openWithDefaultApp(openedPath);
-
-			const result = {
-				sourcePath: resolvedPath,
-				target,
-				openedPath,
-				temporaryPreview: openedPath !== resolvedPath,
-			};
-			return {
-				content: [{ type: "text", text: formatToolText(result) }],
-				details: result,
-			};
+			const match = items.find((i) => i.label === selected);
+			if (match) {
+				ctx.ui.setEditorText(`read ${match.path}`);
+			}
 		},
 	});
 }

extensions/research-tools/service-tier.ts

@@ -0,0 +1,174 @@
+import { homedir } from "node:os";
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+const FEYNMAN_SERVICE_TIERS = [
+	"auto",
+	"default",
+	"flex",
+	"priority",
+	"standard_only",
+] as const;
+
+type FeynmanServiceTier = (typeof FEYNMAN_SERVICE_TIERS)[number];
+
+const SERVICE_TIER_SET = new Set<string>(FEYNMAN_SERVICE_TIERS);
+const OPENAI_SERVICE_TIERS = new Set<FeynmanServiceTier>(["auto", "default", "flex", "priority"]);
+const ANTHROPIC_SERVICE_TIERS = new Set<FeynmanServiceTier>(["auto", "standard_only"]);
+
+type CommandContext = Parameters<Parameters<ExtensionAPI["registerCommand"]>[1]["handler"]>[1];
+
+type SelectOption<T> = {
+	label: string;
+	value: T;
+};
+
+function resolveFeynmanSettingsPath(): string {
+	const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+	const agentDir = configured
+		? configured.startsWith("~/")
+			? resolve(homedir(), configured.slice(2))
+			: resolve(configured)
+		: resolve(homedir(), ".feynman", "agent");
+	return resolve(agentDir, "settings.json");
+}
+
+function normalizeServiceTier(value: string | undefined): FeynmanServiceTier | undefined {
+	if (!value) return undefined;
+	const normalized = value.trim().toLowerCase();
+	return SERVICE_TIER_SET.has(normalized) ? (normalized as FeynmanServiceTier) : undefined;
+}
+
+function getConfiguredServiceTier(settingsPath: string): FeynmanServiceTier | undefined {
+	try {
+		const parsed = JSON.parse(readFileSync(settingsPath, "utf8")) as { serviceTier?: string };
+		return normalizeServiceTier(parsed.serviceTier);
+	} catch {
+		return undefined;
+	}
+}
+
+function setConfiguredServiceTier(settingsPath: string, tier: FeynmanServiceTier | undefined): void {
+	let settings: Record<string, unknown> = {};
+	try {
+		settings = JSON.parse(readFileSync(settingsPath, "utf8")) as Record<string, unknown>;
+	} catch {}
+
+	if (tier) {
+		settings.serviceTier = tier;
+	} else {
+		delete settings.serviceTier;
+	}
+
+	writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+}
+
+function resolveActiveServiceTier(settingsPath: string): FeynmanServiceTier | undefined {
+	return normalizeServiceTier(process.env.FEYNMAN_SERVICE_TIER) ?? getConfiguredServiceTier(settingsPath);
+}
+
+function resolveProviderServiceTier(
+	provider: string | undefined,
+	tier: FeynmanServiceTier | undefined,
+): FeynmanServiceTier | undefined {
+	if (!provider || !tier) return undefined;
+	if ((provider === "openai" || provider === "openai-codex") && OPENAI_SERVICE_TIERS.has(tier)) {
+		return tier;
+	}
+	if (provider === "anthropic" && ANTHROPIC_SERVICE_TIERS.has(tier)) {
+		return tier;
+	}
+	return undefined;
+}
+
+async function selectOption<T>(
+	ctx: CommandContext,
+	title: string,
+	options: SelectOption<T>[],
+): Promise<T | undefined> {
+	const selected = await ctx.ui.select(
+		title,
+		options.map((option) => option.label),
+	);
+	if (!selected) return undefined;
+	return options.find((option) => option.label === selected)?.value;
+}
+
+function parseRequestedTier(rawArgs: string): FeynmanServiceTier | null | undefined {
+	const trimmed = rawArgs.trim();
+	if (!trimmed) return undefined;
+	if (trimmed === "unset" || trimmed === "clear" || trimmed === "off") return null;
+	return normalizeServiceTier(trimmed);
+}
+
+export function registerServiceTierControls(pi: ExtensionAPI): void {
+	pi.on("before_provider_request", (event, ctx) => {
+		if (!ctx.model || !event.payload || typeof event.payload !== "object") {
+			return;
+		}
+
+		const activeTier = resolveActiveServiceTier(resolveFeynmanSettingsPath());
+		const providerTier = resolveProviderServiceTier(ctx.model.provider, activeTier);
+		if (!providerTier) {
+			return;
+		}
+
+		return {
+			...(event.payload as Record<string, unknown>),
+			service_tier: providerTier,
+		};
+	});
+
+	pi.registerCommand("service-tier", {
+		description: "View or set the provider service tier override used for supported models.",
+		handler: async (args, ctx) => {
+			const settingsPath = resolveFeynmanSettingsPath();
+			const requested = parseRequestedTier(args);
+
+			if (requested === undefined && !args.trim()) {
+				if (!ctx.hasUI) {
+					ctx.ui.notify(getConfiguredServiceTier(settingsPath) ?? "not set", "info");
+					return;
+				}
+
+				const current = getConfiguredServiceTier(settingsPath);
+				const selected = await selectOption(
+					ctx,
+					"Select service tier",
+					[
+						{ label: current ? `unset (current: ${current})` : "unset (current)", value: null },
+						...FEYNMAN_SERVICE_TIERS.map((tier) => ({
+							label: tier === current ? `${tier} (current)` : tier,
+							value: tier,
+						})),
+					],
+				);
+				if (selected === undefined) return;
+				if (selected === null) {
+					setConfiguredServiceTier(settingsPath, undefined);
+					ctx.ui.notify("Cleared service tier override.", "info");
+					return;
+				}
+				setConfiguredServiceTier(settingsPath, selected);
+				ctx.ui.notify(`Service tier set to ${selected}.`, "info");
+				return;
+			}
+
+			if (requested === null) {
+				setConfiguredServiceTier(settingsPath, undefined);
+				ctx.ui.notify("Cleared service tier override.", "info");
+				return;
+			}
+
+			if (!requested) {
+				ctx.ui.notify("Use auto, default, flex, priority, standard_only, or unset.", "error");
+				return;
+			}
+
+			setConfiguredServiceTier(settingsPath, requested);
+			ctx.ui.notify(`Service tier set to ${requested}.`, "info");
+		},
+	});
+}

extensions/research-tools/session-search.ts

@@ -1,223 +0,0 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { basename, join } from "node:path";
-import { pathToFileURL } from "node:url";
-
-import { getFeynmanHome } from "./shared.js";
-
-function extractMessageText(message: unknown): string {
-	if (!message || typeof message !== "object") {
-		return "";
-	}
-
-	const content = (message as { content?: unknown }).content;
-	if (typeof content === "string") {
-		return content;
-	}
-	if (!Array.isArray(content)) {
-		return "";
-	}
-
-	return content
-		.map((item) => {
-			if (!item || typeof item !== "object") {
-				return "";
-			}
-			const record = item as { type?: string; text?: unknown; arguments?: unknown; name?: unknown };
-			if (record.type === "text" && typeof record.text === "string") {
-				return record.text;
-			}
-			if (record.type === "toolCall") {
-				const name = typeof record.name === "string" ? record.name : "tool";
-				const args =
-					typeof record.arguments === "string"
-						? record.arguments
-						: record.arguments
-							? JSON.stringify(record.arguments)
-							: "";
-				return `[tool:${name}] ${args}`;
-			}
-			return "";
-		})
-		.filter(Boolean)
-		.join("\n");
-}
-
-function buildExcerpt(text: string, query: string, radius = 180): string {
-	const normalizedText = text.replace(/\s+/g, " ").trim();
-	if (!normalizedText) {
-		return "";
-	}
-
-	const lower = normalizedText.toLowerCase();
-	const q = query.toLowerCase();
-	const index = lower.indexOf(q);
-	if (index === -1) {
-		return normalizedText.slice(0, radius * 2) + (normalizedText.length > radius * 2 ? "..." : "");
-	}
-
-	const start = Math.max(0, index - radius);
-	const end = Math.min(normalizedText.length, index + q.length + radius);
-	const prefix = start > 0 ? "..." : "";
-	const suffix = end < normalizedText.length ? "..." : "";
-	return `${prefix}${normalizedText.slice(start, end)}${suffix}`;
-}
-
-export async function searchSessionTranscripts(query: string, limit: number): Promise<{
-	query: string;
-	results: Array<{
-		sessionId: string;
-		sessionFile: string;
-		startedAt?: string;
-		cwd?: string;
-		matchCount: number;
-		topMatches: Array<{ role: string; timestamp?: string; excerpt: string }>;
-	}>;
-}> {
-	const packageRoot = process.env.FEYNMAN_PI_NPM_ROOT;
-	if (packageRoot) {
-		try {
-			const indexerPath = pathToFileURL(
-				join(packageRoot, "@kaiserlich-dev", "pi-session-search", "extensions", "indexer.ts"),
-			).href;
-			const indexer = await import(indexerPath) as {
-				updateIndex?: (onProgress?: (msg: string) => void) => Promise<number>;
-				search?: (query: string, limit?: number) => Array<{
-					sessionPath: string;
-					project: string;
-					timestamp: string;
-					snippet: string;
-					rank: number;
-					title: string | null;
-				}>;
-				getSessionSnippets?: (sessionPath: string, query: string, limit?: number) => string[];
-			};
-
-			await indexer.updateIndex?.();
-			const results = indexer.search?.(query, limit) ?? [];
-			if (results.length > 0) {
-				return {
-					query,
-					results: results.map((result) => ({
-						sessionId: basename(result.sessionPath),
-						sessionFile: result.sessionPath,
-						startedAt: result.timestamp,
-						cwd: result.project,
-						matchCount: 1,
-						topMatches: (indexer.getSessionSnippets?.(result.sessionPath, query, 4) ?? [result.snippet])
-							.filter(Boolean)
-							.map((excerpt) => ({
-								role: "match",
-								excerpt,
-							})),
-					})),
-				};
-			}
-		} catch {
-			// Fall back to direct JSONL scanning below.
-		}
-	}
-
-	const sessionDir = join(getFeynmanHome(), "sessions");
-	const terms = query
-		.toLowerCase()
-		.split(/\s+/)
-		.map((term) => term.trim())
-		.filter((term) => term.length >= 2);
-	const needle = query.toLowerCase();
-
-	let files: string[] = [];
-	try {
-		files = (await readdir(sessionDir))
-			.filter((entry) => entry.endsWith(".jsonl"))
-			.map((entry) => join(sessionDir, entry));
-	} catch {
-		return { query, results: [] };
-	}
-
-	const sessions = [];
-	for (const file of files) {
-		const raw = await readFile(file, "utf8").catch(() => "");
-		if (!raw) {
-			continue;
-		}
-
-		let sessionId = basename(file);
-		let startedAt: string | undefined;
-		let cwd: string | undefined;
-		const matches: Array<{ role: string; timestamp?: string; excerpt: string }> = [];
-
-		for (const line of raw.split("\n")) {
-			if (!line.trim()) {
-				continue;
-			}
-			try {
-				const record = JSON.parse(line) as {
-					type?: string;
-					id?: string;
-					timestamp?: string;
-					cwd?: string;
-					message?: { role?: string; content?: unknown };
-				};
-				if (record.type === "session") {
-					sessionId = record.id ?? sessionId;
-					startedAt = record.timestamp;
-					cwd = record.cwd;
-					continue;
-				}
-				if (record.type !== "message" || !record.message) {
-					continue;
-				}
-
-				const text = extractMessageText(record.message);
-				if (!text) {
-					continue;
-				}
-				const lower = text.toLowerCase();
-				const matched = lower.includes(needle) || terms.some((term) => lower.includes(term));
-				if (!matched) {
-					continue;
-				}
-				matches.push({
-					role: record.message.role ?? "unknown",
-					timestamp: record.timestamp,
-					excerpt: buildExcerpt(text, query),
-				});
-			} catch {
-				continue;
-			}
-		}
-
-		if (matches.length === 0) {
-			continue;
-		}
-
-		let mtime = 0;
-		try {
-			mtime = (await stat(file)).mtimeMs;
-		} catch {
-			mtime = 0;
-		}
-
-		sessions.push({
-			sessionId,
-			sessionFile: file,
-			startedAt,
-			cwd,
-			matchCount: matches.length,
-			topMatches: matches.slice(0, 4),
-			mtime,
-		});
-	}
-
-	sessions.sort((a, b) => {
-		if (b.matchCount !== a.matchCount) {
-			return b.matchCount - a.matchCount;
-		}
-		return b.mtime - a.mtime;
-	});
-
-	return {
-		query,
-		results: sessions.slice(0, limit).map(({ mtime: _mtime, ...session }) => session),
-	};
-}

extensions/research-tools/shared.ts

@@ -1,5 +1,4 @@
 import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -15,25 +14,3 @@ export const FEYNMAN_VERSION = (() => {
 })();
 
 export { FEYNMAN_ASCII_LOGO as FEYNMAN_AGENT_LOGO } from "../../logo.mjs";
-
-export const FEYNMAN_RESEARCH_TOOLS = [
-	"alpha_search",
-	"alpha_get_paper",
-	"alpha_ask_paper",
-	"alpha_annotate_paper",
-	"alpha_list_annotations",
-	"alpha_read_code",
-	"session_search",
-	"preview_file",
-];
-
-export function formatToolText(result: unknown): string {
-	return typeof result === "string" ? result : JSON.stringify(result, null, 2);
-}
-
-export function getFeynmanHome(): string {
-	const agentDir = process.env.FEYNMAN_CODING_AGENT_DIR ??
-		process.env.PI_CODING_AGENT_DIR ??
-		resolvePath(homedir(), ".feynman", "agent");
-	return dirname(agentDir);
-}

metadata/commands.mjs

@@ -35,11 +35,14 @@ export function readPromptSpecs(appRoot) {
 }
 
 export const extensionCommandSpecs = [
+	{ name: "capabilities", args: "", section: "Project & Session", description: "Show installed packages, discovery entrypoints, and runtime capability counts.", publicDocs: true },
+	{ name: "commands", args: "", section: "Project & Session", description: "Browse all available slash commands, including built-in and package commands.", publicDocs: true },
 	{ name: "help", args: "", section: "Project & Session", description: "Show grouped Feynman commands and prefill the editor with a selected command.", publicDocs: true },
+	{ name: "feynman-model", args: "", section: "Project & Session", description: "Open Feynman model menu (main + per-subagent overrides).", publicDocs: true },
 	{ name: "init", args: "", section: "Project & Session", description: "Bootstrap AGENTS.md and session-log folders for a research project.", publicDocs: true },
-	{ name: "alpha-login", args: "", section: "Setup", description: "Sign in to alphaXiv from inside Feynman.", publicDocs: true },
-	{ name: "alpha-status", args: "", section: "Setup", description: "Show alphaXiv authentication status.", publicDocs: true },
-	{ name: "alpha-logout", args: "", section: "Setup", description: "Clear alphaXiv auth from inside Feynman.", publicDocs: true },
+	{ name: "outputs", args: "", section: "Project & Session", description: "Browse all research artifacts (papers, outputs, experiments, notes).", publicDocs: true },
+	{ name: "service-tier", args: "", section: "Project & Session", description: "View or set the provider service tier override for supported models.", publicDocs: true },
+	{ name: "tools", args: "", section: "Project & Session", description: "Browse all callable tools with their source and parameter summary.", publicDocs: true },
 ];
 
 export const livePackageCommandGroups = [
@@ -59,6 +62,7 @@ export const livePackageCommandGroups = [
 			{ name: "schedule-prompt", usage: "/schedule-prompt" },
 			{ name: "search", usage: "/search" },
 			{ name: "preview", usage: "/preview" },
+			{ name: "hotkeys", usage: "/hotkeys" },
 			{ name: "new", usage: "/new" },
 			{ name: "quit", usage: "/quit" },
 			{ name: "exit", usage: "/exit" },
@@ -85,6 +89,7 @@ export const cliCommandSections = [
 			{ usage: "feynman model login [id]", description: "Login to a Pi OAuth model provider." },
 			{ usage: "feynman model logout [id]", description: "Logout from a Pi OAuth model provider." },
 			{ usage: "feynman model set <provider/model>", description: "Set the default model." },
+			{ usage: "feynman model tier [value]", description: "View or set the request service tier override." },
 		],
 	},
 	{
@@ -101,6 +106,8 @@ export const cliCommandSections = [
 			{ usage: "feynman packages list", description: "Show core and optional Pi package presets." },
 			{ usage: "feynman packages install <preset>", description: "Install optional package presets on demand." },
 			{ usage: "feynman search status", description: "Show Pi web-access status and config path." },
+			{ usage: "feynman search set <provider> [api-key]", description: "Set the web search provider and optionally save its API key." },
+			{ usage: "feynman search clear", description: "Reset web search provider to auto while preserving API keys." },
 			{ usage: "feynman update [package]", description: "Update installed packages, or a specific package." },
 		],
 	},
@@ -112,6 +119,7 @@ export const legacyFlags = [
 	{ usage: "--alpha-logout", description: "Clear alphaXiv auth and exit." },
 	{ usage: "--alpha-status", description: "Show alphaXiv auth status and exit." },
 	{ usage: "--model <provider:model>", description: "Force a specific model." },
+	{ usage: "--service-tier <tier>", description: "Override request service tier for this run." },
 	{ usage: "--thinking <level>", description: "Set thinking level: off | minimal | low | medium | high | xhigh." },
 	{ usage: "--cwd <path>", description: "Set the working directory for tools." },
 	{ usage: "--session-dir <path>", description: "Set the session storage directory." },

package-lock.json

@@ -1,17 +1,18 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.2.12",
+  "version": "0.2.17",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@companion-ai/feynman",
-      "version": "0.2.12",
+      "version": "0.2.17",
       "hasInstallScript": true,
+      "license": "MIT",
       "dependencies": {
         "@companion-ai/alpha-hub": "^0.1.2",
-        "@mariozechner/pi-ai": "^0.62.0",
-        "@mariozechner/pi-coding-agent": "^0.62.0",
+        "@mariozechner/pi-ai": "^0.64.0",
+        "@mariozechner/pi-coding-agent": "^0.64.0",
         "@sinclair/typebox": "^0.34.48",
         "dotenv": "^17.3.1"
       },
@@ -24,7 +25,7 @@
         "typescript": "^5.9.3"
       },
       "engines": {
-        "node": ">=20.18.1"
+        "node": ">=20.19.0"
       }
     },
     "node_modules/@anthropic-ai/sdk": {
@@ -1264,9 +1265,9 @@
       }
     },
     "node_modules/@hono/node-server": {
-      "version": "1.19.11",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.11.tgz",
-      "integrity": "sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g==",
+      "version": "1.19.13",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.13.tgz",
+      "integrity": "sha512-TsQLe4i2gvoTtrHje625ngThGBySOgSK3Xo2XRYOdqGN1teR8+I7vchQC46uLJi8OF62YTYA3AhSpumtkhsaKQ==",
       "license": "MIT",
       "engines": {
         "node": ">=18.14.1"
@@ -1468,21 +1469,21 @@
       }
     },
     "node_modules/@mariozechner/pi-agent-core": {
-      "version": "0.62.0",
-      "resolved": "https://registry.npmjs.org/@mariozechner/pi-agent-core/-/pi-agent-core-0.62.0.tgz",
-      "integrity": "sha512-SBjqgDrgKOaC+IGzFGB3jXQErv9H1QMYnWFvUg6ra6dG0ZgWFBUZb6unidngWLsmaxSDWes6KeKiVFMsr2VSEQ==",
+      "version": "0.64.0",
+      "resolved": "https://registry.npmjs.org/@mariozechner/pi-agent-core/-/pi-agent-core-0.64.0.tgz",
+      "integrity": "sha512-IN/sIxWOD0v1OFVXHB605SGiZhO5XdEWG5dO8EAV08n3jz/p12o4OuYGvhGXmHhU28WXa/FGWC+FO5xiIih8Uw==",
       "license": "MIT",
       "dependencies": {
-        "@mariozechner/pi-ai": "^0.62.0"
+        "@mariozechner/pi-ai": "^0.64.0"
       },
       "engines": {
         "node": ">=20.0.0"
       }
     },
     "node_modules/@mariozechner/pi-ai": {
-      "version": "0.62.0",
-      "resolved": "https://registry.npmjs.org/@mariozechner/pi-ai/-/pi-ai-0.62.0.tgz",
-      "integrity": "sha512-mJgryZ5RgBQG++tiETMtCQQJoH2MAhKetCfqI98NMvGydu7L9x2qC2JekQlRaAgIlTgv4MRH1UXHMEs4UweE/Q==",
+      "version": "0.64.0",
+      "resolved": "https://registry.npmjs.org/@mariozechner/pi-ai/-/pi-ai-0.64.0.tgz",
+      "integrity": "sha512-Z/Jnf+JSVDPLRcxJsa8XhYTJKIqKekNueaCpBLGQHgizL1F9RQ1Rur3rIfZpfXkt2cLu/AIPtOs223ueuoWaWg==",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.73.0",
@@ -1507,16 +1508,17 @@
       }
     },
     "node_modules/@mariozechner/pi-coding-agent": {
-      "version": "0.62.0",
-      "resolved": "https://registry.npmjs.org/@mariozechner/pi-coding-agent/-/pi-coding-agent-0.62.0.tgz",
-      "integrity": "sha512-f1NnExqsHuA6w8UVlBtPsvTBhdkMc0h1JD9SzGCdWTLou5GHJr2JIP6DlwV9IKWAnM+sAelaoFez+14wLP2zOQ==",
+      "version": "0.64.0",
+      "resolved": "https://registry.npmjs.org/@mariozechner/pi-coding-agent/-/pi-coding-agent-0.64.0.tgz",
+      "integrity": "sha512-Q4tcqSqFGQtOgCtRyIp1D80Nv2if13Q2pfbnrOlaT/mix90mLcZGML9jKVnT1jGSy5GMYudU1HsS7cx53kxb0g==",
       "license": "MIT",
       "dependencies": {
         "@mariozechner/jiti": "^2.6.2",
-        "@mariozechner/pi-agent-core": "^0.62.0",
-        "@mariozechner/pi-ai": "^0.62.0",
-        "@mariozechner/pi-tui": "^0.62.0",
+        "@mariozechner/pi-agent-core": "^0.64.0",
+        "@mariozechner/pi-ai": "^0.64.0",
+        "@mariozechner/pi-tui": "^0.64.0",
         "@silvia-odwyer/photon-node": "^0.3.4",
+        "ajv": "^8.17.1",
         "chalk": "^5.5.0",
         "cli-highlight": "^2.1.11",
         "diff": "^8.0.2",
@@ -1543,9 +1545,9 @@
       }
     },
     "node_modules/@mariozechner/pi-tui": {
-      "version": "0.62.0",
-      "resolved": "https://registry.npmjs.org/@mariozechner/pi-tui/-/pi-tui-0.62.0.tgz",
-      "integrity": "sha512-/At11PPe8l319MnUoK4wN5L/uVCU6bDdiIUzH8Ez0stOkjSF6isRXScZ+RMM+6iCKsD4muBTX8Cmcif+3/UWHA==",
+      "version": "0.64.0",
+      "resolved": "https://registry.npmjs.org/@mariozechner/pi-tui/-/pi-tui-0.64.0.tgz",
+      "integrity": "sha512-W1qLry9MAuN/V3YJmMv/BJa0VaYv721NkXPg/DGItdqWxuDc+1VdNbyAnRwxblNkIpXVUWL26x64BlyFXpxmkg==",
       "license": "MIT",
       "dependencies": {
         "@types/mime-types": "^2.1.4",
@@ -2528,9 +2530,9 @@
       "license": "MIT"
     },
     "node_modules/basic-ftp": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.2.0.tgz",
-      "integrity": "sha512-VoMINM2rqJwJgfdHq6RiUudKt2BV+FY5ZFezP/ypmwayk68+NzzAQy4XXLlqsGD4MCzq3DrmNFD/uUmBJuGoXw==",
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.2.1.tgz",
+      "integrity": "sha512-0yaL8JdxTknKDILitVpfYfV2Ob6yb3udX/hK97M7I3jOeznBNxQPtVvTUtnhUkyHlxFWyr5Lvknmgzoc7jf+1Q==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"
@@ -2576,9 +2578,9 @@
       "license": "MIT"
     },
     "node_modules/brace-expansion": {
-      "version": "5.0.4",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.4.tgz",
-      "integrity": "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg==",
+      "version": "5.0.5",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
+      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
       "license": "MIT",
       "dependencies": {
         "balanced-match": "^4.0.2"
@@ -3621,9 +3623,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.9",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.9.tgz",
-      "integrity": "sha512-wy3T8Zm2bsEvxKZM5w21VdHDDcwVS1yUFFY6i8UobSsKfFceT7TOwhbhfKsDyx7tYQlmRM5FLpIuYvNFyjctiA==",
+      "version": "4.12.12",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.12.tgz",
+      "integrity": "sha512-p1JfQMKaceuCbpJKAPKVqyqviZdS0eUxH9v82oWo1kb9xjQ5wA6iP3FNVAPDFlz5/p7d45lO+BpSk1tuSZMF4Q==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -4216,9 +4218,9 @@
       }
     },
     "node_modules/path-to-regexp": {
-      "version": "8.3.0",
-      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.3.0.tgz",
-      "integrity": "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==",
+      "version": "8.4.2",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz",
+      "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==",
       "license": "MIT",
       "funding": {
         "type": "opencollective",

package.json

@@ -1,11 +1,11 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.2.12",
+  "version": "0.2.17",
   "description": "Research-first CLI agent built on Pi and alphaXiv",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=20.18.1"
+    "node": ">=20.19.0"
   },
   "bin": {
     "feynman": "bin/feynman.js"
@@ -26,15 +26,16 @@
     "scripts/",
     "skills/",
     "AGENTS.md",
+    "CONTRIBUTING.md",
     "README.md",
     ".env.example"
   ],
   "scripts": {
+    "preinstall": "node ./scripts/check-node-version.mjs",
     "build": "tsc -p tsconfig.build.json",
     "build:native-bundle": "node ./scripts/build-native-bundle.mjs",
     "dev": "tsx src/index.ts",
-    "prepack": "node ./scripts/prepare-runtime-workspace.mjs",
-    "postinstall": "node ./scripts/patch-embedded-pi.mjs",
+    "prepack": "node ./scripts/clean-publish-artifacts.mjs && npm run build && node ./scripts/prepare-runtime-workspace.mjs",
     "start": "tsx src/index.ts",
     "start:dist": "node ./bin/feynman.js",
     "test": "node --import tsx --test --test-concurrency=1 tests/*.test.ts",
@@ -52,15 +53,40 @@
     ],
     "prompts": [
       "./prompts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "dependencies": {
     "@companion-ai/alpha-hub": "^0.1.2",
-    "@mariozechner/pi-ai": "^0.62.0",
-    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "@mariozechner/pi-ai": "^0.64.0",
+    "@mariozechner/pi-coding-agent": "^0.64.0",
     "@sinclair/typebox": "^0.34.48",
     "dotenv": "^17.3.1"
   },
+  "overrides": {
+    "basic-ftp": "5.2.1",
+    "@modelcontextprotocol/sdk": {
+      "@hono/node-server": "1.19.13",
+      "hono": "4.12.12"
+    },
+    "express": {
+      "router": {
+        "path-to-regexp": "8.4.2"
+      }
+    },
+    "proxy-agent": {
+      "pac-proxy-agent": {
+        "get-uri": {
+          "basic-ftp": "5.2.1"
+        }
+      }
+    },
+    "minimatch": {
+      "brace-expansion": "5.0.5"
+    }
+  },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsx": "^4.21.0",

prompts/autoresearch.md

@@ -27,6 +27,8 @@ Ask the user where to run:
 - **New git branch** — create a branch so main stays clean
 - **Virtual environment** — create an isolated venv/conda env first
 - **Docker** — run experiment code inside an isolated Docker container
+- **Modal** — run on Modal's serverless GPU infrastructure. Write Modal-decorated scripts and execute with `modal run`. Best for GPU-heavy benchmarks with no persistent state between iterations. Requires `modal` CLI.
+- **RunPod** — provision a GPU pod via `runpodctl` and run iterations there over SSH. Best for experiments needing persistent state, large datasets, or SSH access between iterations. Requires `runpodctl` CLI.
 
 Do not proceed without a clear answer.
 

prompts/replicate.md

@@ -14,6 +14,8 @@ Design a replication plan for: $@
    - **Local** — run in the current working directory
    - **Virtual environment** — create an isolated venv/conda env first
    - **Docker** — run experiment code inside an isolated Docker container
+   - **Modal** — run on Modal's serverless GPU infrastructure. Write a Modal-decorated Python script and execute with `modal run <script.py>`. Best for burst GPU jobs that don't need persistent state. Requires `modal` CLI (`pip install modal && modal setup`).
+   - **RunPod** — provision a GPU pod on RunPod and SSH in for execution. Use `runpodctl` to create pods, transfer files, and manage lifecycle. Best for long-running experiments or when you need SSH access and persistent storage. Requires `runpodctl` CLI and `RUNPOD_API_KEY`.
    - **Plan only** — produce the replication plan without executing
 4. **Execute** — If the user chose an execution environment, implement and run the replication steps there. Save notes, scripts, raw outputs, and results to disk in a reproducible layout. Do not call the outcome replicated unless the planned checks actually passed.
 5. **Log** — For multi-step or resumable replication work, append concise entries to `CHANGELOG.md` after meaningful progress, failed attempts, major verification outcomes, and before stopping. Record the active objective, what changed, what was checked, and the next step.

scripts/build-native-bundle.mjs

@@ -6,13 +6,45 @@ import { spawnSync } from "node:child_process";
 const appRoot = resolve(import.meta.dirname, "..");
 const packageJson = JSON.parse(readFileSync(resolve(appRoot, "package.json"), "utf8"));
 const packageLockPath = resolve(appRoot, "package-lock.json");
-const bundledNodeVersion = process.env.FEYNMAN_BUNDLED_NODE_VERSION ?? process.version.slice(1);
+const minBundledNodeVersion = packageJson.engines?.node?.replace(/^>=/, "").trim() || process.version.slice(1);
+
+function parseSemver(version) {
+	const [major = "0", minor = "0", patch = "0"] = version.split(".");
+	return [Number.parseInt(major, 10) || 0, Number.parseInt(minor, 10) || 0, Number.parseInt(patch, 10) || 0];
+}
+
+function compareSemver(left, right) {
+	for (let index = 0; index < 3; index += 1) {
+		const diff = left[index] - right[index];
+		if (diff !== 0) return diff;
+	}
+	return 0;
+}
 
 function fail(message) {
 	console.error(`[feynman] ${message}`);
 	process.exit(1);
 }
 
+function resolveBundledNodeVersion() {
+	const requestedNodeVersion = process.env.FEYNMAN_BUNDLED_NODE_VERSION?.trim();
+	if (requestedNodeVersion) {
+		if (compareSemver(parseSemver(requestedNodeVersion), parseSemver(minBundledNodeVersion)) < 0) {
+			fail(
+				`FEYNMAN_BUNDLED_NODE_VERSION=${requestedNodeVersion} is below the supported floor ${minBundledNodeVersion}`,
+			);
+		}
+		return requestedNodeVersion;
+	}
+
+	const currentNodeVersion = process.version.slice(1);
+	return compareSemver(parseSemver(currentNodeVersion), parseSemver(minBundledNodeVersion)) < 0
+		? minBundledNodeVersion
+		: currentNodeVersion;
+}
+
+const bundledNodeVersion = resolveBundledNodeVersion();
+
 function resolveCommand(command) {
 	if (process.platform === "win32" && command === "npm") {
 		return "npm.cmd";
@@ -136,6 +168,7 @@ function ensureBundledWorkspace() {
 }
 
 function copyPackageFiles(appDir) {
+	const releaseDir = resolve(appRoot, "dist", "release");
 	cpSync(resolve(appRoot, "package.json"), resolve(appDir, "package.json"));
 	for (const entry of packageJson.files) {
 		const normalized = entry.endsWith("/") ? entry.slice(0, -1) : entry;
@@ -143,7 +176,10 @@ function copyPackageFiles(appDir) {
 		if (!existsSync(source)) continue;
 		const destination = resolve(appDir, normalized);
 		mkdirSync(dirname(destination), { recursive: true });
-		cpSync(source, destination, { recursive: true });
+		cpSync(source, destination, {
+			recursive: true,
+			filter: (path) => path !== releaseDir && !path.startsWith(`${releaseDir}/`),
+		});
 	}
 
 	cpSync(packageLockPath, resolve(appDir, "package-lock.json"));
@@ -160,6 +196,9 @@ function installAppDependencies(appDir, stagingRoot) {
 	run("npm", ["ci", "--omit=dev", "--ignore-scripts", "--no-audit", "--no-fund", "--loglevel", "error"], {
 		cwd: depsDir,
 	});
+	run(process.execPath, [resolve(appRoot, "scripts", "prune-runtime-deps.mjs"), depsDir], {
+		cwd: appRoot,
+	});
 
 	cpSync(resolve(depsDir, "node_modules"), resolve(appDir, "node_modules"), { recursive: true });
 }
@@ -236,7 +275,8 @@ function writeLauncher(bundleRoot, target) {
 			"@echo off",
 			"setlocal",
 			'set "ROOT=%~dp0"',
-			'"%ROOT%node\\node.exe" "%ROOT%app\\bin\\feynman.js" %*',
+			'if "%ROOT:~-1%"=="\\" set "ROOT=%ROOT:~0,-1%"',
+			'"%ROOT%\\node\\node.exe" "%ROOT%\\app\\bin\\feynman.js" %*',
 			"",
 		].join("\r\n"),
 		"utf8",
@@ -270,10 +310,12 @@ function packBundle(bundleRoot, target, outDir) {
 
 	if (target.bundleExtension === "zip") {
 		if (process.platform === "win32") {
+			const bundleDir = dirname(bundleRoot).replace(/'/g, "''");
+			const bundleName = basename(bundleRoot).replace(/'/g, "''");
 			run("powershell", [
 				"-NoProfile",
 				"-Command",
-				`Compress-Archive -Path '${bundleRoot.replace(/'/g, "''")}\\*' -DestinationPath '${archivePath.replace(/'/g, "''")}' -Force`,
+				`Push-Location '${bundleDir}'; Compress-Archive -Path '${bundleName}' -DestinationPath '${archivePath.replace(/'/g, "''")}' -Force; Pop-Location`,
 			]);
 		} else {
 			run("zip", ["-qr", archivePath, basename(bundleRoot)], { cwd: resolve(bundleRoot, "..") });

scripts/check-node-version.mjs

@@ -0,0 +1,40 @@
+const MIN_NODE_VERSION = "20.19.0";
+
+function parseNodeVersion(version) {
+	const [major = "0", minor = "0", patch = "0"] = version.replace(/^v/, "").split(".");
+	return {
+		major: Number.parseInt(major, 10) || 0,
+		minor: Number.parseInt(minor, 10) || 0,
+		patch: Number.parseInt(patch, 10) || 0,
+	};
+}
+
+function compareNodeVersions(left, right) {
+	if (left.major !== right.major) return left.major - right.major;
+	if (left.minor !== right.minor) return left.minor - right.minor;
+	return left.patch - right.patch;
+}
+
+function isSupportedNodeVersion(version = process.versions.node) {
+	return compareNodeVersions(parseNodeVersion(version), parseNodeVersion(MIN_NODE_VERSION)) >= 0;
+}
+
+function getUnsupportedNodeVersionLines(version = process.versions.node) {
+	const isWindows = process.platform === "win32";
+	return [
+		`feynman requires Node.js ${MIN_NODE_VERSION} or later (detected ${version}).`,
+		isWindows
+			? "Install a newer Node.js from https://nodejs.org, or use the standalone installer:"
+			: "Switch to Node 20 with `nvm install 20 && nvm use 20`, or use the standalone installer:",
+		isWindows
+			? "irm https://feynman.is/install.ps1 | iex"
+			: "curl -fsSL https://feynman.is/install | bash",
+	];
+}
+
+if (!isSupportedNodeVersion()) {
+	for (const line of getUnsupportedNodeVersionLines()) {
+		console.error(line);
+	}
+	process.exit(1);
+}

scripts/clean-publish-artifacts.mjs

@@ -0,0 +1,8 @@
+import { rmSync } from "node:fs";
+import { resolve } from "node:path";
+
+const appRoot = resolve(import.meta.dirname, "..");
+const releaseDir = resolve(appRoot, "dist", "release");
+
+rmSync(releaseDir, { recursive: true, force: true });
+console.log("[feynman] removed dist/release before npm pack/publish");

scripts/install/install-skills.ps1

@@ -0,0 +1,128 @@
+param(
+  [string]$Version = "latest",
+  [ValidateSet("User", "Repo")]
+  [string]$Scope = "User",
+  [string]$TargetDir = ""
+)
+
+$ErrorActionPreference = "Stop"
+
+function Normalize-Version {
+  param([string]$RequestedVersion)
+
+  if (-not $RequestedVersion) {
+    return "latest"
+  }
+
+  switch ($RequestedVersion.ToLowerInvariant()) {
+    "latest" { return "latest" }
+    "stable" { return "latest" }
+    "edge" { throw "The edge channel has been removed. Use the default installer for the latest tagged release or pass an exact version." }
+    default { return $RequestedVersion.TrimStart("v") }
+  }
+}
+
+function Resolve-LatestReleaseVersion {
+  $page = Invoke-WebRequest -Uri "https://github.com/getcompanion-ai/feynman/releases/latest"
+  $match = [regex]::Match($page.Content, 'releases/tag/v([0-9][^"''<>\s]*)')
+  if (-not $match.Success) {
+    throw "Failed to resolve the latest Feynman release version."
+  }
+
+  return $match.Groups[1].Value
+}
+
+function Resolve-VersionMetadata {
+  param([string]$RequestedVersion)
+
+  $normalizedVersion = Normalize-Version -RequestedVersion $RequestedVersion
+
+  if ($normalizedVersion -eq "latest") {
+    $resolvedVersion = Resolve-LatestReleaseVersion
+  } else {
+    $resolvedVersion = $normalizedVersion
+  }
+
+  return [PSCustomObject]@{
+    ResolvedVersion = $resolvedVersion
+    GitRef = "v$resolvedVersion"
+    DownloadUrl = if ($env:FEYNMAN_INSTALL_SKILLS_ARCHIVE_URL) { $env:FEYNMAN_INSTALL_SKILLS_ARCHIVE_URL } else { "https://github.com/getcompanion-ai/feynman/archive/refs/tags/v$resolvedVersion.zip" }
+  }
+}
+
+function Resolve-InstallDir {
+  param(
+    [string]$ResolvedScope,
+    [string]$ResolvedTargetDir
+  )
+
+  if ($ResolvedTargetDir) {
+    return $ResolvedTargetDir
+  }
+
+  if ($ResolvedScope -eq "Repo") {
+    return Join-Path (Get-Location) ".agents\skills\feynman"
+  }
+
+  $codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $HOME ".codex" }
+  return Join-Path $codexHome "skills\feynman"
+}
+
+$metadata = Resolve-VersionMetadata -RequestedVersion $Version
+$resolvedVersion = $metadata.ResolvedVersion
+$downloadUrl = $metadata.DownloadUrl
+$installDir = Resolve-InstallDir -ResolvedScope $Scope -ResolvedTargetDir $TargetDir
+
+$tmpDir = Join-Path ([System.IO.Path]::GetTempPath()) ("feynman-skills-install-" + [System.Guid]::NewGuid().ToString("N"))
+New-Item -ItemType Directory -Path $tmpDir | Out-Null
+
+try {
+  $archivePath = Join-Path $tmpDir "feynman-skills.zip"
+  $extractDir = Join-Path $tmpDir "extract"
+
+  Write-Host "==> Downloading Feynman skills $resolvedVersion"
+  Invoke-WebRequest -Uri $downloadUrl -OutFile $archivePath
+
+  Write-Host "==> Extracting skills"
+  Expand-Archive -LiteralPath $archivePath -DestinationPath $extractDir -Force
+
+  $sourceRoot = Get-ChildItem -Path $extractDir -Directory | Select-Object -First 1
+  if (-not $sourceRoot) {
+    throw "Could not find extracted Feynman archive."
+  }
+
+  $skillsSource = Join-Path $sourceRoot.FullName "skills"
+  $promptsSource = Join-Path $sourceRoot.FullName "prompts"
+  if (-not (Test-Path $skillsSource) -or -not (Test-Path $promptsSource)) {
+    throw "Could not find the bundled skills resources in the downloaded archive."
+  }
+
+  $installParent = Split-Path $installDir -Parent
+  if ($installParent) {
+    New-Item -ItemType Directory -Path $installParent -Force | Out-Null
+  }
+
+  if (Test-Path $installDir) {
+    Remove-Item -Recurse -Force $installDir
+  }
+
+  New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+  Copy-Item -Path (Join-Path $skillsSource "*") -Destination $installDir -Recurse -Force
+  New-Item -ItemType Directory -Path (Join-Path $installDir "prompts") -Force | Out-Null
+  Copy-Item -Path (Join-Path $promptsSource "*") -Destination (Join-Path $installDir "prompts") -Recurse -Force
+  Copy-Item -Path (Join-Path $sourceRoot.FullName "AGENTS.md") -Destination (Join-Path $installDir "AGENTS.md") -Force
+  Copy-Item -Path (Join-Path $sourceRoot.FullName "CONTRIBUTING.md") -Destination (Join-Path $installDir "CONTRIBUTING.md") -Force
+
+  Write-Host "==> Installed skills to $installDir"
+  if ($Scope -eq "Repo") {
+    Write-Host "Repo-local skills will be discovered automatically from .agents/skills."
+  } else {
+    Write-Host "User-level skills will be discovered from `$CODEX_HOME/skills."
+  }
+
+  Write-Host "Feynman skills $resolvedVersion installed successfully."
+} finally {
+  if (Test-Path $tmpDir) {
+    Remove-Item -Recurse -Force $tmpDir
+  }
+}

scripts/install/install-skills.sh

@@ -0,0 +1,210 @@
+#!/bin/sh
+
+set -eu
+
+VERSION="latest"
+SCOPE="${FEYNMAN_SKILLS_SCOPE:-user}"
+TARGET_DIR="${FEYNMAN_SKILLS_DIR:-}"
+
+step() {
+  printf '==> %s\n' "$1"
+}
+
+normalize_version() {
+  case "$1" in
+    "")
+      printf 'latest\n'
+      ;;
+    latest | stable)
+      printf 'latest\n'
+      ;;
+    edge)
+      echo "The edge channel has been removed. Use the default installer for the latest tagged release or pass an exact version." >&2
+      exit 1
+      ;;
+    v*)
+      printf '%s\n' "${1#v}"
+      ;;
+    *)
+      printf '%s\n' "$1"
+      ;;
+  esac
+}
+
+download_file() {
+  url="$1"
+  output="$2"
+
+  if command -v curl >/dev/null 2>&1; then
+    if [ -t 2 ]; then
+      curl -fL --progress-bar "$url" -o "$output"
+    else
+      curl -fsSL "$url" -o "$output"
+    fi
+    return
+  fi
+
+  if command -v wget >/dev/null 2>&1; then
+    if [ -t 2 ]; then
+      wget --show-progress -O "$output" "$url"
+    else
+      wget -q -O "$output" "$url"
+    fi
+    return
+  fi
+
+  echo "curl or wget is required to install Feynman skills." >&2
+  exit 1
+}
+
+download_text() {
+  url="$1"
+
+  if command -v curl >/dev/null 2>&1; then
+    curl -fsSL "$url"
+    return
+  fi
+
+  if command -v wget >/dev/null 2>&1; then
+    wget -q -O - "$url"
+    return
+  fi
+
+  echo "curl or wget is required to install Feynman skills." >&2
+  exit 1
+}
+
+resolve_version() {
+  normalized_version="$(normalize_version "$VERSION")"
+
+  if [ "$normalized_version" = "latest" ]; then
+    release_page="$(download_text "https://github.com/getcompanion-ai/feynman/releases/latest")"
+    resolved_version="$(printf '%s\n' "$release_page" | sed -n 's@.*releases/tag/v\([0-9][^"<>[:space:]]*\).*@\1@p' | head -n 1)"
+
+    if [ -z "$resolved_version" ]; then
+      echo "Failed to resolve the latest Feynman release version." >&2
+      exit 1
+    fi
+
+    printf '%s\nv%s\n' "$resolved_version" "$resolved_version"
+    return
+  fi
+
+  printf '%s\nv%s\n' "$normalized_version" "$normalized_version"
+}
+
+resolve_target_dir() {
+  if [ -n "$TARGET_DIR" ]; then
+    printf '%s\n' "$TARGET_DIR"
+    return
+  fi
+
+  case "$SCOPE" in
+    repo)
+      printf '%s/.agents/skills/feynman\n' "$PWD"
+      ;;
+    user)
+      codex_home="${CODEX_HOME:-$HOME/.codex}"
+      printf '%s/skills/feynman\n' "$codex_home"
+      ;;
+    *)
+      echo "Unknown scope: $SCOPE (expected --user or --repo)" >&2
+      exit 1
+      ;;
+  esac
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo)
+      SCOPE="repo"
+      ;;
+    --user)
+      SCOPE="user"
+      ;;
+    --dir)
+      if [ $# -lt 2 ]; then
+        echo "Usage: install-skills.sh [stable|latest|<version>] [--user|--repo] [--dir <path>]" >&2
+        exit 1
+      fi
+      TARGET_DIR="$2"
+      shift
+      ;;
+    edge|stable|latest|v*|[0-9]*)
+      VERSION="$1"
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      echo "Usage: install-skills.sh [stable|latest|<version>] [--user|--repo] [--dir <path>]" >&2
+      exit 1
+      ;;
+  esac
+  shift
+done
+
+archive_metadata="$(resolve_version)"
+resolved_version="$(printf '%s\n' "$archive_metadata" | sed -n '1p')"
+git_ref="$(printf '%s\n' "$archive_metadata" | sed -n '2p')"
+
+archive_url="${FEYNMAN_INSTALL_SKILLS_ARCHIVE_URL:-}"
+if [ -z "$archive_url" ]; then
+  case "$git_ref" in
+    main)
+      archive_url="https://github.com/getcompanion-ai/feynman/archive/refs/heads/main.tar.gz"
+      ;;
+    v*)
+      archive_url="https://github.com/getcompanion-ai/feynman/archive/refs/tags/${git_ref}.tar.gz"
+      ;;
+  esac
+fi
+
+if [ -z "$archive_url" ]; then
+  echo "Could not resolve a download URL for ref: $git_ref" >&2
+  exit 1
+fi
+
+install_dir="$(resolve_target_dir)"
+
+step "Installing Feynman skills ${resolved_version} (${SCOPE})"
+
+tmp_dir="$(mktemp -d)"
+cleanup() {
+  rm -rf "$tmp_dir"
+}
+trap cleanup EXIT INT TERM
+
+archive_path="$tmp_dir/feynman-skills.tar.gz"
+step "Downloading skills archive"
+download_file "$archive_url" "$archive_path"
+
+extract_dir="$tmp_dir/extract"
+mkdir -p "$extract_dir"
+step "Extracting skills"
+tar -xzf "$archive_path" -C "$extract_dir"
+
+source_root="$(find "$extract_dir" -mindepth 1 -maxdepth 1 -type d | head -n 1)"
+if [ -z "$source_root" ] || [ ! -d "$source_root/skills" ] || [ ! -d "$source_root/prompts" ]; then
+  echo "Could not find the bundled skills resources in the downloaded archive." >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$install_dir")"
+rm -rf "$install_dir"
+mkdir -p "$install_dir"
+cp -R "$source_root/skills/." "$install_dir/"
+mkdir -p "$install_dir/prompts"
+cp -R "$source_root/prompts/." "$install_dir/prompts/"
+cp "$source_root/AGENTS.md" "$install_dir/AGENTS.md"
+cp "$source_root/CONTRIBUTING.md" "$install_dir/CONTRIBUTING.md"
+
+step "Installed skills to $install_dir"
+case "$SCOPE" in
+  repo)
+    step "Repo-local skills will be discovered automatically from .agents/skills"
+    ;;
+  user)
+    step "User-level skills will be discovered from \$CODEX_HOME/skills"
+    ;;
+esac
+
+printf 'Feynman skills %s installed successfully.\n' "$resolved_version"

scripts/install/install.ps1

@@ -4,36 +4,88 @@ param(
 
 $ErrorActionPreference = "Stop"
 
-function Resolve-Version {
+function Normalize-Version {
   param([string]$RequestedVersion)
 
-  if ($RequestedVersion -and $RequestedVersion -ne "latest") {
-    return $RequestedVersion.TrimStart("v")
+  if (-not $RequestedVersion) {
+    return "latest"
   }
 
-  $release = Invoke-RestMethod -Uri "https://api.github.com/repos/getcompanion-ai/feynman/releases/latest"
-  if (-not $release.tag_name) {
+  switch ($RequestedVersion.ToLowerInvariant()) {
+    "latest" { return "latest" }
+    "stable" { return "latest" }
+    "edge" { throw "The edge channel has been removed. Use the default installer for the latest tagged release or pass an exact version." }
+    default { return $RequestedVersion.TrimStart("v") }
+  }
+}
+
+function Resolve-LatestReleaseVersion {
+  $page = Invoke-WebRequest -Uri "https://github.com/getcompanion-ai/feynman/releases/latest"
+  $match = [regex]::Match($page.Content, 'releases/tag/v([0-9][^"''<>\s]*)')
+  if (-not $match.Success) {
     throw "Failed to resolve the latest Feynman release version."
   }
 
-  return $release.tag_name.TrimStart("v")
+  return $match.Groups[1].Value
 }
 
-function Get-ArchSuffix {
-  $arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
-  switch ($arch.ToString()) {
-    "X64" { return "x64" }
-    "Arm64" { return "arm64" }
-    default { throw "Unsupported architecture: $arch" }
+function Resolve-ReleaseMetadata {
+  param(
+    [string]$RequestedVersion,
+    [string]$AssetTarget,
+    [string]$BundleExtension
+  )
+
+  $normalizedVersion = Normalize-Version -RequestedVersion $RequestedVersion
+
+  if ($normalizedVersion -eq "latest") {
+    $resolvedVersion = Resolve-LatestReleaseVersion
+  } else {
+    $resolvedVersion = $normalizedVersion
+  }
+
+  $bundleName = "feynman-$resolvedVersion-$AssetTarget"
+  $archiveName = "$bundleName.$BundleExtension"
+  $baseUrl = if ($env:FEYNMAN_INSTALL_BASE_URL) { $env:FEYNMAN_INSTALL_BASE_URL } else { "https://github.com/getcompanion-ai/feynman/releases/download/v$resolvedVersion" }
+
+  return [PSCustomObject]@{
+    ResolvedVersion = $resolvedVersion
+    BundleName = $bundleName
+    ArchiveName = $archiveName
+    DownloadUrl = "$baseUrl/$archiveName"
   }
 }
 
-$resolvedVersion = Resolve-Version -RequestedVersion $Version
+function Get-ArchSuffix {
+  # Prefer PROCESSOR_ARCHITECTURE which is always available on Windows.
+  # RuntimeInformation::OSArchitecture requires .NET 4.7.1+ and may not
+  # be loaded in every Windows PowerShell 5.1 session.
+  $envArch = $env:PROCESSOR_ARCHITECTURE
+  if ($envArch) {
+    switch ($envArch) {
+      "AMD64" { return "x64" }
+      "ARM64" { return "arm64" }
+    }
+  }
+
+  try {
+    $arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture
+    switch ($arch.ToString()) {
+      "X64" { return "x64" }
+      "Arm64" { return "arm64" }
+    }
+  } catch {}
+
+  throw "Unsupported architecture: $envArch"
+}
+
 $archSuffix = Get-ArchSuffix
-$bundleName = "feynman-$resolvedVersion-win32-$archSuffix"
-$archiveName = "$bundleName.zip"
-$baseUrl = if ($env:FEYNMAN_INSTALL_BASE_URL) { $env:FEYNMAN_INSTALL_BASE_URL } else { "https://github.com/getcompanion-ai/feynman/releases/download/v$resolvedVersion" }
-$downloadUrl = "$baseUrl/$archiveName"
+$assetTarget = "win32-$archSuffix"
+$release = Resolve-ReleaseMetadata -RequestedVersion $Version -AssetTarget $assetTarget -BundleExtension "zip"
+$resolvedVersion = $release.ResolvedVersion
+$bundleName = $release.BundleName
+$archiveName = $release.ArchiveName
+$downloadUrl = $release.DownloadUrl
 
 $installRoot = Join-Path $env:LOCALAPPDATA "Programs\feynman"
 $installBinDir = Join-Path $installRoot "bin"
@@ -44,25 +96,53 @@ New-Item -ItemType Directory -Path $tmpDir | Out-Null
 
 try {
   $archivePath = Join-Path $tmpDir $archiveName
-  Invoke-WebRequest -Uri $downloadUrl -OutFile $archivePath
+  Write-Host "==> Downloading $archiveName"
+  try {
+    Invoke-WebRequest -Uri $downloadUrl -OutFile $archivePath
+  } catch {
+    throw @"
+Failed to download $archiveName from:
+  $downloadUrl
+
+The win32-$archSuffix bundle is missing from the GitHub release.
+This usually means the release exists, but not all platform bundles were uploaded.
+
+Workarounds:
+  - try again after the release finishes publishing
+  - pass the latest published version explicitly, e.g.:
+    & ([scriptblock]::Create((irm https://feynman.is/install.ps1))) -Version 0.2.16
+"@
+  }
 
   New-Item -ItemType Directory -Path $installRoot -Force | Out-Null
   if (Test-Path $bundleDir) {
     Remove-Item -Recurse -Force $bundleDir
   }
 
+  Write-Host "==> Extracting $archiveName"
   Expand-Archive -LiteralPath $archivePath -DestinationPath $installRoot -Force
 
   New-Item -ItemType Directory -Path $installBinDir -Force | Out-Null
 
   $shimPath = Join-Path $installBinDir "feynman.cmd"
+  $shimPs1Path = Join-Path $installBinDir "feynman.ps1"
+  Write-Host "==> Linking feynman into $installBinDir"
   @"
 @echo off
-"$bundleDir\feynman.cmd" %*
+CALL "$bundleDir\feynman.cmd" %*
 "@ | Set-Content -Path $shimPath -Encoding ASCII
 
+  @"
+`$BundleDir = "$bundleDir"
+& "`$BundleDir\node\node.exe" "`$BundleDir\app\bin\feynman.js" @args
+"@ | Set-Content -Path $shimPs1Path -Encoding UTF8
+
   $currentUserPath = [Environment]::GetEnvironmentVariable("Path", "User")
-  if (-not $currentUserPath.Split(';').Contains($installBinDir)) {
+  $alreadyOnPath = $false
+  if ($currentUserPath) {
+    $alreadyOnPath = $currentUserPath.Split(';') -contains $installBinDir
+  }
+  if (-not $alreadyOnPath) {
     $updatedPath = if ([string]::IsNullOrWhiteSpace($currentUserPath)) {
       $installBinDir
     } else {
@@ -74,6 +154,14 @@ try {
     Write-Host "$installBinDir is already on PATH."
   }
 
+  $resolvedCommand = Get-Command feynman -ErrorAction SilentlyContinue
+  if ($resolvedCommand -and $resolvedCommand.Source -ne $shimPath) {
+    Write-Warning "Current shell resolves feynman to $($resolvedCommand.Source)"
+    Write-Host "Run in a new shell, or run: `$env:Path = '$installBinDir;' + `$env:Path"
+    Write-Host "Then run: feynman"
+    Write-Host "If that path is an old package-manager install, remove it or put $installBinDir first on PATH."
+  }
+
   Write-Host "Feynman $resolvedVersion installed successfully."
 } finally {
   if (Test-Path $tmpDir) {

scripts/install/install.sh

@@ -13,11 +13,57 @@ step() {
   printf '==> %s\n' "$1"
 }
 
+run_with_spinner() {
+  label="$1"
+  shift
+
+  if [ ! -t 2 ]; then
+    step "$label"
+    "$@"
+    return
+  fi
+
+  "$@" &
+  pid=$!
+  frame=0
+
+  set +e
+  while kill -0 "$pid" 2>/dev/null; do
+    case "$frame" in
+      0) spinner='|' ;;
+      1) spinner='/' ;;
+      2) spinner='-' ;;
+      *) spinner='\\' ;;
+    esac
+    printf '\r==> %s %s' "$label" "$spinner" >&2
+    frame=$(( (frame + 1) % 4 ))
+    sleep 0.1
+  done
+  wait "$pid"
+  status=$?
+  set -e
+
+  printf '\r\033[2K' >&2
+  if [ "$status" -ne 0 ]; then
+    printf '==> %s failed\n' "$label" >&2
+    return "$status"
+  fi
+
+  step "$label"
+}
+
 normalize_version() {
   case "$1" in
-    "" | latest)
+    "")
       printf 'latest\n'
       ;;
+    latest | stable)
+      printf 'latest\n'
+      ;;
+    edge)
+      echo "The edge channel has been removed. Use the default installer for the latest tagged release or pass an exact version." >&2
+      exit 1
+      ;;
     v*)
       printf '%s\n' "${1#v}"
       ;;
@@ -32,12 +78,20 @@ download_file() {
   output="$2"
 
   if command -v curl >/dev/null 2>&1; then
-    curl -fsSL "$url" -o "$output"
+    if [ -t 2 ]; then
+      curl -fL --progress-bar "$url" -o "$output"
+    else
+      curl -fsSL "$url" -o "$output"
+    fi
     return
   fi
 
   if command -v wget >/dev/null 2>&1; then
-    wget -q -O "$output" "$url"
+    if [ -t 2 ]; then
+      wget --show-progress -O "$output" "$url"
+    else
+      wget -q -O "$output" "$url"
+    fi
     return
   fi
 
@@ -110,23 +164,43 @@ require_command() {
   fi
 }
 
-resolve_version() {
-  normalized_version="$(normalize_version "$VERSION")"
+warn_command_conflict() {
+  expected_path="$INSTALL_BIN_DIR/feynman"
+  resolved_path="$(command -v feynman 2>/dev/null || true)"
 
-  if [ "$normalized_version" != "latest" ]; then
-    printf '%s\n' "$normalized_version"
+  if [ -z "$resolved_path" ]; then
     return
   fi
 
-  release_json="$(download_text "https://api.github.com/repos/getcompanion-ai/feynman/releases/latest")"
-  resolved="$(printf '%s\n' "$release_json" | sed -n 's/.*"tag_name":[[:space:]]*"v\([^"]*\)".*/\1/p' | head -n 1)"
+  if [ "$resolved_path" != "$expected_path" ]; then
+    step "Warning: current shell resolves feynman to $resolved_path"
+    step "Run now: export PATH=\"$INSTALL_BIN_DIR:\$PATH\" && hash -r && feynman"
+    step "Or launch directly: $expected_path"
 
-  if [ -z "$resolved" ]; then
-    echo "Failed to resolve the latest Feynman release version." >&2
-    exit 1
+    step "If that path is an old package-manager install, remove it or put $INSTALL_BIN_DIR first on PATH."
+  fi
+}
+
+resolve_release_metadata() {
+  normalized_version="$(normalize_version "$VERSION")"
+
+  if [ "$normalized_version" = "latest" ]; then
+    release_page="$(download_text "https://github.com/getcompanion-ai/feynman/releases/latest")"
+    resolved_version="$(printf '%s\n' "$release_page" | sed -n 's@.*releases/tag/v\([0-9][^"<>[:space:]]*\).*@\1@p' | head -n 1)"
+
+    if [ -z "$resolved_version" ]; then
+      echo "Failed to resolve the latest Feynman release version." >&2
+      exit 1
+    fi
+  else
+    resolved_version="$normalized_version"
   fi
 
-  printf '%s\n' "$resolved"
+  bundle_name="feynman-${resolved_version}-${asset_target}"
+  archive_name="${bundle_name}.${archive_extension}"
+  download_url="${FEYNMAN_INSTALL_BASE_URL:-https://github.com/getcompanion-ai/feynman/releases/download/v${resolved_version}}/${archive_name}"
+
+  printf '%s\n%s\n%s\n%s\n' "$resolved_version" "$bundle_name" "$archive_name" "$download_url"
 }
 
 case "$(uname -s)" in
@@ -158,12 +232,13 @@ esac
 require_command mktemp
 require_command tar
 
-resolved_version="$(resolve_version)"
 asset_target="$os-$arch"
-bundle_name="feynman-${resolved_version}-${asset_target}"
-archive_name="${bundle_name}.tar.gz"
-base_url="${FEYNMAN_INSTALL_BASE_URL:-https://github.com/getcompanion-ai/feynman/releases/download/v${resolved_version}}"
-download_url="${base_url}/${archive_name}"
+archive_extension="tar.gz"
+release_metadata="$(resolve_release_metadata)"
+resolved_version="$(printf '%s\n' "$release_metadata" | sed -n '1p')"
+bundle_name="$(printf '%s\n' "$release_metadata" | sed -n '2p')"
+archive_name="$(printf '%s\n' "$release_metadata" | sed -n '3p')"
+download_url="$(printf '%s\n' "$release_metadata" | sed -n '4p')"
 
 step "Installing Feynman ${resolved_version} for ${asset_target}"
 
@@ -174,13 +249,29 @@ cleanup() {
 trap cleanup EXIT INT TERM
 
 archive_path="$tmp_dir/$archive_name"
-download_file "$download_url" "$archive_path"
+step "Downloading ${archive_name}"
+if ! download_file "$download_url" "$archive_path"; then
+  cat >&2 <<EOF
+Failed to download ${archive_name} from:
+  ${download_url}
+
+The ${asset_target} bundle is missing from the GitHub release.
+This usually means the release exists, but not all platform bundles were uploaded.
+
+Workarounds:
+  - try again after the release finishes publishing
+  - pass the latest published version explicitly, e.g.:
+    curl -fsSL https://feynman.is/install | bash -s -- 0.2.16
+EOF
+  exit 1
+fi
 
 mkdir -p "$INSTALL_APP_DIR"
 rm -rf "$INSTALL_APP_DIR/$bundle_name"
-tar -xzf "$archive_path" -C "$INSTALL_APP_DIR"
+run_with_spinner "Extracting ${archive_name}" tar -xzf "$archive_path" -C "$INSTALL_APP_DIR"
 
 mkdir -p "$INSTALL_BIN_DIR"
+step "Linking feynman into $INSTALL_BIN_DIR"
 cat >"$INSTALL_BIN_DIR/feynman" <<EOF
 #!/bin/sh
 set -eu
@@ -193,20 +284,22 @@ add_to_path
 case "$path_action" in
   added)
     step "PATH updated for future shells in $path_profile"
-    step "Run now: export PATH=\"$INSTALL_BIN_DIR:\$PATH\" && feynman"
+    step "Run now: export PATH=\"$INSTALL_BIN_DIR:\$PATH\" && hash -r && feynman"
     ;;
   configured)
     step "PATH is already configured for future shells in $path_profile"
-    step "Run now: export PATH=\"$INSTALL_BIN_DIR:\$PATH\" && feynman"
+    step "Run now: export PATH=\"$INSTALL_BIN_DIR:\$PATH\" && hash -r && feynman"
     ;;
   skipped)
     step "PATH update skipped"
-    step "Run now: export PATH=\"$INSTALL_BIN_DIR:\$PATH\" && feynman"
+    step "Run now: export PATH=\"$INSTALL_BIN_DIR:\$PATH\" && hash -r && feynman"
     ;;
   *)
     step "$INSTALL_BIN_DIR is already on PATH"
-    step "Run: feynman"
+    step "Run: hash -r && feynman"
     ;;
 esac
 
+warn_command_conflict
+
 printf 'Feynman %s installed successfully.\n' "$resolved_version"

scripts/lib/pi-extension-loader-patch.d.mts

@@ -0,0 +1 @@
+export function patchPiExtensionLoaderSource(source: string): string;

scripts/lib/pi-extension-loader-patch.mjs

@@ -0,0 +1,32 @@
+const PATH_TO_FILE_URL_IMPORT = 'import { fileURLToPath, pathToFileURL } from "node:url";';
+const FILE_URL_TO_PATH_IMPORT = 'import { fileURLToPath } from "node:url";';
+
+const IMPORT_CALL = 'const module = await jiti.import(extensionPath, { default: true });';
+const PATCHED_IMPORT_CALL = [
+	'    const extensionSpecifier = process.platform === "win32" && path.isAbsolute(extensionPath)',
+	'        ? pathToFileURL(extensionPath).href',
+	'        : extensionPath;',
+	'    const module = await jiti.import(extensionSpecifier, { default: true });',
+].join("\n");
+
+export function patchPiExtensionLoaderSource(source) {
+	let patched = source;
+
+	if (patched.includes(PATH_TO_FILE_URL_IMPORT) || patched.includes(PATCHED_IMPORT_CALL)) {
+		return patched;
+	}
+
+	if (patched.includes(FILE_URL_TO_PATH_IMPORT)) {
+		patched = patched.replace(FILE_URL_TO_PATH_IMPORT, PATH_TO_FILE_URL_IMPORT);
+	}
+
+	if (!patched.includes(PATH_TO_FILE_URL_IMPORT)) {
+		return source;
+	}
+
+	if (!patched.includes(IMPORT_CALL)) {
+		return source;
+	}
+
+	return patched.replace(IMPORT_CALL, PATCHED_IMPORT_CALL);
+}

scripts/lib/pi-google-legacy-schema-patch.d.mts

@@ -0,0 +1 @@
+export function patchPiGoogleLegacySchemaSource(source: string): string;

scripts/lib/pi-google-legacy-schema-patch.mjs

@@ -0,0 +1,44 @@
+const HELPER = [
+	"function normalizeLegacyToolSchema(schema) {",
+	"    if (Array.isArray(schema)) return schema.map((item) => normalizeLegacyToolSchema(item));",
+	'    if (!schema || typeof schema !== "object") return schema;',
+	"    const normalized = {};",
+	"    for (const [key, value] of Object.entries(schema)) {",
+	'        if (key === "const") {',
+	"            normalized.enum = [value];",
+	"            continue;",
+	"        }",
+	"        normalized[key] = normalizeLegacyToolSchema(value);",
+	"    }",
+	"    return normalized;",
+	"}",
+].join("\n");
+
+const ORIGINAL =
+	'                ...(useParameters ? { parameters: tool.parameters } : { parametersJsonSchema: tool.parameters }),';
+const PATCHED = [
+	"                ...(useParameters",
+	"                    ? { parameters: normalizeLegacyToolSchema(tool.parameters) }",
+	"                    : { parametersJsonSchema: tool.parameters }),",
+].join("\n");
+
+export function patchPiGoogleLegacySchemaSource(source) {
+	let patched = source;
+
+	if (patched.includes("function normalizeLegacyToolSchema(schema) {")) {
+		return patched;
+	}
+
+	if (!patched.includes(ORIGINAL)) {
+		return source;
+	}
+
+	patched = patched.replace(ORIGINAL, PATCHED);
+	const marker = "export function convertTools(tools, useParameters = false) {";
+	const markerIndex = patched.indexOf(marker);
+	if (markerIndex === -1) {
+		return source;
+	}
+
+	return `${patched.slice(0, markerIndex)}${HELPER}\n\n${patched.slice(markerIndex)}`;
+}

scripts/lib/pi-subagents-patch.d.mts

@@ -0,0 +1,2 @@
+export const PI_SUBAGENTS_PATCH_TARGETS: string[];
+export function patchPiSubagentsSource(relativePath: string, source: string): string;

scripts/lib/pi-subagents-patch.mjs

@@ -0,0 +1,124 @@
+export const PI_SUBAGENTS_PATCH_TARGETS = [
+	"index.ts",
+	"agents.ts",
+	"artifacts.ts",
+	"run-history.ts",
+	"skills.ts",
+	"chain-clarify.ts",
+];
+
+const RESOLVE_PI_AGENT_DIR_HELPER = [
+	"function resolvePiAgentDir(): string {",
+	'	const configured = process.env.PI_CODING_AGENT_DIR?.trim();',
+	'	if (!configured) return path.join(os.homedir(), ".pi", "agent");',
+	'	return configured.startsWith("~/") ? path.join(os.homedir(), configured.slice(2)) : configured;',
+	"}",
+].join("\n");
+
+function injectResolvePiAgentDirHelper(source) {
+	if (source.includes("function resolvePiAgentDir(): string {")) {
+		return source;
+	}
+
+	const lines = source.split("\n");
+	let insertAt = 0;
+	let importSeen = false;
+	let importOpen = false;
+
+	for (let index = 0; index < lines.length; index += 1) {
+		const trimmed = lines[index].trim();
+		if (!importSeen) {
+			if (trimmed === "" || trimmed.startsWith("/**") || trimmed.startsWith("*") || trimmed.startsWith("*/")) {
+				insertAt = index + 1;
+				continue;
+			}
+			if (trimmed.startsWith("import ")) {
+				importSeen = true;
+				importOpen = !trimmed.endsWith(";");
+				insertAt = index + 1;
+				continue;
+			}
+			break;
+		}
+
+		if (trimmed.startsWith("import ")) {
+			importOpen = !trimmed.endsWith(";");
+			insertAt = index + 1;
+			continue;
+		}
+		if (importOpen) {
+			if (trimmed.endsWith(";")) importOpen = false;
+			insertAt = index + 1;
+			continue;
+		}
+		if (trimmed === "") {
+			insertAt = index + 1;
+			continue;
+		}
+		insertAt = index;
+		break;
+	}
+
+	return [...lines.slice(0, insertAt), "", RESOLVE_PI_AGENT_DIR_HELPER, "", ...lines.slice(insertAt)].join("\n");
+}
+
+function replaceAll(source, from, to) {
+	return source.split(from).join(to);
+}
+
+export function patchPiSubagentsSource(relativePath, source) {
+	let patched = source;
+
+	switch (relativePath) {
+		case "index.ts":
+			patched = replaceAll(
+				patched,
+				'const configPath = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent", "config.json");',
+				'const configPath = path.join(resolvePiAgentDir(), "extensions", "subagent", "config.json");',
+			);
+			break;
+		case "agents.ts":
+			patched = replaceAll(
+				patched,
+				'const userDir = path.join(os.homedir(), ".pi", "agent", "agents");',
+				'const userDir = path.join(resolvePiAgentDir(), "agents");',
+			);
+			break;
+		case "artifacts.ts":
+			patched = replaceAll(
+				patched,
+				'const sessionsBase = path.join(os.homedir(), ".pi", "agent", "sessions");',
+				'const sessionsBase = path.join(resolvePiAgentDir(), "sessions");',
+			);
+			break;
+		case "run-history.ts":
+			patched = replaceAll(
+				patched,
+				'const HISTORY_PATH = path.join(os.homedir(), ".pi", "agent", "run-history.jsonl");',
+				'const HISTORY_PATH = path.join(resolvePiAgentDir(), "run-history.jsonl");',
+			);
+			break;
+		case "skills.ts":
+			patched = replaceAll(
+				patched,
+				'const AGENT_DIR = path.join(os.homedir(), ".pi", "agent");',
+				"const AGENT_DIR = resolvePiAgentDir();",
+			);
+			break;
+		case "chain-clarify.ts":
+			patched = replaceAll(
+				patched,
+				'const dir = path.join(os.homedir(), ".pi", "agent", "agents");',
+				'const dir = path.join(resolvePiAgentDir(), "agents");',
+			);
+			break;
+		default:
+			return source;
+	}
+
+	if (patched === source) {
+		return source;
+	}
+
+	return injectResolvePiAgentDirHelper(patched);
+}

scripts/lib/pi-web-access-patch.d.mts

@@ -0,0 +1,2 @@
+export const PI_WEB_ACCESS_PATCH_TARGETS: string[];
+export function patchPiWebAccessSource(relativePath: string, source: string): string;

scripts/lib/pi-web-access-patch.mjs

@@ -0,0 +1,32 @@
+export const PI_WEB_ACCESS_PATCH_TARGETS = [
+	"index.ts",
+	"exa.ts",
+	"gemini-api.ts",
+	"gemini-search.ts",
+	"gemini-web.ts",
+	"github-extract.ts",
+	"perplexity.ts",
+	"video-extract.ts",
+	"youtube-extract.ts",
+];
+
+const LEGACY_CONFIG_EXPR = 'join(homedir(), ".pi", "web-search.json")';
+const PATCHED_CONFIG_EXPR =
+	'process.env.FEYNMAN_WEB_SEARCH_CONFIG ?? process.env.PI_WEB_SEARCH_CONFIG ?? join(homedir(), ".pi", "web-search.json")';
+
+export function patchPiWebAccessSource(relativePath, source) {
+	let patched = source;
+
+	if (patched.includes(PATCHED_CONFIG_EXPR)) {
+		return patched;
+	}
+
+	patched = patched.split(LEGACY_CONFIG_EXPR).join(PATCHED_CONFIG_EXPR);
+
+	if (relativePath === "index.ts" && patched !== source) {
+		patched = patched.replace('import { join } from "node:path";', 'import { dirname, join } from "node:path";');
+		patched = patched.replace('const dir = join(homedir(), ".pi");', "const dir = dirname(WEB_SEARCH_CONFIG_PATH);");
+	}
+
+	return patched;
+}

scripts/patch-embedded-pi.mjs

@@ -1,28 +1,50 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { FEYNMAN_LOGO_HTML } from "../logo.mjs";
+import { patchPiExtensionLoaderSource } from "./lib/pi-extension-loader-patch.mjs";
+import { patchPiGoogleLegacySchemaSource } from "./lib/pi-google-legacy-schema-patch.mjs";
+import { PI_WEB_ACCESS_PATCH_TARGETS, patchPiWebAccessSource } from "./lib/pi-web-access-patch.mjs";
+import { PI_SUBAGENTS_PATCH_TARGETS, patchPiSubagentsSource } from "./lib/pi-subagents-patch.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const appRoot = resolve(here, "..");
+const feynmanHome = resolve(process.env.FEYNMAN_HOME ?? homedir(), ".feynman");
+const feynmanNpmPrefix = resolve(feynmanHome, "npm-global");
+process.env.FEYNMAN_NPM_PREFIX = feynmanNpmPrefix;
+process.env.NPM_CONFIG_PREFIX = feynmanNpmPrefix;
+process.env.npm_config_prefix = feynmanNpmPrefix;
+const appRequire = createRequire(resolve(appRoot, "package.json"));
 const isGlobalInstall = process.env.npm_config_global === "true" || process.env.npm_config_location === "global";
 
-function findNodeModules() {
-	let dir = appRoot;
-	while (dir !== dirname(dir)) {
-		const nm = resolve(dir, "node_modules");
-		if (existsSync(nm)) return nm;
-		dir = dirname(dir);
-	}
-	return resolve(appRoot, "node_modules");
-}
-
-const nodeModules = findNodeModules();
-
 function findPackageRoot(packageName) {
-	const candidate = resolve(nodeModules, packageName);
-	if (existsSync(resolve(candidate, "package.json"))) return candidate;
+	const segments = packageName.split("/");
+	let current = appRoot;
+	while (current !== dirname(current)) {
+		for (const candidate of [resolve(current, "node_modules", ...segments), resolve(current, ...segments)]) {
+			if (existsSync(resolve(candidate, "package.json"))) {
+				return candidate;
+			}
+		}
+		current = dirname(current);
+	}
+
+	for (const spec of [`${packageName}/dist/index.js`, `${packageName}/dist/cli.js`, packageName]) {
+		try {
+			let current = dirname(appRequire.resolve(spec));
+			while (current !== dirname(current)) {
+				if (existsSync(resolve(current, "package.json"))) {
+					return current;
+				}
+				current = dirname(current);
+			}
+		} catch {
+			continue;
+		}
+	}
 	return null;
 }
 
@@ -31,17 +53,28 @@ const piTuiRoot = findPackageRoot("@mariozechner/pi-tui");
 const piAiRoot = findPackageRoot("@mariozechner/pi-ai");
 
 if (!piPackageRoot) {
-	console.warn("[feynman] pi-coding-agent not found, skipping patches");
-	process.exit(0);
+	console.warn("[feynman] pi-coding-agent not found, skipping Pi patches");
 }
 
-const packageJsonPath = resolve(piPackageRoot, "package.json");
-const cliPath = resolve(piPackageRoot, "dist", "cli.js");
-const bunCliPath = resolve(piPackageRoot, "dist", "bun", "cli.js");
-const interactiveModePath = resolve(piPackageRoot, "dist", "modes", "interactive", "interactive-mode.js");
-const interactiveThemePath = resolve(piPackageRoot, "dist", "modes", "interactive", "theme", "theme.js");
+const packageJsonPath = piPackageRoot ? resolve(piPackageRoot, "package.json") : null;
+const cliPath = piPackageRoot ? resolve(piPackageRoot, "dist", "cli.js") : null;
+const bunCliPath = piPackageRoot ? resolve(piPackageRoot, "dist", "bun", "cli.js") : null;
+const interactiveModePath = piPackageRoot ? resolve(piPackageRoot, "dist", "modes", "interactive", "interactive-mode.js") : null;
+const interactiveThemePath = piPackageRoot ? resolve(piPackageRoot, "dist", "modes", "interactive", "theme", "theme.js") : null;
+const extensionLoaderPath = piPackageRoot ? resolve(piPackageRoot, "dist", "core", "extensions", "loader.js") : null;
+const terminalPath = piTuiRoot ? resolve(piTuiRoot, "dist", "terminal.js") : null;
 const editorPath = piTuiRoot ? resolve(piTuiRoot, "dist", "components", "editor.js") : null;
 const workspaceRoot = resolve(appRoot, ".feynman", "npm", "node_modules");
+const workspaceExtensionLoaderPath = resolve(
+	workspaceRoot,
+	"@mariozechner",
+	"pi-coding-agent",
+	"dist",
+	"core",
+	"extensions",
+	"loader.js",
+);
+const piSubagentsRoot = resolve(workspaceRoot, "pi-subagents");
 const webAccessPath = resolve(workspaceRoot, "pi-web-access", "index.ts");
 const sessionSearchIndexerPath = resolve(
 	workspaceRoot,
@@ -56,6 +89,71 @@ const workspaceDir = resolve(appRoot, ".feynman", "npm");
 const workspacePackageJsonPath = resolve(workspaceDir, "package.json");
 const workspaceArchivePath = resolve(appRoot, ".feynman", "runtime-workspace.tgz");
 
+function createInstallCommand(packageManager, packageSpecs) {
+	switch (packageManager) {
+		case "npm":
+			return [
+				"install",
+				"--global=false",
+				"--location=project",
+				"--prefer-offline",
+				"--no-audit",
+				"--no-fund",
+				"--loglevel",
+				"error",
+				...packageSpecs,
+			];
+		case "pnpm":
+			return ["add", "--prefer-offline", "--reporter", "silent", ...packageSpecs];
+		case "bun":
+			return ["add", "--silent", ...packageSpecs];
+		default:
+			throw new Error(`Unsupported package manager: ${packageManager}`);
+	}
+}
+
+let cachedPackageManager = undefined;
+
+function resolvePackageManager() {
+	if (cachedPackageManager !== undefined) return cachedPackageManager;
+
+	const requested = process.env.FEYNMAN_PACKAGE_MANAGER?.trim();
+	const candidates = requested ? [requested] : ["npm", "pnpm", "bun"];
+	for (const candidate of candidates) {
+		if (resolveExecutable(candidate)) {
+			cachedPackageManager = candidate;
+			return candidate;
+		}
+	}
+
+	cachedPackageManager = null;
+	return null;
+}
+
+function installWorkspacePackages(packageSpecs) {
+	const packageManager = resolvePackageManager();
+	if (!packageManager) {
+		process.stderr.write(
+			"[feynman] no supported package manager found; install npm, pnpm, or bun, or set FEYNMAN_PACKAGE_MANAGER.\n",
+		);
+		return false;
+	}
+
+	const result = spawnSync(packageManager, createInstallCommand(packageManager, packageSpecs), {
+		cwd: workspaceDir,
+		stdio: ["ignore", "ignore", "pipe"],
+		timeout: 300000,
+	});
+
+	if (result.status !== 0) {
+		if (result.stderr?.length) process.stderr.write(result.stderr);
+		process.stderr.write(`[feynman] ${packageManager} failed while setting up bundled packages.\n`);
+		return false;
+	}
+
+	return true;
+}
+
 function parsePackageName(spec) {
 	const match = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@.+)?$/);
 	return match?.[1] ?? spec;
@@ -72,26 +170,22 @@ function restorePackagedWorkspace(packageSpecs) {
 		timeout: 300000,
 	});
 
+	// On Windows, tar may exit non-zero due to symlink creation failures in
+	// .bin/ directories. These are non-fatal — check whether the actual
+	// package directories were extracted successfully.
+	const packagesPresent = packageSpecs.every((spec) => existsSync(resolve(workspaceRoot, parsePackageName(spec))));
+	if (packagesPresent) return true;
+
 	if (result.status !== 0) {
 		if (result.stderr?.length) process.stderr.write(result.stderr);
 		return false;
 	}
 
-	return packageSpecs.every((spec) => existsSync(resolve(workspaceRoot, parsePackageName(spec))));
+	return false;
 }
 
 function refreshPackagedWorkspace(packageSpecs) {
-	const result = spawnSync("npm", ["install", "--prefer-offline", "--no-audit", "--no-fund", "--loglevel", "error", "--prefix", workspaceDir, ...packageSpecs], {
-		stdio: ["ignore", "ignore", "pipe"],
-		timeout: 300000,
-	});
-
-	if (result.status !== 0) {
-		if (result.stderr?.length) process.stderr.write(result.stderr);
-		return false;
-	}
-
-	return true;
+	return installWorkspacePackages(packageSpecs);
 }
 
 function resolveExecutable(name, fallbackPaths = []) {
@@ -99,12 +193,18 @@ function resolveExecutable(name, fallbackPaths = []) {
 		if (existsSync(candidate)) return candidate;
 	}
 
-	const result = spawnSync("sh", ["-lc", `command -v ${name}`], {
-		encoding: "utf8",
-		stdio: ["ignore", "pipe", "ignore"],
-	});
+	const isWindows = process.platform === "win32";
+	const result = isWindows
+		? spawnSync("cmd", ["/c", `where ${name}`], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+			})
+		: spawnSync("sh", ["-lc", `command -v ${name}`], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+			});
 	if (result.status === 0) {
-		const resolved = result.stdout.trim();
+		const resolved = result.stdout.trim().split(/\r?\n/)[0];
 		if (resolved) return resolved;
 	}
 	return null;
@@ -139,17 +239,13 @@ function ensurePackageWorkspace() {
 		process.stderr.write(`\r${frames[frame++ % frames.length]} setting up feynman... ${elapsed}s`);
 	}, 80);
 
-	const result = spawnSync("npm", ["install", "--prefer-offline", "--no-audit", "--no-fund", "--loglevel", "error", "--prefix", workspaceDir, ...packageSpecs], {
-		stdio: ["ignore", "ignore", "pipe"],
-		timeout: 300000,
-	});
+	const result = installWorkspacePackages(packageSpecs);
 
 	clearInterval(spinner);
 	const elapsed = Math.round((Date.now() - start) / 1000);
 
-	if (result.status !== 0) {
+	if (!result) {
 		process.stderr.write(`\r✗ setup failed (${elapsed}s)\n`);
-		if (result.stderr?.length) process.stderr.write(result.stderr);
 	} else {
 		process.stderr.write(`\r✓ feynman ready (${elapsed}s)\n`);
 	}
@@ -178,7 +274,20 @@ function ensurePandoc() {
 
 ensurePandoc();
 
-if (existsSync(packageJsonPath)) {
+if (existsSync(piSubagentsRoot)) {
+	for (const relativePath of PI_SUBAGENTS_PATCH_TARGETS) {
+		const entryPath = resolve(piSubagentsRoot, relativePath);
+		if (!existsSync(entryPath)) continue;
+
+		const source = readFileSync(entryPath, "utf8");
+		const patched = patchPiSubagentsSource(relativePath, source);
+		if (patched !== source) {
+			writeFileSync(entryPath, patched, "utf8");
+		}
+	}
+}
+
+if (packageJsonPath && existsSync(packageJsonPath)) {
 	const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8"));
 	if (pkg.piConfig?.name !== "feynman" || pkg.piConfig?.configDir !== ".feynman") {
 		pkg.piConfig = {
@@ -190,18 +299,76 @@ if (existsSync(packageJsonPath)) {
 	}
 }
 
-for (const entryPath of [cliPath, bunCliPath]) {
+for (const entryPath of [cliPath, bunCliPath].filter(Boolean)) {
 	if (!existsSync(entryPath)) {
 		continue;
 	}
 
-	const cliSource = readFileSync(entryPath, "utf8");
+	let cliSource = readFileSync(entryPath, "utf8");
 	if (cliSource.includes('process.title = "pi";')) {
-		writeFileSync(entryPath, cliSource.replace('process.title = "pi";', 'process.title = "feynman";'), "utf8");
+		cliSource = cliSource.replace('process.title = "pi";', 'process.title = "feynman";');
 	}
+	const stdinErrorGuard = [
+		"const feynmanHandleStdinError = (error) => {",
+		'    if (error && typeof error === "object") {',
+		'        const code = "code" in error ? error.code : undefined;',
+		'        const syscall = "syscall" in error ? error.syscall : undefined;',
+		'        if ((code === "EIO" || code === "EBADF") && syscall === "read") {',
+		"            return;",
+		"        }",
+		"    }",
+		"};",
+		'process.stdin?.on?.("error", feynmanHandleStdinError);',
+	].join("\n");
+	if (!cliSource.includes('process.stdin?.on?.("error", feynmanHandleStdinError);')) {
+		cliSource = cliSource.replace(
+			'process.emitWarning = (() => { });',
+			`process.emitWarning = (() => { });\n${stdinErrorGuard}`,
+		);
+	}
+	writeFileSync(entryPath, cliSource, "utf8");
 }
 
-if (existsSync(interactiveModePath)) {
+if (terminalPath && existsSync(terminalPath)) {
+	let terminalSource = readFileSync(terminalPath, "utf8");
+	if (!terminalSource.includes("stdinErrorHandler;")) {
+		terminalSource = terminalSource.replace(
+			"    stdinBuffer;\n    stdinDataHandler;\n",
+			[
+				"    stdinBuffer;",
+				"    stdinDataHandler;",
+				"    stdinErrorHandler = (error) => {",
+				'        if ((error?.code === "EIO" || error?.code === "EBADF") && error?.syscall === "read") {',
+				"            return;",
+				"        }",
+				"    };",
+			].join("\n") + "\n",
+		);
+	}
+	if (!terminalSource.includes('process.stdin.on("error", this.stdinErrorHandler);')) {
+		terminalSource = terminalSource.replace(
+			'        process.stdin.resume();\n',
+			'        process.stdin.resume();\n        process.stdin.on("error", this.stdinErrorHandler);\n',
+		);
+	}
+	if (!terminalSource.includes('            process.stdin.removeListener("error", this.stdinErrorHandler);')) {
+		terminalSource = terminalSource.replace(
+			'            process.stdin.removeListener("data", onData);\n            this.inputHandler = previousHandler;\n',
+			[
+				'            process.stdin.removeListener("data", onData);',
+				'            process.stdin.removeListener("error", this.stdinErrorHandler);',
+				'            this.inputHandler = previousHandler;',
+			].join("\n"),
+		);
+		terminalSource = terminalSource.replace(
+			'        process.stdin.pause();\n',
+			'        process.stdin.removeListener("error", this.stdinErrorHandler);\n        process.stdin.pause();\n',
+		);
+	}
+	writeFileSync(terminalPath, terminalSource, "utf8");
+}
+
+if (interactiveModePath && existsSync(interactiveModePath)) {
 	const interactiveModeSource = readFileSync(interactiveModePath, "utf8");
 	if (interactiveModeSource.includes("`π - ${sessionName} - ${cwdBasename}`")) {
 		writeFileSync(
@@ -214,7 +381,19 @@ if (existsSync(interactiveModePath)) {
 	}
 }
 
-if (existsSync(interactiveThemePath)) {
+for (const loaderPath of [extensionLoaderPath, workspaceExtensionLoaderPath].filter(Boolean)) {
+	if (!existsSync(loaderPath)) {
+		continue;
+	}
+
+	const source = readFileSync(loaderPath, "utf8");
+	const patched = patchPiExtensionLoaderSource(source);
+	if (patched !== source) {
+		writeFileSync(loaderPath, patched, "utf8");
+	}
+}
+
+if (interactiveThemePath && existsSync(interactiveThemePath)) {
 	let themeSource = readFileSync(interactiveThemePath, "utf8");
 	const desiredGetEditorTheme = [
 		"export function getEditorTheme() {",
@@ -389,6 +568,21 @@ if (existsSync(webAccessPath)) {
 	}
 }
 
+const piWebAccessRoot = resolve(workspaceRoot, "pi-web-access");
+
+if (existsSync(piWebAccessRoot)) {
+	for (const relativePath of PI_WEB_ACCESS_PATCH_TARGETS) {
+		const entryPath = resolve(piWebAccessRoot, relativePath);
+		if (!existsSync(entryPath)) continue;
+
+		const source = readFileSync(entryPath, "utf8");
+		const patched = patchPiWebAccessSource(relativePath, source);
+		if (patched !== source) {
+			writeFileSync(entryPath, patched, "utf8");
+		}
+	}
+}
+
 if (existsSync(sessionSearchIndexerPath)) {
 	const source = readFileSync(sessionSearchIndexerPath, "utf8");
 	const original = 'const sessionsDir = path.join(os.homedir(), ".pi", "agent", "sessions");';
@@ -400,6 +594,7 @@ if (existsSync(sessionSearchIndexerPath)) {
 }
 
 const oauthPagePath = piAiRoot ? resolve(piAiRoot, "dist", "utils", "oauth", "oauth-page.js") : null;
+const googleSharedPath = piAiRoot ? resolve(piAiRoot, "dist", "providers", "google-shared.js") : null;
 
 if (oauthPagePath && existsSync(oauthPagePath)) {
 	let source = readFileSync(oauthPagePath, "utf8");
@@ -412,6 +607,14 @@ if (oauthPagePath && existsSync(oauthPagePath)) {
 	if (changed) writeFileSync(oauthPagePath, source, "utf8");
 }
 
+if (googleSharedPath && existsSync(googleSharedPath)) {
+	const source = readFileSync(googleSharedPath, "utf8");
+	const patched = patchPiGoogleLegacySchemaSource(source);
+	if (patched !== source) {
+		writeFileSync(googleSharedPath, patched, "utf8");
+	}
+}
+
 const alphaHubAuthPath = findPackageRoot("@companion-ai/alpha-hub")
 	? resolve(findPackageRoot("@companion-ai/alpha-hub"), "src", "lib", "auth.js")
 	: null;
@@ -430,6 +633,11 @@ if (alphaHubAuthPath && existsSync(alphaHubAuthPath)) {
 	if (source.includes(oldError)) {
 		source = source.replace(oldError, newError);
 	}
+	const brokenWinOpen = "else if (plat === 'win32') execSync(`start \"${url}\"`);";
+	const fixedWinOpen = "else if (plat === 'win32') execSync(`cmd /c start \"\" \"${url}\"`);";
+	if (source.includes(brokenWinOpen)) {
+		source = source.replace(brokenWinOpen, fixedWinOpen);
+	}
 	writeFileSync(alphaHubAuthPath, source, "utf8");
 }
 

scripts/prepare-runtime-workspace.mjs

@@ -10,6 +10,7 @@ const workspaceNodeModulesDir = resolve(workspaceDir, "node_modules");
 const manifestPath = resolve(workspaceDir, ".runtime-manifest.json");
 const workspacePackageJsonPath = resolve(workspaceDir, "package.json");
 const workspaceArchivePath = resolve(feynmanDir, "runtime-workspace.tgz");
+const PRUNE_VERSION = 3;
 
 function readPackageSpecs() {
 	const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
@@ -44,7 +45,8 @@ function workspaceIsCurrent(packageSpecs) {
 		if (
 			manifest.nodeAbi !== process.versions.modules ||
 			manifest.platform !== process.platform ||
-			manifest.arch !== process.arch
+			manifest.arch !== process.arch ||
+			manifest.pruneVersion !== PRUNE_VERSION
 		) {
 			return false;
 		}
@@ -102,6 +104,7 @@ function writeManifest(packageSpecs) {
 					nodeVersion: process.version,
 					platform: process.platform,
 					arch: process.arch,
+					pruneVersion: PRUNE_VERSION,
 				},
 			null,
 			2,
@@ -110,6 +113,15 @@ function writeManifest(packageSpecs) {
 	);
 }
 
+function pruneWorkspace() {
+	const result = spawnSync(process.execPath, [resolve(appRoot, "scripts", "prune-runtime-deps.mjs"), workspaceDir], {
+		stdio: "inherit",
+	});
+	if (result.status !== 0) {
+		process.exit(result.status ?? 1);
+	}
+}
+
 function archiveIsCurrent() {
 	if (!existsSync(workspaceArchivePath) || !existsSync(manifestPath)) {
 		return false;
@@ -144,6 +156,7 @@ if (workspaceIsCurrent(packageSpecs)) {
 
 console.log("[feynman] preparing vendored runtime workspace...");
 prepareWorkspace(packageSpecs);
+pruneWorkspace();
 writeManifest(packageSpecs);
 createWorkspaceArchive();
 console.log("[feynman] vendored runtime workspace ready");

scripts/prune-runtime-deps.mjs

@@ -0,0 +1,131 @@
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+
+const root = resolve(process.argv[2] ?? ".");
+const nodeModulesDir = resolve(root, "node_modules");
+
+const STRIP_FILE_PATTERNS = [
+	/\.map$/i,
+	/\.d\.cts$/i,
+	/\.d\.ts$/i,
+	/^README(\..+)?\.md$/i,
+	/^CHANGELOG(\..+)?\.md$/i,
+];
+
+function safeStat(path) {
+	try {
+		return statSync(path);
+	} catch {
+		return null;
+	}
+}
+
+function removePath(path) {
+	rmSync(path, { recursive: true, force: true });
+}
+
+function walkAndPrune(dir) {
+	if (!existsSync(dir)) return;
+
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const path = join(dir, entry.name);
+		const stats = entry.isSymbolicLink() ? safeStat(path) : null;
+		const isDirectory = entry.isDirectory() || stats?.isDirectory();
+		const isFile = entry.isFile() || stats?.isFile();
+
+		if (isDirectory) {
+			walkAndPrune(path);
+			continue;
+		}
+
+		if (isFile && STRIP_FILE_PATTERNS.some((pattern) => pattern.test(entry.name))) {
+			removePath(path);
+		}
+	}
+}
+
+function currentKoffiVariant() {
+	if (process.platform === "darwin" && process.arch === "arm64") return "darwin_arm64";
+	if (process.platform === "darwin" && process.arch === "x64") return "darwin_x64";
+	if (process.platform === "linux" && process.arch === "arm64") return "linux_arm64";
+	if (process.platform === "linux" && process.arch === "x64") return "linux_x64";
+	if (process.platform === "win32" && process.arch === "arm64") return "win32_arm64";
+	if (process.platform === "win32" && process.arch === "x64") return "win32_x64";
+	return null;
+}
+
+function pruneKoffi(nodeModulesRoot) {
+	const koffiRoot = join(nodeModulesRoot, "koffi");
+	if (!existsSync(koffiRoot)) return;
+
+	for (const dirName of ["doc", "src", "vendor"]) {
+		removePath(join(koffiRoot, dirName));
+	}
+
+	const buildRoot = join(koffiRoot, "build", "koffi");
+	if (!existsSync(buildRoot)) return;
+
+	const keep = currentKoffiVariant();
+	for (const entry of readdirSync(buildRoot, { withFileTypes: true })) {
+		if (entry.name === keep) continue;
+		removePath(join(buildRoot, entry.name));
+	}
+}
+
+function pruneBetterSqlite3(nodeModulesRoot) {
+	const pkgRoot = join(nodeModulesRoot, "better-sqlite3");
+	if (!existsSync(pkgRoot)) return;
+
+	removePath(join(pkgRoot, "deps"));
+	removePath(join(pkgRoot, "src"));
+	removePath(join(pkgRoot, "binding.gyp"));
+
+	const buildRoot = join(pkgRoot, "build");
+	const releaseRoot = join(buildRoot, "Release");
+	if (existsSync(releaseRoot)) {
+		for (const entry of readdirSync(releaseRoot, { withFileTypes: true })) {
+			if (entry.name === "better_sqlite3.node") continue;
+			removePath(join(releaseRoot, entry.name));
+		}
+	}
+
+	for (const entry of ["Makefile", "binding.Makefile", "config.gypi", "deps", "gyp-mac-tool", "test_extension.target.mk", "better_sqlite3.target.mk"]) {
+		removePath(join(buildRoot, entry));
+	}
+}
+
+function pruneLiteparse(nodeModulesRoot) {
+	const pkgRoot = join(nodeModulesRoot, "@llamaindex", "liteparse");
+	if (!existsSync(pkgRoot)) return;
+	if (existsSync(join(pkgRoot, "dist"))) {
+		removePath(join(pkgRoot, "src"));
+	}
+}
+
+function prunePiCodingAgent(nodeModulesRoot) {
+	const pkgRoot = join(nodeModulesRoot, "@mariozechner", "pi-coding-agent");
+	if (!existsSync(pkgRoot)) return;
+	removePath(join(pkgRoot, "docs"));
+	removePath(join(pkgRoot, "examples"));
+}
+
+function pruneMermaid(nodeModulesRoot) {
+	const pkgRoot = join(nodeModulesRoot, "mermaid", "dist");
+	if (!existsSync(pkgRoot)) return;
+	removePath(join(pkgRoot, "docs"));
+	removePath(join(pkgRoot, "tests"));
+	removePath(join(pkgRoot, "__mocks__"));
+}
+
+if (!existsSync(nodeModulesDir)) {
+	process.exit(0);
+}
+
+walkAndPrune(nodeModulesDir);
+pruneKoffi(nodeModulesDir);
+pruneBetterSqlite3(nodeModulesDir);
+pruneLiteparse(nodeModulesDir);
+prunePiCodingAgent(nodeModulesDir);
+pruneMermaid(nodeModulesDir);
+
+console.log(`[feynman] pruned runtime deps in ${basename(root)}`);

scripts/sync-website-installers.mjs

@@ -7,5 +7,7 @@ const websitePublicDir = resolve(appRoot, "website", "public");
 mkdirSync(websitePublicDir, { recursive: true });
 cpSync(resolve(appRoot, "scripts", "install", "install.sh"), resolve(websitePublicDir, "install"));
 cpSync(resolve(appRoot, "scripts", "install", "install.ps1"), resolve(websitePublicDir, "install.ps1"));
+cpSync(resolve(appRoot, "scripts", "install", "install-skills.sh"), resolve(websitePublicDir, "install-skills"));
+cpSync(resolve(appRoot, "scripts", "install", "install-skills.ps1"), resolve(websitePublicDir, "install-skills.ps1"));
 
 console.log("[feynman] synced website installers");

skills/alpha-research/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: alpha-research
+description: Search, read, and query research papers via the `alpha` CLI (alphaXiv-backed). Use when the user asks about academic papers, wants to find research on a topic, needs to read a specific paper, ask questions about a paper, inspect a paper's code repository, or manage paper annotations.
+---
+
+# Alpha Research CLI
+
+Use the `alpha` CLI via bash for all paper research operations.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `alpha search "<query>"` | Search papers. Prefer `--mode semantic` by default; use `--mode keyword` only for exact-term lookup and `--mode agentic` for broader retrieval. |
+| `alpha get <arxiv-id-or-url>` | Fetch paper content and any local annotation |
+| `alpha get --full-text <arxiv-id>` | Get raw full text instead of AI report |
+| `alpha ask <arxiv-id> "<question>"` | Ask a question about a paper's PDF |
+| `alpha code <github-url> [path]` | Read files from a paper's GitHub repo. Use `/` for overview |
+| `alpha annotate <paper-id> "<note>"` | Save a persistent annotation on a paper |
+| `alpha annotate --clear <paper-id>` | Remove an annotation |
+| `alpha annotate --list` | List all annotations |
+
+## Auth
+
+Run `alpha login` to authenticate with alphaXiv. Check status with `feynman alpha status`, or `alpha status` once your installed `alpha-hub` version includes it.
+
+## Examples
+
+```bash
+alpha search "transformer scaling laws"
+alpha search --mode agentic "efficient attention mechanisms for long context"
+alpha get 2106.09685
+alpha ask 2106.09685 "What optimizer did they use?"
+alpha code https://github.com/karpathy/nanoGPT src/model.py
+alpha annotate 2106.09685 "Key paper on LoRA - revisit for adapter comparison"
+```
+
+## When to use
+
+- Academic paper search, reading, Q&A → `alpha`
+- Current topics (products, releases, docs) → web search tools
+- Mixed topics → combine both

skills/autoresearch/SKILL.md

@@ -5,7 +5,7 @@ description: Autonomous experiment loop that tries ideas, measures results, keep
 
 # Autoresearch
 
-Run the `/autoresearch` workflow. Read the prompt template at `prompts/autoresearch.md` for the full procedure.
+Run the `/autoresearch` workflow. Read the prompt template at `../prompts/autoresearch.md` for the full procedure.
 
 Tools used: `init_experiment`, `run_experiment`, `log_experiment` (from pi-autoresearch)
 

skills/contributing/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: contributing
+description: Contribute changes to the Feynman repository itself. Use when the task is to add features, fix bugs, update prompts or skills, change install or release behavior, improve docs, or prepare a focused PR against this repo.
+---
+
+# Contributing
+
+Read `../CONTRIBUTING.md` first, then `../AGENTS.md` for repo-level agent conventions.
+
+Use this skill when working on Feynman itself, especially for:
+
+- CLI or runtime changes in `src/`
+- prompt changes in `prompts/`
+- bundled skill changes in `skills/`
+- subagent behavior changes in `.feynman/agents/`
+- install, packaging, or release changes in `scripts/`, `README.md`, or website docs
+
+Minimum local checks before claiming the repo change is done:
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```
+
+If the docs site changed, also validate `website/`.
+
+When changing release-sensitive behavior, verify that `.nvmrc`, package `engines`, runtime guards, and install docs stay aligned.

skills/deep-research/SKILL.md

@@ -5,7 +5,7 @@ description: Run a thorough, source-heavy investigation on any topic. Use when t
 
 # Deep Research
 
-Run the `/deepresearch` workflow. Read the prompt template at `prompts/deepresearch.md` for the full procedure.
+Run the `/deepresearch` workflow. Read the prompt template at `../prompts/deepresearch.md` for the full procedure.
 
 Agents used: `researcher`, `verifier`, `reviewer`
 

skills/eli5/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: eli5
+description: Explain research, papers, or technical ideas in plain English with minimal jargon, concrete analogies, and clear takeaways. Use when the user says "ELI5 this", asks for a simple explanation of a paper or research result, wants jargon removed, or asks what something technically dense actually means.
+---
+
+# ELI5
+
+Use `alpha` first when the user names a specific paper, arXiv id, DOI, or paper URL.
+
+If the user gives only a topic, identify 1-3 representative papers and anchor the explanation around the clearest or most important one.
+
+Structure the answer with:
+- `One-Sentence Summary`
+- `Big Idea`
+- `How It Works`
+- `Why It Matters`
+- `What To Be Skeptical Of`
+- `If You Remember 3 Things`
+
+Guidelines:
+- Use short sentences and concrete words.
+- Define jargon immediately or remove it.
+- Prefer one good analogy over several weak ones.
+- Separate what the paper actually shows from speculation or interpretation.
+- Keep the explanation inline unless the user explicitly asks to save it as an artifact.

skills/jobs/SKILL.md

@@ -5,6 +5,6 @@ description: Inspect active background research work including running processes
 
 # Jobs
 
-Run the `/jobs` workflow. Read the prompt template at `prompts/jobs.md` for the full procedure.
+Run the `/jobs` workflow. Read the prompt template at `../prompts/jobs.md` for the full procedure.
 
 Shows active `pi-processes`, scheduled `pi-schedule-prompt` entries, and running subagent tasks.

skills/literature-review/SKILL.md

@@ -5,7 +5,7 @@ description: Run a literature review using paper search and primary-source synth
 
 # Literature Review
 
-Run the `/lit` workflow. Read the prompt template at `prompts/lit.md` for the full procedure.
+Run the `/lit` workflow. Read the prompt template at `../prompts/lit.md` for the full procedure.
 
 Agents used: `researcher`, `verifier`, `reviewer`
 

skills/modal-compute/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: modal-compute
+description: Run GPU workloads on Modal's serverless infrastructure. Use when the user needs remote GPU compute for training, inference, benchmarks, or batch processing and Modal CLI is available.
+---
+
+# Modal Compute
+
+Use the `modal` CLI for serverless GPU workloads. No pod lifecycle to manage — write a decorated Python script and run it.
+
+## Setup
+
+```bash
+pip install modal
+modal setup
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `modal run script.py` | Run a script on Modal (ephemeral) |
+| `modal run --detach script.py` | Run detached (background) |
+| `modal deploy script.py` | Deploy persistently |
+| `modal serve script.py` | Serve with hot-reload (dev) |
+| `modal shell --gpu a100` | Interactive shell with GPU |
+| `modal app list` | List deployed apps |
+
+## GPU types
+
+`T4`, `L4`, `A10G`, `L40S`, `A100`, `A100-80GB`, `H100`, `H200`, `B200`
+
+Multi-GPU: `"H100:4"` for 4x H100s.
+
+## Script pattern
+
+```python
+import modal
+
+app = modal.App("experiment")
+image = modal.Image.debian_slim(python_version="3.11").pip_install("torch==2.8.0")
+
+@app.function(gpu="A100", image=image, timeout=600)
+def train():
+    import torch
+    # training code here
+
+@app.local_entrypoint()
+def main():
+    train.remote()
+```
+
+## When to use
+
+- Stateless burst GPU jobs (training, inference, benchmarks)
+- No persistent state needed between runs
+- Check availability: `command -v modal`

skills/paper-code-audit/SKILL.md

@@ -5,7 +5,7 @@ description: Compare a paper's claims against its public codebase. Use when the
 
 # Paper-Code Audit
 
-Run the `/audit` workflow. Read the prompt template at `prompts/audit.md` for the full procedure.
+Run the `/audit` workflow. Read the prompt template at `../prompts/audit.md` for the full procedure.
 
 Agents used: `researcher`, `verifier`
 

skills/paper-writing/SKILL.md

@@ -5,7 +5,7 @@ description: Turn research findings into a polished paper-style draft with secti
 
 # Paper Writing
 
-Run the `/draft` workflow. Read the prompt template at `prompts/draft.md` for the full procedure.
+Run the `/draft` workflow. Read the prompt template at `../prompts/draft.md` for the full procedure.
 
 Agents used: `writer`, `verifier`
 

skills/peer-review/SKILL.md

@@ -5,7 +5,7 @@ description: Simulate a tough but constructive peer review of an AI research art
 
 # Peer Review
 
-Run the `/review` workflow. Read the prompt template at `prompts/review.md` for the full procedure.
+Run the `/review` workflow. Read the prompt template at `../prompts/review.md` for the full procedure.
 
 Agents used: `researcher`, `reviewer`
 

skills/preview/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: preview
+description: Preview Markdown, LaTeX, PDF, or code artifacts in the browser or as PDF. Use when the user wants to review a written artifact, export a report, or view a rendered document.
+---
+
+# Preview
+
+Use the `/preview` command to render and open artifacts.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/preview` | Preview the most recent artifact in the browser |
+| `/preview --file <path>` | Preview a specific file |
+| `/preview-browser` | Force browser preview |
+| `/preview-pdf` | Export to PDF via pandoc + LaTeX |
+| `/preview-clear-cache` | Clear rendered preview cache |
+
+## Fallback
+
+If the preview commands are not available, use bash:
+
+```bash
+open <file.md>          # macOS — opens in default app
+open <file.pdf>         # macOS — opens in Preview
+```

skills/replication/SKILL.md

@@ -5,7 +5,7 @@ description: Plan or execute a replication of a paper, claim, or benchmark. Use
 
 # Replication
 
-Run the `/replicate` workflow. Read the prompt template at `prompts/replicate.md` for the full procedure.
+Run the `/replicate` workflow. Read the prompt template at `../prompts/replicate.md` for the full procedure.
 
 Agents used: `researcher`
 

skills/runpod-compute/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: runpod-compute
+description: Provision and manage GPU pods on RunPod for long-running experiments. Use when the user needs persistent GPU compute with SSH access, large datasets, or multi-step experiments.
+---
+
+# RunPod Compute
+
+Use `runpodctl` CLI for persistent GPU pods with SSH access.
+
+## Setup
+
+```bash
+brew install runpod/runpodctl/runpodctl   # macOS
+runpodctl config --apiKey=YOUR_KEY
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `runpodctl create pod --gpuType "NVIDIA A100 80GB PCIe" --imageName "runpod/pytorch:2.4.0-py3.11-cuda12.4.1-devel-ubuntu22.04" --name experiment` | Create a pod |
+| `runpodctl get pod` | List all pods |
+| `runpodctl stop pod <id>` | Stop (preserves volume) |
+| `runpodctl start pod <id>` | Resume a stopped pod |
+| `runpodctl remove pod <id>` | Terminate and delete |
+| `runpodctl gpu list` | List available GPU types and prices |
+| `runpodctl send <file>` | Transfer files to/from pods |
+| `runpodctl receive <code>` | Receive transferred files |
+
+## SSH access
+
+```bash
+ssh root@<IP> -p <PORT> -i ~/.ssh/id_ed25519
+```
+
+Get connection details from `runpodctl get pod <id>`. Pods must expose port `22/tcp`.
+
+## GPU types
+
+`NVIDIA GeForce RTX 4090`, `NVIDIA RTX A6000`, `NVIDIA A40`, `NVIDIA A100 80GB PCIe`, `NVIDIA H100 80GB HBM3`
+
+## When to use
+
+- Long-running experiments needing persistent state
+- Large dataset processing
+- Multi-step work with SSH access between iterations
+- Always stop or remove pods after experiments
+- Check availability: `command -v runpodctl`

skills/session-log/SKILL.md

@@ -5,6 +5,6 @@ description: Write a durable session log capturing completed work, findings, ope
 
 # Session Log
 
-Run the `/log` workflow. Read the prompt template at `prompts/log.md` for the full procedure.
+Run the `/log` workflow. Read the prompt template at `../prompts/log.md` for the full procedure.
 
 Output: session log in `notes/session-logs/`.

skills/session-search/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: session-search
+description: Search past Feynman session transcripts to recover prior work, conversations, and research context. Use when the user references something from a previous session, asks "what did we do before", or when you suspect relevant past context exists.
+---
+
+# Session Search
+
+Use the `/search` command to search prior Feynman sessions interactively, or search session JSONL files directly via bash.
+
+## Interactive search
+
+```
+/search <query>
+```
+
+Opens the session search UI. Supports `resume <sessionPath>` to continue a found session.
+
+## Direct file search
+
+Session transcripts are stored as JSONL files in `~/.feynman/sessions/`. Each line is a JSON record with `type` (session, message, model_change) and `message.content` fields.
+
+```bash
+grep -ril "scaling laws" ~/.feynman/sessions/
+```
+
+For structured search across sessions, use the interactive `/search` command.

skills/source-comparison/SKILL.md

@@ -5,7 +5,7 @@ description: Compare multiple sources on a topic and produce a grounded comparis
 
 # Source Comparison
 
-Run the `/compare` workflow. Read the prompt template at `prompts/compare.md` for the full procedure.
+Run the `/compare` workflow. Read the prompt template at `../prompts/compare.md` for the full procedure.
 
 Agents used: `researcher`, `verifier`
 

skills/watch/SKILL.md

@@ -5,7 +5,7 @@ description: Set up a recurring research watch on a topic, company, paper area,
 
 # Watch
 
-Run the `/watch` workflow. Read the prompt template at `prompts/watch.md` for the full procedure.
+Run the `/watch` workflow. Read the prompt template at `../prompts/watch.md` for the full procedure.
 
 Agents used: `researcher`
 

src/bootstrap/sync.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 
 import { getBootstrapStatePath } from "../config/paths.js";
@@ -64,27 +64,76 @@ function listFiles(root: string): string[] {
 	return files.sort();
 }
 
+function removeEmptyParentDirectories(path: string, stopAt: string): void {
+	let current = dirname(path);
+	while (current.startsWith(stopAt) && current !== stopAt) {
+		if (!existsSync(current)) {
+			current = dirname(current);
+			continue;
+		}
+		if (readdirSync(current).length > 0) {
+			return;
+		}
+		rmSync(current, { recursive: true, force: true });
+		current = dirname(current);
+	}
+}
+
 function syncManagedFiles(
 	sourceRoot: string,
 	targetRoot: string,
+	scope: string,
 	state: BootstrapState,
 	result: BootstrapSyncResult,
 ): void {
+	const sourcePaths = new Set(listFiles(sourceRoot).map((sourcePath) => relative(sourceRoot, sourcePath)));
+
+	for (const targetPath of listFiles(targetRoot)) {
+		const key = relative(targetRoot, targetPath);
+		if (sourcePaths.has(key)) continue;
+
+		const scopedKey = `${scope}:${key}`;
+		const previous = state.files[scopedKey] ?? state.files[key];
+		if (!previous) {
+			continue;
+		}
+
+		if (!existsSync(targetPath)) {
+			delete state.files[scopedKey];
+			delete state.files[key];
+			continue;
+		}
+
+		const currentTargetText = readFileSync(targetPath, "utf8");
+		const currentTargetHash = sha256(currentTargetText);
+		if (currentTargetHash !== previous.lastAppliedTargetHash) {
+			result.skipped.push(key);
+			continue;
+		}
+
+		rmSync(targetPath, { force: true });
+		removeEmptyParentDirectories(targetPath, targetRoot);
+		delete state.files[scopedKey];
+		delete state.files[key];
+	}
+
 	for (const sourcePath of listFiles(sourceRoot)) {
 		const key = relative(sourceRoot, sourcePath);
 		const targetPath = resolve(targetRoot, key);
 		const sourceText = readFileSync(sourcePath, "utf8");
 		const sourceHash = sha256(sourceText);
-		const previous = state.files[key];
+		const scopedKey = `${scope}:${key}`;
+		const previous = state.files[scopedKey] ?? state.files[key];
 
 		mkdirSync(dirname(targetPath), { recursive: true });
 
 		if (!existsSync(targetPath)) {
 			writeFileSync(targetPath, sourceText, "utf8");
-			state.files[key] = {
+			state.files[scopedKey] = {
 				lastAppliedSourceHash: sourceHash,
 				lastAppliedTargetHash: sourceHash,
 			};
+			delete state.files[key];
 			result.copied.push(key);
 			continue;
 		}
@@ -93,10 +142,11 @@ function syncManagedFiles(
 		const currentTargetHash = sha256(currentTargetText);
 
 		if (currentTargetHash === sourceHash) {
-			state.files[key] = {
+			state.files[scopedKey] = {
 				lastAppliedSourceHash: sourceHash,
 				lastAppliedTargetHash: currentTargetHash,
 			};
+			delete state.files[key];
 			continue;
 		}
 
@@ -111,10 +161,11 @@ function syncManagedFiles(
 		}
 
 		writeFileSync(targetPath, sourceText, "utf8");
-		state.files[key] = {
+		state.files[scopedKey] = {
 			lastAppliedSourceHash: sourceHash,
 			lastAppliedTargetHash: sourceHash,
 		};
+		delete state.files[key];
 		result.updated.push(key);
 	}
 }
@@ -128,8 +179,9 @@ export function syncBundledAssets(appRoot: string, agentDir: string): BootstrapS
 		skipped: [],
 	};
 
-	syncManagedFiles(resolve(appRoot, ".feynman", "themes"), resolve(agentDir, "themes"), state, result);
-	syncManagedFiles(resolve(appRoot, ".feynman", "agents"), resolve(agentDir, "agents"), state, result);
+	syncManagedFiles(resolve(appRoot, ".feynman", "themes"), resolve(agentDir, "themes"), "themes", state, result);
+	syncManagedFiles(resolve(appRoot, ".feynman", "agents"), resolve(agentDir, "agents"), "agents", state, result);
+	syncManagedFiles(resolve(appRoot, "skills"), resolve(agentDir, "skills"), "skills", state, result);
 
 	writeBootstrapState(statePath, state);
 	return result;

src/cli.ts

@@ -11,25 +11,30 @@ import {
 	login as loginAlpha,
 	logout as logoutAlpha,
 } from "@companion-ai/alpha-hub/lib";
-import { AuthStorage, DefaultPackageManager, ModelRegistry, SettingsManager } from "@mariozechner/pi-coding-agent";
+import { DefaultPackageManager, SettingsManager } from "@mariozechner/pi-coding-agent";
 
 import { syncBundledAssets } from "./bootstrap/sync.js";
 import { ensureFeynmanHome, getDefaultSessionDir, getFeynmanAgentDir, getFeynmanHome } from "./config/paths.js";
 import { launchPiChat } from "./pi/launch.js";
 import { CORE_PACKAGE_SOURCES, getOptionalPackagePresetSources, listOptionalPackagePresets } from "./pi/package-presets.js";
 import { normalizeFeynmanSettings, normalizeThinkingLevel, parseModelSpec } from "./pi/settings.js";
+import { applyFeynmanPackageManagerEnv } from "./pi/runtime.js";
+import { getConfiguredServiceTier, normalizeServiceTier, setConfiguredServiceTier } from "./model/service-tier.js";
 import {
+	authenticateModelProvider,
 	getCurrentModelSpec,
 	loginModelProvider,
 	logoutModelProvider,
 	printModelList,
 	setDefaultModelSpec,
 } from "./model/commands.js";
-import { printSearchStatus } from "./search/commands.js";
+import { clearSearchConfig, printSearchStatus, setSearchProvider } from "./search/commands.js";
+import type { PiWebSearchProvider } from "./pi/web-access.js";
 import { runDoctor, runStatus } from "./setup/doctor.js";
 import { setupPreviewDependencies } from "./setup/preview.js";
 import { runSetup } from "./setup/setup.js";
-import { printAsciiHeader, printInfo, printPanel, printSection } from "./ui/terminal.js";
+import { ASH, printAsciiHeader, printInfo, printPanel, printSection, RESET, SAGE } from "./ui/terminal.js";
+import { createModelRegistry } from "./model/registry.js";
 import {
 	cliCommandSections,
 	formatCliWorkflowUsage,
@@ -43,7 +48,7 @@ const TOP_LEVEL_COMMANDS = new Set(topLevelCommandNames);
 function printHelpLine(usage: string, description: string): void {
 	const width = 30;
 	const padding = Math.max(1, width - usage.length);
-	printInfo(`${usage}${" ".repeat(padding)}${description}`);
+	console.log(`  ${SAGE}${usage}${RESET}${" ".repeat(padding)}${ASH}${description}${RESET}`);
 }
 
 function printHelp(appRoot: string): void {
@@ -124,7 +129,13 @@ async function handleModelCommand(subcommand: string | undefined, args: string[]
 	}
 
 	if (subcommand === "login") {
-		await loginModelProvider(feynmanAuthPath, args[0], feynmanSettingsPath);
+		if (args[0]) {
+			// Specific provider given - use OAuth login directly
+			await loginModelProvider(feynmanAuthPath, args[0], feynmanSettingsPath);
+		} else {
+			// No provider specified - show auth method choice
+			await authenticateModelProvider(feynmanAuthPath, feynmanSettingsPath);
+		}
 		return;
 	}
 
@@ -142,10 +153,34 @@ async function handleModelCommand(subcommand: string | undefined, args: string[]
 		return;
 	}
 
+	if (subcommand === "tier") {
+		const requested = args[0];
+		if (!requested) {
+			console.log(getConfiguredServiceTier(feynmanSettingsPath) ?? "not set");
+			return;
+		}
+
+		if (requested === "unset" || requested === "clear" || requested === "off") {
+			setConfiguredServiceTier(feynmanSettingsPath, undefined);
+			console.log("Cleared service tier override");
+			return;
+		}
+
+		const tier = normalizeServiceTier(requested);
+		if (!tier) {
+			throw new Error("Usage: feynman model tier <auto|default|flex|priority|standard_only|unset>");
+		}
+
+		setConfiguredServiceTier(feynmanSettingsPath, tier);
+		console.log(`Service tier set to ${tier}`);
+		return;
+	}
+
 	throw new Error(`Unknown model command: ${subcommand}`);
 }
 
 async function handleUpdateCommand(workingDir: string, feynmanAgentDir: string, source?: string): Promise<void> {
+	applyFeynmanPackageManagerEnv(feynmanAgentDir);
 	const settingsManager = SettingsManager.create(workingDir, feynmanAgentDir);
 	const packageManager = new DefaultPackageManager({
 		cwd: workingDir,
@@ -169,6 +204,7 @@ async function handleUpdateCommand(workingDir: string, feynmanAgentDir: string,
 }
 
 async function handlePackagesCommand(subcommand: string | undefined, args: string[], workingDir: string, feynmanAgentDir: string): Promise<void> {
+	applyFeynmanPackageManagerEnv(feynmanAgentDir);
 	const settingsManager = SettingsManager.create(workingDir, feynmanAgentDir);
 	const configuredSources = new Set(
 		settingsManager
@@ -234,12 +270,27 @@ async function handlePackagesCommand(subcommand: string | undefined, args: strin
 	console.log("Optional packages installed.");
 }
 
-function handleSearchCommand(subcommand: string | undefined): void {
+function handleSearchCommand(subcommand: string | undefined, args: string[]): void {
 	if (!subcommand || subcommand === "status") {
 		printSearchStatus();
 		return;
 	}
 
+	if (subcommand === "set") {
+		const provider = args[0] as PiWebSearchProvider | undefined;
+		const validProviders: PiWebSearchProvider[] = ["auto", "perplexity", "exa", "gemini"];
+		if (!provider || !validProviders.includes(provider)) {
+			throw new Error("Usage: feynman search set <auto|perplexity|exa|gemini> [api-key]");
+		}
+		setSearchProvider(provider, args[1]);
+		return;
+	}
+
+	if (subcommand === "clear") {
+		clearSearchConfig();
+		return;
+	}
+
 	throw new Error(`Unknown search command: ${subcommand}`);
 }
 
@@ -293,12 +344,15 @@ export async function main(): Promise<void> {
 			cwd: { type: "string" },
 			doctor: { type: "boolean" },
 			help: { type: "boolean" },
+			version: { type: "boolean" },
 			"alpha-login": { type: "boolean" },
 			"alpha-logout": { type: "boolean" },
 			"alpha-status": { type: "boolean" },
+			mode: { type: "string" },
 			model: { type: "string" },
 			"new-session": { type: "boolean" },
 			prompt: { type: "string" },
+			"service-tier": { type: "string" },
 			"session-dir": { type: "string" },
 			"setup-preview": { type: "boolean" },
 			thinking: { type: "string" },
@@ -310,6 +364,14 @@ export async function main(): Promise<void> {
 		return;
 	}
 
+	if (values.version) {
+		if (feynmanVersion) {
+			console.log(feynmanVersion);
+			return;
+		}
+		throw new Error("Unable to determine the installed Feynman version.");
+	}
+
 	const workingDir = resolve(values.cwd ?? process.cwd());
 	const sessionDir = resolve(values["session-dir"] ?? getDefaultSessionDir(feynmanHome));
 	const feynmanSettingsPath = resolve(feynmanAgentDir, "settings.json");
@@ -397,7 +459,7 @@ export async function main(): Promise<void> {
 	}
 
 	if (command === "search") {
-		handleSearchCommand(rest[0]);
+		handleSearchCommand(rest[0], rest.slice(1));
 		return;
 	}
 
@@ -417,8 +479,19 @@ export async function main(): Promise<void> {
 	}
 
 	const explicitModelSpec = values.model ?? process.env.FEYNMAN_MODEL;
+	const explicitServiceTier = normalizeServiceTier(values["service-tier"] ?? process.env.FEYNMAN_SERVICE_TIER);
+	const mode = values.mode;
+	if (mode !== undefined && mode !== "text" && mode !== "json" && mode !== "rpc") {
+		throw new Error("Unknown mode. Use text, json, or rpc.");
+	}
+	if ((values["service-tier"] ?? process.env.FEYNMAN_SERVICE_TIER) && !explicitServiceTier) {
+		throw new Error("Unknown service tier. Use auto, default, flex, priority, or standard_only.");
+	}
+	if (explicitServiceTier) {
+		process.env.FEYNMAN_SERVICE_TIER = explicitServiceTier;
+	}
 	if (explicitModelSpec) {
-		const modelRegistry = new ModelRegistry(AuthStorage.create(feynmanAuthPath));
+		const modelRegistry = createModelRegistry(feynmanAuthPath);
 		const explicitModel = parseModelSpec(explicitModelSpec, modelRegistry);
 		if (!explicitModel) {
 			throw new Error(`Unknown model: ${explicitModelSpec}`);
@@ -447,6 +520,7 @@ export async function main(): Promise<void> {
 		sessionDir,
 		feynmanAgentDir,
 		feynmanVersion,
+		mode,
 		thinkingLevel,
 		explicitModelSpec,
 		oneShotPrompt: values.prompt,

src/index.ts

@@ -1,6 +1,12 @@
-import { main } from "./cli.js";
+import { ensureSupportedNodeVersion } from "./system/node-version.js";
 
-main().catch((error) => {
+async function run(): Promise<void> {
+	ensureSupportedNodeVersion();
+	const { main } = await import("./cli.js");
+	await main();
+}
+
+run().catch((error) => {
 	console.error(error instanceof Error ? error.message : String(error));
 	process.exitCode = 1;
 });

src/model/catalog.ts

@@ -1,4 +1,4 @@
-import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+import { createModelRegistry } from "./registry.js";
 
 type ModelRecord = {
 	provider: string;
@@ -95,6 +95,14 @@ const RESEARCH_MODEL_PREFERENCES = [
 		spec: "zai/glm-5",
 		reason: "good fallback when GLM is the available research model",
 	},
+	{
+		spec: "minimax/minimax-m2.7",
+		reason: "good fallback when MiniMax is the available research model",
+	},
+	{
+		spec: "minimax/minimax-m2.7-highspeed",
+		reason: "good fallback when MiniMax is the available research model",
+	},
 	{
 		spec: "kimi-coding/kimi-k2-thinking",
 		reason: "good fallback when Kimi is the available research model",
@@ -166,10 +174,6 @@ function sortProviders(left: ProviderStatus, right: ProviderStatus): number {
 	return left.label.localeCompare(right.label);
 }
 
-function createModelRegistry(authPath: string): ModelRegistry {
-	return new ModelRegistry(AuthStorage.create(authPath));
-}
-
 export function getAvailableModelRecords(authPath: string): ModelRecord[] {
 	return createModelRegistry(authPath)
 		.getAvailable()
@@ -258,7 +262,9 @@ export function buildModelStatusSnapshotFromRecords(
 	const guidance: string[] = [];
 	if (available.length === 0) {
 		guidance.push("No authenticated Pi models are available yet.");
-		guidance.push("Run `feynman model login <provider>` or add provider credentials that Pi can see.");
+		guidance.push(
+			"Run `feynman model login <provider>` (OAuth) or configure an API key (env var, auth.json, or models.json for custom providers).",
+		);
 		guidance.push("After auth is in place, rerun `feynman model list` or `feynman setup model`.");
 	} else if (!current) {
 		guidance.push(`No default research model is set. Recommended: ${recommended?.spec}.`);

src/model/commands.ts

@@ -1,8 +1,11 @@
 import { AuthStorage } from "@mariozechner/pi-coding-agent";
 import { writeFileSync } from "node:fs";
+import { exec as execCallback } from "node:child_process";
+import { promisify } from "node:util";
 
 import { readJson } from "../pi/settings.js";
 import { promptChoice, promptText } from "../setup/prompts.js";
+import { openUrl } from "../system/open-url.js";
 import { printInfo, printSection, printSuccess, printWarning } from "../ui/terminal.js";
 import {
 	buildModelStatusSnapshotFromRecords,
@@ -11,6 +14,10 @@ import {
 	getSupportedModelRecords,
 	type ModelStatusSnapshot,
 } from "./catalog.js";
+import { createModelRegistry, getModelsJsonPath } from "./registry.js";
+import { upsertProviderBaseUrl, upsertProviderConfig } from "./models-json.js";
+
+const exec = promisify(execCallback);
 
 function collectModelStatus(settingsPath: string, authPath: string): ModelStatusSnapshot {
 	return buildModelStatusSnapshotFromRecords(
@@ -57,6 +64,453 @@ async function selectOAuthProvider(authPath: string, action: "login" | "logout")
 	return providers[selection];
 }
 
+type ApiKeyProviderInfo = {
+	id: string;
+	label: string;
+	envVar?: string;
+};
+
+const API_KEY_PROVIDERS: ApiKeyProviderInfo[] = [
+	{ id: "__custom__", label: "Custom provider (baseUrl + API key)" },
+	{ id: "openai", label: "OpenAI Platform API", envVar: "OPENAI_API_KEY" },
+	{ id: "anthropic", label: "Anthropic API", envVar: "ANTHROPIC_API_KEY" },
+	{ id: "google", label: "Google Gemini API", envVar: "GEMINI_API_KEY" },
+	{ id: "openrouter", label: "OpenRouter", envVar: "OPENROUTER_API_KEY" },
+	{ id: "zai", label: "Z.AI / GLM", envVar: "ZAI_API_KEY" },
+	{ id: "kimi-coding", label: "Kimi / Moonshot", envVar: "KIMI_API_KEY" },
+	{ id: "minimax", label: "MiniMax", envVar: "MINIMAX_API_KEY" },
+	{ id: "minimax-cn", label: "MiniMax (China)", envVar: "MINIMAX_CN_API_KEY" },
+	{ id: "mistral", label: "Mistral", envVar: "MISTRAL_API_KEY" },
+	{ id: "groq", label: "Groq", envVar: "GROQ_API_KEY" },
+	{ id: "xai", label: "xAI", envVar: "XAI_API_KEY" },
+	{ id: "cerebras", label: "Cerebras", envVar: "CEREBRAS_API_KEY" },
+	{ id: "vercel-ai-gateway", label: "Vercel AI Gateway", envVar: "AI_GATEWAY_API_KEY" },
+	{ id: "huggingface", label: "Hugging Face", envVar: "HF_TOKEN" },
+	{ id: "opencode", label: "OpenCode Zen", envVar: "OPENCODE_API_KEY" },
+	{ id: "opencode-go", label: "OpenCode Go", envVar: "OPENCODE_API_KEY" },
+	{ id: "azure-openai-responses", label: "Azure OpenAI (Responses)", envVar: "AZURE_OPENAI_API_KEY" },
+];
+
+async function selectApiKeyProvider(): Promise<ApiKeyProviderInfo | undefined> {
+	const choices = API_KEY_PROVIDERS.map(
+		(provider) => `${provider.id} — ${provider.label}${provider.envVar ? ` (${provider.envVar})` : ""}`,
+	);
+	choices.push("Cancel");
+	const selection = await promptChoice("Choose an API-key provider:", choices, 0);
+	if (selection >= API_KEY_PROVIDERS.length) {
+		return undefined;
+	}
+	return API_KEY_PROVIDERS[selection];
+}
+
+type CustomProviderSetup = {
+	providerId: string;
+	modelIds: string[];
+	baseUrl: string;
+	api: "openai-completions" | "openai-responses" | "anthropic-messages" | "google-generative-ai";
+	apiKeyConfig: string;
+	/**
+	 * If true, add `Authorization: Bearer <apiKey>` to requests in addition to
+	 * whatever the API mode uses (useful for proxies that implement /v1/messages
+	 * but expect Bearer auth instead of x-api-key).
+	 */
+	authHeader: boolean;
+};
+
+function normalizeProviderId(value: string): string {
+	return value.trim().toLowerCase().replace(/\s+/g, "-");
+}
+
+function normalizeModelIds(value: string): string[] {
+	const items = value
+		.split(",")
+		.map((entry) => entry.trim())
+		.filter(Boolean);
+	return Array.from(new Set(items));
+}
+
+function normalizeBaseUrl(value: string): string {
+	return value.trim().replace(/\/+$/, "");
+}
+
+function normalizeCustomProviderBaseUrl(
+	api: CustomProviderSetup["api"],
+	baseUrl: string,
+): { baseUrl: string; note?: string } {
+	const normalized = normalizeBaseUrl(baseUrl);
+	if (!normalized) {
+		return { baseUrl: normalized };
+	}
+
+	// Pi expects Anthropic baseUrl without `/v1` (it appends `/v1/messages` internally).
+	if (api === "anthropic-messages" && /\/v1$/i.test(normalized)) {
+		return { baseUrl: normalized.replace(/\/v1$/i, ""), note: "Stripped trailing /v1 for Anthropic mode." };
+	}
+
+	return { baseUrl: normalized };
+}
+
+function isLocalBaseUrl(baseUrl: string): boolean {
+	return /^(https?:\/\/)?(localhost|127\.0\.0\.1|0\.0\.0\.0)(:|\/|$)/i.test(baseUrl);
+}
+
+async function resolveApiKeyConfig(apiKeyConfig: string): Promise<string | undefined> {
+	const trimmed = apiKeyConfig.trim();
+	if (!trimmed) return undefined;
+
+	if (trimmed.startsWith("!")) {
+		const command = trimmed.slice(1).trim();
+		if (!command) return undefined;
+		const shell = process.platform === "win32" ? process.env.ComSpec || "cmd.exe" : process.env.SHELL || "/bin/sh";
+		try {
+			const { stdout } = await exec(command, { shell, maxBuffer: 1024 * 1024 });
+			const value = stdout.trim();
+			return value || undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
+	const envValue = process.env[trimmed];
+	if (typeof envValue === "string" && envValue.trim()) {
+		return envValue.trim();
+	}
+
+	// Fall back to literal value.
+	return trimmed;
+}
+
+async function bestEffortFetchOpenAiModelIds(
+	baseUrl: string,
+	apiKey: string,
+	authHeader: boolean,
+): Promise<string[] | undefined> {
+	const url = `${baseUrl}/models`;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), 5000);
+	try {
+		const response = await fetch(url, {
+			method: "GET",
+			headers: authHeader ? { Authorization: `Bearer ${apiKey}` } : undefined,
+			signal: controller.signal,
+		});
+		if (!response.ok) {
+			return undefined;
+		}
+		const json = (await response.json()) as any;
+		if (!Array.isArray(json?.data)) return undefined;
+		return json.data
+			.map((entry: any) => (typeof entry?.id === "string" ? entry.id : undefined))
+			.filter(Boolean);
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+async function promptCustomProviderSetup(): Promise<CustomProviderSetup | undefined> {
+	printSection("Custom Provider");
+	const providerIdInput = await promptText("Provider id (e.g. my-proxy)", "custom");
+	const providerId = normalizeProviderId(providerIdInput);
+	if (!providerId || providerId === "__custom__") {
+		printWarning("Invalid provider id.");
+		return undefined;
+	}
+
+	const apiChoices = [
+		"openai-completions — OpenAI Chat Completions compatible (e.g. /v1/chat/completions)",
+		"openai-responses — OpenAI Responses compatible (e.g. /v1/responses)",
+		"anthropic-messages — Anthropic Messages compatible (e.g. /v1/messages)",
+		"google-generative-ai — Google Generative AI compatible (generativelanguage.googleapis.com)",
+		"Cancel",
+	];
+	const apiSelection = await promptChoice("API mode:", apiChoices, 0);
+	if (apiSelection >= 4) {
+		return undefined;
+	}
+	const api = ["openai-completions", "openai-responses", "anthropic-messages", "google-generative-ai"][apiSelection] as CustomProviderSetup["api"];
+
+	const baseUrlDefault = ((): string => {
+		if (api === "openai-completions" || api === "openai-responses") return "http://localhost:11434/v1";
+		if (api === "anthropic-messages") return "https://api.anthropic.com";
+		if (api === "google-generative-ai") return "https://generativelanguage.googleapis.com";
+		return "http://localhost:11434/v1";
+	})();
+	const baseUrlPrompt =
+		api === "openai-completions" || api === "openai-responses"
+			? "Base URL (include /v1 for OpenAI-compatible endpoints)"
+			: api === "anthropic-messages"
+				? "Base URL (no trailing /, no /v1)"
+				: "Base URL (no trailing /)";
+	const baseUrlRaw = await promptText(baseUrlPrompt, baseUrlDefault);
+	const { baseUrl, note: baseUrlNote } = normalizeCustomProviderBaseUrl(api, baseUrlRaw);
+	if (!baseUrl) {
+		printWarning("Base URL is required.");
+		return undefined;
+	}
+	if (baseUrlNote) {
+		printInfo(baseUrlNote);
+	}
+
+	let authHeader = false;
+	if (api === "openai-completions" || api === "openai-responses") {
+		const defaultAuthHeader = !isLocalBaseUrl(baseUrl);
+		const authHeaderChoices = [
+			"Yes (send Authorization: Bearer <apiKey>)",
+			"No (common for local Ollama/vLLM/LM Studio)",
+			"Cancel",
+		];
+		const authHeaderSelection = await promptChoice(
+			"Send Authorization header?",
+			authHeaderChoices,
+			defaultAuthHeader ? 0 : 1,
+		);
+		if (authHeaderSelection >= 2) {
+			return undefined;
+		}
+		authHeader = authHeaderSelection === 0;
+	}
+	if (api === "anthropic-messages") {
+		const defaultAuthHeader = isLocalBaseUrl(baseUrl);
+		const authHeaderChoices = [
+			"Yes (also send Authorization: Bearer <apiKey>)",
+			"No (standard Anthropic uses x-api-key only)",
+			"Cancel",
+		];
+		const authHeaderSelection = await promptChoice(
+			"Also send Authorization header?",
+			authHeaderChoices,
+			defaultAuthHeader ? 0 : 1,
+		);
+		if (authHeaderSelection >= 2) {
+			return undefined;
+		}
+		authHeader = authHeaderSelection === 0;
+	}
+
+	printInfo("API key value supports:");
+	printInfo("  - literal secret (stored in models.json)");
+	printInfo("  - env var name (resolved at runtime)");
+	printInfo("  - !command (executes and uses stdout)");
+	const apiKeyConfigRaw = (await promptText("API key / resolver", "")).trim();
+	const apiKeyConfig = apiKeyConfigRaw || "local";
+	if (!apiKeyConfigRaw) {
+		printInfo("Using placeholder apiKey value (required by Pi for custom providers).");
+	}
+
+	let modelIdsDefault = "my-model";
+	if (api === "openai-completions" || api === "openai-responses") {
+		// Best-effort: hit /models so users can pick correct ids (especially for proxies).
+		const resolvedKey = await resolveApiKeyConfig(apiKeyConfig);
+		const modelIds = resolvedKey ? await bestEffortFetchOpenAiModelIds(baseUrl, resolvedKey, authHeader) : undefined;
+		if (modelIds && modelIds.length > 0) {
+			const sample = modelIds.slice(0, 10).join(", ");
+			printInfo(`Detected models: ${sample}${modelIds.length > 10 ? ", ..." : ""}`);
+			modelIdsDefault = modelIds.includes("sonnet") ? "sonnet" : modelIds[0]!;
+		}
+	}
+
+	const modelIdsRaw = await promptText("Model id(s) (comma-separated)", modelIdsDefault);
+	const modelIds = normalizeModelIds(modelIdsRaw);
+	if (modelIds.length === 0) {
+		printWarning("At least one model id is required.");
+		return undefined;
+	}
+
+	return { providerId, modelIds, baseUrl, api, apiKeyConfig, authHeader };
+}
+
+async function verifyCustomProvider(setup: CustomProviderSetup, authPath: string): Promise<void> {
+	const registry = createModelRegistry(authPath);
+	const modelsError = registry.getError();
+	if (modelsError) {
+		printWarning("Verification: models.json failed to load.");
+		for (const line of modelsError.split("\n")) {
+			printInfo(`  ${line}`);
+		}
+		return;
+	}
+
+	const all = registry.getAll();
+	const hasModel = setup.modelIds.some((id) => all.some((model) => model.provider === setup.providerId && model.id === id));
+	if (!hasModel) {
+		printWarning("Verification: model registry does not contain the configured provider/model ids.");
+		return;
+	}
+
+	const available = registry.getAvailable();
+	const hasAvailable = setup.modelIds.some((id) =>
+		available.some((model) => model.provider === setup.providerId && model.id === id),
+	);
+	if (!hasAvailable) {
+		printWarning("Verification: provider is not considered authenticated/available.");
+		return;
+	}
+
+	const apiKey = await registry.getApiKeyForProvider(setup.providerId);
+	if (!apiKey) {
+		printWarning("Verification: API key could not be resolved (check env var name / !command).");
+		return;
+	}
+
+	const timeoutMs = 8000;
+
+	// Best-effort network check for OpenAI-compatible endpoints
+	if (setup.api === "openai-completions" || setup.api === "openai-responses") {
+		const url = `${setup.baseUrl}/models`;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const response = await fetch(url, {
+				method: "GET",
+				headers: setup.authHeader ? { Authorization: `Bearer ${apiKey}` } : undefined,
+				signal: controller.signal,
+			});
+			if (!response.ok) {
+				printWarning(`Verification: ${url} returned ${response.status} ${response.statusText}`);
+				return;
+			}
+			const json = (await response.json()) as unknown;
+			const modelIds = Array.isArray((json as any)?.data)
+				? (json as any).data.map((entry: any) => (typeof entry?.id === "string" ? entry.id : undefined)).filter(Boolean)
+				: [];
+			const missing = setup.modelIds.filter((id) => modelIds.length > 0 && !modelIds.includes(id));
+			if (modelIds.length > 0 && missing.length > 0) {
+				printWarning(`Verification: /models does not list configured model id(s): ${missing.join(", ")}`);
+				return;
+			}
+			printSuccess("Verification: endpoint reachable and authorized.");
+		} catch (error) {
+			printWarning(`Verification: failed to reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+		} finally {
+			clearTimeout(timer);
+		}
+		return;
+	}
+
+	if (setup.api === "anthropic-messages") {
+		const url = `${setup.baseUrl}/v1/models?limit=1`;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const headers: Record<string, string> = {
+				"x-api-key": apiKey,
+				"anthropic-version": "2023-06-01",
+			};
+			if (setup.authHeader) {
+				headers.Authorization = `Bearer ${apiKey}`;
+			}
+			const response = await fetch(url, {
+				method: "GET",
+				headers,
+				signal: controller.signal,
+			});
+			if (!response.ok) {
+				printWarning(`Verification: ${url} returned ${response.status} ${response.statusText}`);
+				if (response.status === 404) {
+					printInfo("  Tip: For Anthropic mode, use a base URL without /v1 (e.g. https://api.anthropic.com).");
+				}
+				if ((response.status === 401 || response.status === 403) && !setup.authHeader) {
+					printInfo("  Tip: Some proxies require `Authorization: Bearer <apiKey>` even in Anthropic mode.");
+				}
+				return;
+			}
+			printSuccess("Verification: endpoint reachable and authorized.");
+		} catch (error) {
+			printWarning(`Verification: failed to reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+		} finally {
+			clearTimeout(timer);
+		}
+		return;
+	}
+
+	if (setup.api === "google-generative-ai") {
+		const url = `${setup.baseUrl}/v1beta/models?key=${encodeURIComponent(apiKey)}`;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const response = await fetch(url, { method: "GET", signal: controller.signal });
+			if (!response.ok) {
+				printWarning(`Verification: ${url} returned ${response.status} ${response.statusText}`);
+				return;
+			}
+			printSuccess("Verification: endpoint reachable and authorized.");
+		} catch (error) {
+			printWarning(`Verification: failed to reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+		} finally {
+			clearTimeout(timer);
+		}
+		return;
+	}
+
+	printInfo("Verification: skipped network probe for this API mode.");
+}
+
+async function configureApiKeyProvider(authPath: string): Promise<boolean> {
+	const provider = await selectApiKeyProvider();
+	if (!provider) {
+		printInfo("API key setup cancelled.");
+		return false;
+	}
+
+	if (provider.id === "__custom__") {
+		const setup = await promptCustomProviderSetup();
+		if (!setup) {
+			printInfo("Custom provider setup cancelled.");
+			return false;
+		}
+
+		const modelsJsonPath = getModelsJsonPath(authPath);
+		const result = upsertProviderConfig(modelsJsonPath, setup.providerId, {
+			baseUrl: setup.baseUrl,
+			apiKey: setup.apiKeyConfig,
+			api: setup.api,
+			authHeader: setup.authHeader,
+			models: setup.modelIds.map((id) => ({ id })),
+		});
+		if (!result.ok) {
+			printWarning(result.error);
+			return false;
+		}
+
+		printSuccess(`Saved custom provider: ${setup.providerId}`);
+		await verifyCustomProvider(setup, authPath);
+		return true;
+	}
+
+	printSection(`API Key: ${provider.label}`);
+	if (provider.envVar) {
+		printInfo(`Tip: to avoid writing secrets to disk, set ${provider.envVar} in your shell or .env.`);
+	}
+
+	const apiKey = await promptText("Paste API key (leave empty to use env var instead)", "");
+	if (!apiKey) {
+		if (provider.envVar) {
+			printInfo(`Set ${provider.envVar} and rerun setup (or run \`feynman model list\`).`);
+		} else {
+			printInfo("No API key provided.");
+		}
+		return false;
+	}
+
+	AuthStorage.create(authPath).set(provider.id, { type: "api_key", key: apiKey });
+	printSuccess(`Saved API key for ${provider.id} in auth storage.`);
+
+	const baseUrl = await promptText("Base URL override (optional, include /v1 for OpenAI-compatible endpoints)", "");
+	if (baseUrl) {
+		const modelsJsonPath = getModelsJsonPath(authPath);
+		const result = upsertProviderBaseUrl(modelsJsonPath, provider.id, baseUrl);
+		if (result.ok) {
+			printSuccess(`Saved baseUrl override for ${provider.id} in models.json.`);
+		} else {
+			printWarning(result.error);
+		}
+	}
+
+	return true;
+}
+
 function resolveAvailableModelSpec(authPath: string, input: string): string | undefined {
 	const normalizedInput = input.trim().toLowerCase();
 	if (!normalizedInput) {
@@ -110,14 +564,46 @@ export function printModelList(settingsPath: string, authPath: string): void {
 	}
 }
 
-export async function loginModelProvider(authPath: string, providerId?: string, settingsPath?: string): Promise<void> {
+export async function authenticateModelProvider(authPath: string, settingsPath?: string): Promise<boolean> {
+	const choices = [
+		"API key (OpenAI, Anthropic, Google, custom provider, ...)",
+		"OAuth login (ChatGPT Plus/Pro, Claude Pro/Max, Copilot, ...)",
+		"Cancel",
+	];
+	const selection = await promptChoice("How do you want to authenticate?", choices, 0);
+
+	if (selection === 0) {
+		const configured = await configureApiKeyProvider(authPath);
+		if (configured && settingsPath) {
+			const currentSpec = getCurrentModelSpec(settingsPath);
+			const available = getAvailableModelRecords(authPath);
+			const currentValid = currentSpec ? available.some((m) => `${m.provider}/${m.id}` === currentSpec) : false;
+			if ((!currentSpec || !currentValid) && available.length > 0) {
+				const recommended = chooseRecommendedModel(authPath);
+				if (recommended) {
+					setDefaultModelSpec(settingsPath, authPath, recommended.spec);
+				}
+			}
+		}
+		return configured;
+	}
+
+	if (selection === 1) {
+		return loginModelProvider(authPath, undefined, settingsPath);
+	}
+
+	printInfo("Authentication cancelled.");
+	return false;
+}
+
+export async function loginModelProvider(authPath: string, providerId?: string, settingsPath?: string): Promise<boolean> {
 	const provider = providerId ? resolveOAuthProvider(authPath, providerId) : await selectOAuthProvider(authPath, "login");
 	if (!provider) {
 		if (providerId) {
 			throw new Error(`Unknown OAuth model provider: ${providerId}`);
 		}
 		printInfo("Login cancelled.");
-		return;
+		return false;
 	}
 
 	const authStorage = AuthStorage.create(authPath);
@@ -126,7 +612,13 @@ export async function loginModelProvider(authPath: string, providerId?: string,
 	await authStorage.login(provider.id, {
 		onAuth: (info: { url: string; instructions?: string }) => {
 			printSection(`Login: ${provider.name ?? provider.id}`);
-			printInfo(`Open this URL: ${info.url}`);
+			const opened = openUrl(info.url);
+			if (opened) {
+				printInfo("Opened the login URL in your browser.");
+			} else {
+				printWarning("Couldn't open your browser automatically.");
+			}
+			printInfo(`Auth URL: ${info.url}`);
 			if (info.instructions) {
 				printInfo(info.instructions);
 			}
@@ -159,6 +651,8 @@ export async function loginModelProvider(authPath: string, providerId?: string,
 			}
 		}
 	}
+
+	return true;
 }
 
 export async function logoutModelProvider(authPath: string, providerId?: string): Promise<void> {
@@ -193,11 +687,34 @@ export function setDefaultModelSpec(settingsPath: string, authPath: string, spec
 export async function runModelSetup(settingsPath: string, authPath: string): Promise<void> {
 	let status = collectModelStatus(settingsPath, authPath);
 
-	if (status.availableModels.length === 0) {
-		await loginModelProvider(authPath, undefined, settingsPath);
+	while (status.availableModels.length === 0) {
+		const choices = [
+			"API key (OpenAI, Anthropic, ZAI, Kimi, MiniMax, ...)",
+			"OAuth login (ChatGPT Plus/Pro, Claude Pro/Max, Copilot, ...)",
+			"Cancel",
+		];
+		const selection = await promptChoice("Choose how to configure model access:", choices, 0);
+		if (selection === 0) {
+			const configured = await configureApiKeyProvider(authPath);
+			if (!configured) {
+				status = collectModelStatus(settingsPath, authPath);
+				continue;
+			}
+		} else if (selection === 1) {
+			const loggedIn = await loginModelProvider(authPath, undefined, settingsPath);
+			if (!loggedIn) {
+				status = collectModelStatus(settingsPath, authPath);
+				continue;
+			}
+		} else {
+			printInfo("Setup cancelled.");
+			return;
+		}
 		status = collectModelStatus(settingsPath, authPath);
 		if (status.availableModels.length === 0) {
-			return;
+			printWarning("No authenticated models are available yet.");
+			printInfo("If you configured a custom provider, ensure it has `apiKey` set in models.json.");
+			printInfo("Tip: run `feynman doctor` to see models.json path + load errors.");
 		}
 	}
 

src/model/models-json.ts

@@ -0,0 +1,91 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+type ModelsJson = {
+	providers?: Record<string, Record<string, unknown>>;
+};
+
+function readModelsJson(modelsJsonPath: string): { ok: true; value: ModelsJson } | { ok: false; error: string } {
+	if (!existsSync(modelsJsonPath)) {
+		return { ok: true, value: { providers: {} } };
+	}
+
+	try {
+		const raw = readFileSync(modelsJsonPath, "utf8").trim();
+		if (!raw) {
+			return { ok: true, value: { providers: {} } };
+		}
+		const parsed = JSON.parse(raw) as unknown;
+		if (!parsed || typeof parsed !== "object") {
+			return { ok: false, error: `Invalid models.json (expected an object): ${modelsJsonPath}` };
+		}
+		return { ok: true, value: parsed as ModelsJson };
+	} catch (error) {
+		return {
+			ok: false,
+			error: `Failed to read models.json: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+}
+
+export function upsertProviderBaseUrl(
+	modelsJsonPath: string,
+	providerId: string,
+	baseUrl: string,
+): { ok: true } | { ok: false; error: string } {
+	return upsertProviderConfig(modelsJsonPath, providerId, { baseUrl });
+}
+
+export type ProviderConfigPatch = {
+	baseUrl?: string;
+	apiKey?: string;
+	api?: string;
+	authHeader?: boolean;
+	headers?: Record<string, string>;
+	models?: Array<{ id: string }>;
+};
+
+export function upsertProviderConfig(
+	modelsJsonPath: string,
+	providerId: string,
+	patch: ProviderConfigPatch,
+): { ok: true } | { ok: false; error: string } {
+	const loaded = readModelsJson(modelsJsonPath);
+	if (!loaded.ok) {
+		return loaded;
+	}
+
+	const value: ModelsJson = loaded.value;
+	const providers: Record<string, Record<string, unknown>> = {
+		...(value.providers && typeof value.providers === "object" ? value.providers : {}),
+	};
+
+	const currentProvider =
+		providers[providerId] && typeof providers[providerId] === "object" ? providers[providerId] : {};
+
+	const nextProvider: Record<string, unknown> = { ...currentProvider };
+	if (patch.baseUrl !== undefined) nextProvider.baseUrl = patch.baseUrl;
+	if (patch.apiKey !== undefined) nextProvider.apiKey = patch.apiKey;
+	if (patch.api !== undefined) nextProvider.api = patch.api;
+	if (patch.authHeader !== undefined) nextProvider.authHeader = patch.authHeader;
+	if (patch.headers !== undefined) nextProvider.headers = patch.headers;
+	if (patch.models !== undefined) nextProvider.models = patch.models;
+
+	providers[providerId] = nextProvider;
+
+	const next: ModelsJson = { ...value, providers };
+
+	try {
+		mkdirSync(dirname(modelsJsonPath), { recursive: true });
+		writeFileSync(modelsJsonPath, JSON.stringify(next, null, 2) + "\n", "utf8");
+		// models.json can contain API keys/headers; default to user-only permissions.
+		try {
+			chmodSync(modelsJsonPath, 0o600);
+		} catch {
+			// ignore permission errors (best-effort)
+		}
+		return { ok: true };
+	} catch (error) {
+		return { ok: false, error: `Failed to write models.json: ${error instanceof Error ? error.message : String(error)}` };
+	}
+}

src/model/registry.ts

@@ -0,0 +1,11 @@
+import { dirname, resolve } from "node:path";
+
+import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+
+export function getModelsJsonPath(authPath: string): string {
+	return resolve(dirname(authPath), "models.json");
+}
+
+export function createModelRegistry(authPath: string): ModelRegistry {
+	return ModelRegistry.create(AuthStorage.create(authPath), getModelsJsonPath(authPath));
+}

src/model/service-tier.ts

@@ -0,0 +1,65 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+export const FEYNMAN_SERVICE_TIERS = [
+	"auto",
+	"default",
+	"flex",
+	"priority",
+	"standard_only",
+] as const;
+
+export type FeynmanServiceTier = (typeof FEYNMAN_SERVICE_TIERS)[number];
+
+const SERVICE_TIER_SET = new Set<string>(FEYNMAN_SERVICE_TIERS);
+const OPENAI_SERVICE_TIERS = new Set<FeynmanServiceTier>(["auto", "default", "flex", "priority"]);
+const ANTHROPIC_SERVICE_TIERS = new Set<FeynmanServiceTier>(["auto", "standard_only"]);
+
+function readSettings(settingsPath: string): Record<string, unknown> {
+	try {
+		return JSON.parse(readFileSync(settingsPath, "utf8")) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+export function normalizeServiceTier(value: string | undefined): FeynmanServiceTier | undefined {
+	if (!value) return undefined;
+	const normalized = value.trim().toLowerCase();
+	return SERVICE_TIER_SET.has(normalized) ? (normalized as FeynmanServiceTier) : undefined;
+}
+
+export function getConfiguredServiceTier(settingsPath: string): FeynmanServiceTier | undefined {
+	const settings = readSettings(settingsPath);
+	return normalizeServiceTier(typeof settings.serviceTier === "string" ? settings.serviceTier : undefined);
+}
+
+export function setConfiguredServiceTier(settingsPath: string, tier: FeynmanServiceTier | undefined): void {
+	const settings = readSettings(settingsPath);
+	if (tier) {
+		settings.serviceTier = tier;
+	} else {
+		delete settings.serviceTier;
+	}
+
+	mkdirSync(dirname(settingsPath), { recursive: true });
+	writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+}
+
+export function resolveActiveServiceTier(settingsPath: string): FeynmanServiceTier | undefined {
+	return normalizeServiceTier(process.env.FEYNMAN_SERVICE_TIER) ?? getConfiguredServiceTier(settingsPath);
+}
+
+export function resolveProviderServiceTier(
+	provider: string | undefined,
+	tier: FeynmanServiceTier | undefined,
+): FeynmanServiceTier | undefined {
+	if (!provider || !tier) return undefined;
+	if ((provider === "openai" || provider === "openai-codex") && OPENAI_SERVICE_TIERS.has(tier)) {
+		return tier;
+	}
+	if (provider === "anthropic" && ANTHROPIC_SERVICE_TIERS.has(tier)) {
+		return tier;
+	}
+	return undefined;
+}

src/pi/launch.ts

@@ -1,22 +1,38 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { constants } from "node:os";
 
-import { buildPiArgs, buildPiEnv, type PiRuntimeOptions, resolvePiPaths } from "./runtime.js";
+import { buildPiArgs, buildPiEnv, type PiRuntimeOptions, resolvePiPaths, toNodeImportSpecifier } from "./runtime.js";
+import { ensureSupportedNodeVersion } from "../system/node-version.js";
+
+export function exitCodeFromSignal(signal: NodeJS.Signals): number {
+	const signalNumber = constants.signals[signal];
+	return typeof signalNumber === "number" ? 128 + signalNumber : 1;
+}
 
 export async function launchPiChat(options: PiRuntimeOptions): Promise<void> {
-	const { piCliPath, promisePolyfillPath } = resolvePiPaths(options.appRoot);
+	ensureSupportedNodeVersion();
+
+	const { piCliPath, promisePolyfillPath, promisePolyfillSourcePath, tsxLoaderPath } = resolvePiPaths(options.appRoot);
 	if (!existsSync(piCliPath)) {
 		throw new Error(`Pi CLI not found: ${piCliPath}`);
 	}
-	if (!existsSync(promisePolyfillPath)) {
+
+	const useBuiltPolyfill = existsSync(promisePolyfillPath);
+	const useDevPolyfill = !useBuiltPolyfill && existsSync(promisePolyfillSourcePath) && existsSync(tsxLoaderPath);
+	if (!useBuiltPolyfill && !useDevPolyfill) {
 		throw new Error(`Promise polyfill not found: ${promisePolyfillPath}`);
 	}
 
-	if (process.stdout.isTTY) {
+	if (process.stdout.isTTY && options.mode !== "rpc") {
 		process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
 	}
 
-	const child = spawn(process.execPath, ["--import", promisePolyfillPath, piCliPath, ...buildPiArgs(options)], {
+	const importArgs = useDevPolyfill
+		? ["--import", toNodeImportSpecifier(tsxLoaderPath), "--import", toNodeImportSpecifier(promisePolyfillSourcePath)]
+		: ["--import", toNodeImportSpecifier(promisePolyfillPath)];
+
+	const child = spawn(process.execPath, [...importArgs, piCliPath, ...buildPiArgs(options)], {
 		cwd: options.workingDir,
 		stdio: "inherit",
 		env: buildPiEnv(options),
@@ -26,7 +42,9 @@ export async function launchPiChat(options: PiRuntimeOptions): Promise<void> {
 		child.on("error", reject);
 		child.on("exit", (code, signal) => {
 			if (signal) {
-				process.kill(process.pid, signal);
+				console.error(`feynman terminated because the Pi child exited with ${signal}.`);
+				process.exitCode = exitCodeFromSignal(signal);
+				resolvePromise();
 				return;
 			}
 			process.exitCode = code ?? 0;

src/pi/package-presets.ts

@@ -1,6 +1,7 @@
 import type { PackageSource } from "@mariozechner/pi-coding-agent";
 
 export const CORE_PACKAGE_SOURCES = [
+	"npm:@companion-ai/alpha-hub",
 	"npm:pi-subagents",
 	"npm:pi-btw",
 	"npm:pi-docparser",
@@ -23,13 +24,13 @@ export const OPTIONAL_PACKAGE_PRESETS = {
 	},
 } as const;
 
+export type OptionalPackagePresetName = keyof typeof OPTIONAL_PACKAGE_PRESETS;
+
 const LEGACY_DEFAULT_PACKAGE_SOURCES = [
 	...CORE_PACKAGE_SOURCES,
 	"npm:pi-generative-ui",
 ] as const;
 
-export type OptionalPackagePresetName = keyof typeof OPTIONAL_PACKAGE_PRESETS;
-
 function arraysMatchAsSets(left: readonly string[], right: readonly string[]): boolean {
 	if (left.length !== right.length) {
 		return false;

src/pi/runtime.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { delimiter, dirname, isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 
 import {
 	BROWSER_FALLBACK_PATHS,
@@ -14,30 +15,54 @@ export type PiRuntimeOptions = {
 	sessionDir: string;
 	feynmanAgentDir: string;
 	feynmanVersion?: string;
+	mode?: "text" | "json" | "rpc";
 	thinkingLevel?: string;
 	explicitModelSpec?: string;
 	oneShotPrompt?: string;
 	initialPrompt?: string;
 };
 
+export function getFeynmanNpmPrefixPath(feynmanAgentDir: string): string {
+	return resolve(dirname(feynmanAgentDir), "npm-global");
+}
+
+export function applyFeynmanPackageManagerEnv(feynmanAgentDir: string): string {
+	const feynmanNpmPrefixPath = getFeynmanNpmPrefixPath(feynmanAgentDir);
+	process.env.FEYNMAN_NPM_PREFIX = feynmanNpmPrefixPath;
+	process.env.NPM_CONFIG_PREFIX = feynmanNpmPrefixPath;
+	process.env.npm_config_prefix = feynmanNpmPrefixPath;
+	return feynmanNpmPrefixPath;
+}
+
 export function resolvePiPaths(appRoot: string) {
 	return {
 		piPackageRoot: resolve(appRoot, "node_modules", "@mariozechner", "pi-coding-agent"),
 		piCliPath: resolve(appRoot, "node_modules", "@mariozechner", "pi-coding-agent", "dist", "cli.js"),
 		promisePolyfillPath: resolve(appRoot, "dist", "system", "promise-polyfill.js"),
+		promisePolyfillSourcePath: resolve(appRoot, "src", "system", "promise-polyfill.ts"),
+		tsxLoaderPath: resolve(appRoot, "node_modules", "tsx", "dist", "loader.mjs"),
 		researchToolsPath: resolve(appRoot, "extensions", "research-tools.ts"),
 		promptTemplatePath: resolve(appRoot, "prompts"),
 		systemPromptPath: resolve(appRoot, ".feynman", "SYSTEM.md"),
 		piWorkspaceNodeModulesPath: resolve(appRoot, ".feynman", "npm", "node_modules"),
+		nodeModulesBinPath: resolve(appRoot, "node_modules", ".bin"),
 	};
 }
 
+export function toNodeImportSpecifier(modulePath: string): string {
+	return isAbsolute(modulePath) ? pathToFileURL(modulePath).href : modulePath;
+}
+
 export function validatePiInstallation(appRoot: string): string[] {
 	const paths = resolvePiPaths(appRoot);
 	const missing: string[] = [];
 
 	if (!existsSync(paths.piCliPath)) missing.push(paths.piCliPath);
-	if (!existsSync(paths.promisePolyfillPath)) missing.push(paths.promisePolyfillPath);
+	if (!existsSync(paths.promisePolyfillPath)) {
+		// Dev fallback: allow running from source without `dist/` build artifacts.
+		const hasDevPolyfill = existsSync(paths.promisePolyfillSourcePath) && existsSync(paths.tsxLoaderPath);
+		if (!hasDevPolyfill) missing.push(paths.promisePolyfillPath);
+	}
 	if (!existsSync(paths.researchToolsPath)) missing.push(paths.researchToolsPath);
 	if (!existsSync(paths.promptTemplatePath)) missing.push(paths.promptTemplatePath);
 
@@ -59,6 +84,9 @@ export function buildPiArgs(options: PiRuntimeOptions): string[] {
 		args.push("--system-prompt", readFileSync(paths.systemPromptPath, "utf8"));
 	}
 
+	if (options.mode) {
+		args.push("--mode", options.mode);
+	}
 	if (options.explicitModelSpec) {
 		args.push("--model", options.explicitModelSpec);
 	}
@@ -76,19 +104,36 @@ export function buildPiArgs(options: PiRuntimeOptions): string[] {
 
 export function buildPiEnv(options: PiRuntimeOptions): NodeJS.ProcessEnv {
 	const paths = resolvePiPaths(options.appRoot);
+	const feynmanNpmPrefixPath = getFeynmanNpmPrefixPath(options.feynmanAgentDir);
+	const feynmanNpmBinPath = resolve(feynmanNpmPrefixPath, "bin");
+	const feynmanWebSearchConfigPath = resolve(dirname(options.feynmanAgentDir), "web-search.json");
+
+	const currentPath = process.env.PATH ?? "";
+	const binEntries = [paths.nodeModulesBinPath, resolve(paths.piWorkspaceNodeModulesPath, ".bin"), feynmanNpmBinPath];
+	const binPath = binEntries.join(delimiter);
 
 	return {
 		...process.env,
+		PATH: `${binPath}${delimiter}${currentPath}`,
 		FEYNMAN_VERSION: options.feynmanVersion,
 		FEYNMAN_SESSION_DIR: options.sessionDir,
 		FEYNMAN_MEMORY_DIR: resolve(dirname(options.feynmanAgentDir), "memory"),
+		FEYNMAN_WEB_SEARCH_CONFIG: feynmanWebSearchConfigPath,
 		FEYNMAN_NODE_EXECUTABLE: process.execPath,
 		FEYNMAN_BIN_PATH: resolve(options.appRoot, "bin", "feynman.js"),
+		FEYNMAN_NPM_PREFIX: feynmanNpmPrefixPath,
+		// Ensure the Pi child process uses Feynman's agent dir for auth/models/settings.
+		PI_CODING_AGENT_DIR: options.feynmanAgentDir,
 		PANDOC_PATH: process.env.PANDOC_PATH ?? resolveExecutable("pandoc", PANDOC_FALLBACK_PATHS),
 		PI_HARDWARE_CURSOR: process.env.PI_HARDWARE_CURSOR ?? "1",
 		PI_SKIP_VERSION_CHECK: process.env.PI_SKIP_VERSION_CHECK ?? "1",
 		MERMAID_CLI_PATH: process.env.MERMAID_CLI_PATH ?? resolveExecutable("mmdc", MERMAID_FALLBACK_PATHS),
 		PUPPETEER_EXECUTABLE_PATH:
 			process.env.PUPPETEER_EXECUTABLE_PATH ?? resolveExecutable("google-chrome", BROWSER_FALLBACK_PATHS),
+		// Always pin npm's global prefix to the Feynman workspace. npm injects
+		// lowercase config vars into child processes, which would otherwise leak
+		// the caller's global prefix into Pi.
+		NPM_CONFIG_PREFIX: feynmanNpmPrefixPath,
+		npm_config_prefix: feynmanNpmPrefixPath,
 	};
 }

src/pi/settings.ts

@@ -1,9 +1,10 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
-import { AuthStorage, ModelRegistry, type PackageSource } from "@mariozechner/pi-coding-agent";
+import { ModelRegistry, type PackageSource } from "@mariozechner/pi-coding-agent";
 
 import { CORE_PACKAGE_SOURCES, shouldPruneLegacyDefaultPackages } from "./package-presets.js";
+import { createModelRegistry } from "../model/registry.js";
 
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
@@ -115,8 +116,7 @@ export function normalizeFeynmanSettings(
 		settings.packages = [...CORE_PACKAGE_SOURCES];
 	}
 
-	const authStorage = AuthStorage.create(authPath);
-	const modelRegistry = new ModelRegistry(authStorage);
+	const modelRegistry = createModelRegistry(authPath);
 	const availableModels = modelRegistry.getAvailable().map((model) => ({
 		provider: model.provider,
 		id: model.id,

src/pi/web-access.ts

@@ -1,13 +1,15 @@
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { getFeynmanHome } from "../config/paths.js";
 
-export type PiWebSearchProvider = "auto" | "perplexity" | "gemini";
+export type PiWebSearchProvider = "auto" | "perplexity" | "exa" | "gemini";
 
 export type PiWebAccessConfig = Record<string, unknown> & {
+	route?: PiWebSearchProvider;
 	provider?: PiWebSearchProvider;
 	searchProvider?: PiWebSearchProvider;
 	perplexityApiKey?: string;
+	exaApiKey?: string;
 	geminiApiKey?: string;
 	chromeProfile?: string;
 };
@@ -17,18 +19,20 @@ export type PiWebAccessStatus = {
 	searchProvider: PiWebSearchProvider;
 	requestProvider: PiWebSearchProvider;
 	perplexityConfigured: boolean;
+	exaConfigured: boolean;
 	geminiApiConfigured: boolean;
 	chromeProfile?: string;
 	routeLabel: string;
 	note: string;
 };
 
-export function getPiWebSearchConfigPath(home = process.env.HOME ?? homedir()): string {
-	return resolve(home, ".feynman", "web-search.json");
+export function getPiWebSearchConfigPath(home?: string): string {
+	const feynmanHome = home ? resolve(home, ".feynman") : getFeynmanHome();
+	return resolve(feynmanHome, "web-search.json");
 }
 
 function normalizeProvider(value: unknown): PiWebSearchProvider | undefined {
-	return value === "auto" || value === "perplexity" || value === "gemini" ? value : undefined;
+	return value === "auto" || value === "perplexity" || value === "exa" || value === "gemini" ? value : undefined;
 }
 
 function normalizeNonEmptyString(value: unknown): string | undefined {
@@ -48,10 +52,29 @@ export function loadPiWebAccessConfig(configPath = getPiWebSearchConfigPath()):
 	}
 }
 
+export function savePiWebAccessConfig(
+	updates: Partial<Record<keyof PiWebAccessConfig, unknown>>,
+	configPath = getPiWebSearchConfigPath(),
+): void {
+	const merged: Record<string, unknown> = { ...loadPiWebAccessConfig(configPath) };
+	for (const [key, value] of Object.entries(updates)) {
+		if (value === undefined) {
+			delete merged[key];
+		} else {
+			merged[key] = value;
+		}
+	}
+
+	mkdirSync(dirname(configPath), { recursive: true });
+	writeFileSync(configPath, JSON.stringify(merged, null, 2) + "\n", "utf8");
+}
+
 function formatRouteLabel(provider: PiWebSearchProvider): string {
 	switch (provider) {
 		case "perplexity":
 			return "Perplexity";
+		case "exa":
+			return "Exa";
 		case "gemini":
 			return "Gemini";
 		default:
@@ -63,10 +86,12 @@ function formatRouteNote(provider: PiWebSearchProvider): string {
 	switch (provider) {
 		case "perplexity":
 			return "Pi web-access will use Perplexity for search.";
+		case "exa":
+			return "Pi web-access will use Exa for search.";
 		case "gemini":
 			return "Pi web-access will use Gemini API or Gemini Browser.";
 		default:
-			return "Pi web-access will try Perplexity, then Gemini API, then Gemini Browser.";
+			return "Pi web-access will try Perplexity, then Exa, then Gemini API, then Gemini Browser.";
 	}
 }
 
@@ -74,9 +99,11 @@ export function getPiWebAccessStatus(
 	config: PiWebAccessConfig = loadPiWebAccessConfig(),
 	configPath = getPiWebSearchConfigPath(),
 ): PiWebAccessStatus {
-	const searchProvider = normalizeProvider(config.searchProvider) ?? "auto";
-	const requestProvider = normalizeProvider(config.provider) ?? searchProvider;
+	const searchProvider =
+		normalizeProvider(config.searchProvider) ?? normalizeProvider(config.route) ?? normalizeProvider(config.provider) ?? "auto";
+	const requestProvider = normalizeProvider(config.provider) ?? normalizeProvider(config.route) ?? searchProvider;
 	const perplexityConfigured = Boolean(normalizeNonEmptyString(config.perplexityApiKey));
+	const exaConfigured = Boolean(normalizeNonEmptyString(config.exaApiKey));
 	const geminiApiConfigured = Boolean(normalizeNonEmptyString(config.geminiApiKey));
 	const chromeProfile = normalizeNonEmptyString(config.chromeProfile);
 	const effectiveProvider = searchProvider;
@@ -86,6 +113,7 @@ export function getPiWebAccessStatus(
 		searchProvider,
 		requestProvider,
 		perplexityConfigured,
+		exaConfigured,
 		geminiApiConfigured,
 		chromeProfile,
 		routeLabel: formatRouteLabel(effectiveProvider),
@@ -101,6 +129,7 @@ export function formatPiWebAccessDoctorLines(
 		`  search route: ${status.routeLabel}`,
 		`  request route: ${status.requestProvider}`,
 		`  perplexity api: ${status.perplexityConfigured ? "configured" : "not configured"}`,
+		`  exa api: ${status.exaConfigured ? "configured" : "not configured"}`,
 		`  gemini api: ${status.geminiApiConfigured ? "configured" : "not configured"}`,
 		`  browser profile: ${status.chromeProfile ?? "default Chromium profile"}`,
 		`  config path: ${status.configPath}`,

src/search/commands.ts

@@ -1,13 +1,58 @@
-import { getPiWebAccessStatus } from "../pi/web-access.js";
+import {
+	getPiWebAccessStatus,
+	savePiWebAccessConfig,
+	type PiWebAccessConfig,
+	type PiWebSearchProvider,
+} from "../pi/web-access.js";
 import { printInfo } from "../ui/terminal.js";
 
+const SEARCH_PROVIDERS: PiWebSearchProvider[] = ["auto", "perplexity", "exa", "gemini"];
+const PROVIDER_API_KEY_FIELDS: Partial<Record<PiWebSearchProvider, keyof PiWebAccessConfig>> = {
+	perplexity: "perplexityApiKey",
+	exa: "exaApiKey",
+	gemini: "geminiApiKey",
+};
+
 export function printSearchStatus(): void {
 	const status = getPiWebAccessStatus();
 	printInfo("Managed by: pi-web-access");
 	printInfo(`Search route: ${status.routeLabel}`);
 	printInfo(`Request route: ${status.requestProvider}`);
 	printInfo(`Perplexity API configured: ${status.perplexityConfigured ? "yes" : "no"}`);
+	printInfo(`Exa API configured: ${status.exaConfigured ? "yes" : "no"}`);
 	printInfo(`Gemini API configured: ${status.geminiApiConfigured ? "yes" : "no"}`);
 	printInfo(`Browser profile: ${status.chromeProfile ?? "default Chromium profile"}`);
 	printInfo(`Config path: ${status.configPath}`);
 }
+
+export function setSearchProvider(provider: PiWebSearchProvider, apiKey?: string): void {
+	if (!SEARCH_PROVIDERS.includes(provider)) {
+		throw new Error(`Usage: feynman search set <${SEARCH_PROVIDERS.join("|")}> [api-key]`);
+	}
+	if (apiKey !== undefined && provider === "auto") {
+		throw new Error("The auto provider does not use an API key. Usage: feynman search set auto");
+	}
+
+	const updates: Partial<Record<keyof PiWebAccessConfig, unknown>> = {
+		provider,
+		searchProvider: provider,
+		route: undefined,
+	};
+	const apiKeyField = PROVIDER_API_KEY_FIELDS[provider];
+	if (apiKeyField && apiKey !== undefined) {
+		updates[apiKeyField] = apiKey;
+	}
+	savePiWebAccessConfig(updates);
+
+	const status = getPiWebAccessStatus();
+	console.log(`Web search provider set to ${status.routeLabel}.`);
+	console.log(`Config path: ${status.configPath}`);
+}
+
+export function clearSearchConfig(): void {
+	savePiWebAccessConfig({ provider: undefined, searchProvider: undefined, route: undefined });
+
+	const status = getPiWebAccessStatus();
+	console.log(`Web search provider reset to ${status.routeLabel}.`);
+	console.log(`Config path: ${status.configPath}`);
+}

src/setup/doctor.ts

@@ -1,6 +1,7 @@
-import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
 import { getUserName as getAlphaUserName, isLoggedIn as isAlphaLoggedIn } from "@companion-ai/alpha-hub/lib";
 
+import { readFileSync } from "node:fs";
+
 import { formatPiWebAccessDoctorLines, getPiWebAccessStatus } from "../pi/web-access.js";
 import { BROWSER_FALLBACK_PATHS, PANDOC_FALLBACK_PATHS, resolveExecutable } from "../system/executables.js";
 import { readJson } from "../pi/settings.js";
@@ -8,6 +9,31 @@ import { validatePiInstallation } from "../pi/runtime.js";
 import { printInfo, printPanel, printSection } from "../ui/terminal.js";
 import { getCurrentModelSpec } from "../model/commands.js";
 import { buildModelStatusSnapshotFromRecords, getAvailableModelRecords, getSupportedModelRecords } from "../model/catalog.js";
+import { createModelRegistry, getModelsJsonPath } from "../model/registry.js";
+import { getConfiguredServiceTier } from "../model/service-tier.js";
+
+function findProvidersMissingApiKey(modelsJsonPath: string): string[] {
+	try {
+		const raw = readFileSync(modelsJsonPath, "utf8").trim();
+		if (!raw) return [];
+		const parsed = JSON.parse(raw) as any;
+		const providers = parsed?.providers;
+		if (!providers || typeof providers !== "object") return [];
+		const missing: string[] = [];
+		for (const [providerId, config] of Object.entries(providers as Record<string, unknown>)) {
+			if (!config || typeof config !== "object") continue;
+			const models = (config as any).models;
+			if (!Array.isArray(models) || models.length === 0) continue;
+			const apiKey = (config as any).apiKey;
+			if (typeof apiKey !== "string" || apiKey.trim().length === 0) {
+				missing.push(providerId);
+			}
+		}
+		return missing;
+	} catch {
+		return [];
+	}
+}
 
 export type DoctorOptions = {
 	settingsPath: string;
@@ -80,6 +106,7 @@ export function runStatus(options: DoctorOptions): void {
 	printInfo(`Recommended model: ${snapshot.recommendedModel ?? "not available"}`);
 	printInfo(`alphaXiv: ${snapshot.alphaLoggedIn ? snapshot.alphaUser ?? "configured" : "not configured"}`);
 	printInfo(`Web access: pi-web-access (${snapshot.webRouteLabel})`);
+	printInfo(`Service tier: ${getConfiguredServiceTier(options.settingsPath) ?? "not set"}`);
 	printInfo(`Preview: ${snapshot.previewConfigured ? "configured" : "not configured"}`);
 
 	printSection("Paths");
@@ -104,7 +131,7 @@ export function runStatus(options: DoctorOptions): void {
 
 export function runDoctor(options: DoctorOptions): void {
 	const settings = readJson(options.settingsPath);
-	const modelRegistry = new ModelRegistry(AuthStorage.create(options.authPath));
+	const modelRegistry = createModelRegistry(options.authPath);
 	const availableModels = modelRegistry.getAvailable();
 	const pandocPath = resolveExecutable("pandoc", PANDOC_FALLBACK_PATHS);
 	const browserPath = process.env.PUPPETEER_EXECUTABLE_PATH ?? resolveExecutable("google-chrome", BROWSER_FALLBACK_PATHS);
@@ -140,10 +167,26 @@ export function runDoctor(options: DoctorOptions): void {
 	console.log(`default model valid: ${modelStatus.modelValid ? "yes" : "no"}`);
 	console.log(`authenticated providers: ${modelStatus.authenticatedProviderCount}`);
 	console.log(`authenticated models: ${modelStatus.authenticatedModelCount}`);
+	console.log(`service tier: ${getConfiguredServiceTier(options.settingsPath) ?? "not set"}`);
 	console.log(`recommended model: ${modelStatus.recommendedModel ?? "not available"}`);
 	if (modelStatus.recommendedModelReason) {
 		console.log(`  why: ${modelStatus.recommendedModelReason}`);
 	}
+	const modelsError = modelRegistry.getError();
+	if (modelsError) {
+		console.log("models.json: error");
+		for (const line of modelsError.split("\n")) {
+			console.log(`  ${line}`);
+		}
+	} else {
+		const modelsJsonPath = getModelsJsonPath(options.authPath);
+		console.log(`models.json: ${modelsJsonPath}`);
+		const missingApiKeyProviders = findProvidersMissingApiKey(modelsJsonPath);
+		if (missingApiKeyProviders.length > 0) {
+			console.log(`  warning: provider(s) missing apiKey: ${missingApiKeyProviders.join(", ")}`);
+			console.log("  note: custom providers with a models[] list need apiKey in models.json to be available.");
+		}
+	}
 	console.log(`pandoc: ${pandocPath ?? "missing"}`);
 	console.log(`browser preview runtime: ${browserPath ?? "missing"}`);
 	for (const line of formatPiWebAccessDoctorLines()) {

src/setup/preview.ts

@@ -13,13 +13,35 @@ export function setupPreviewDependencies(): PreviewSetupResult {
 		return { status: "ready", message: `pandoc already installed at ${pandocPath}` };
 	}
 
-	const brewPath = resolveExecutable("brew", BREW_FALLBACK_PATHS);
-	if (process.platform === "darwin" && brewPath) {
-		const result = spawnSync(brewPath, ["install", "pandoc"], { stdio: "inherit" });
-		if (result.status !== 0) {
-			throw new Error("Failed to install pandoc via Homebrew.");
+	if (process.platform === "darwin") {
+		const brewPath = resolveExecutable("brew", BREW_FALLBACK_PATHS);
+		if (brewPath) {
+			const result = spawnSync(brewPath, ["install", "pandoc"], { stdio: "inherit" });
+			if (result.status !== 0) {
+				throw new Error("Failed to install pandoc via Homebrew.");
+			}
+			return { status: "installed", message: "Preview dependency installed: pandoc" };
+		}
+	}
+
+	if (process.platform === "win32") {
+		const wingetPath = resolveExecutable("winget");
+		if (wingetPath) {
+			const result = spawnSync(wingetPath, ["install", "--id", "JohnMacFarlane.Pandoc", "-e"], { stdio: "inherit" });
+			if (result.status === 0) {
+				return { status: "installed", message: "Preview dependency installed: pandoc (via winget)" };
+			}
+		}
+	}
+
+	if (process.platform === "linux") {
+		const aptPath = resolveExecutable("apt-get");
+		if (aptPath) {
+			const result = spawnSync(aptPath, ["install", "-y", "pandoc"], { stdio: "inherit" });
+			if (result.status === 0) {
+				return { status: "installed", message: "Preview dependency installed: pandoc (via apt)" };
+			}
 		}
-		return { status: "installed", message: "Preview dependency installed: pandoc" };
 	}
 
 	return {

src/setup/setup.ts

@@ -29,6 +29,7 @@ function printNonInteractiveSetupGuidance(): void {
 	printInfo("Non-interactive terminal. Use explicit commands:");
 	printInfo("  feynman model login <provider>");
 	printInfo("  feynman model set <provider/model>");
+	printInfo("  # or configure API keys via env vars/auth.json and rerun `feynman model list`");
 	printInfo("  feynman alpha login");
 	printInfo("  feynman doctor");
 }

src/system/executables.ts

@@ -1,27 +1,36 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 
-export const PANDOC_FALLBACK_PATHS = [
-	"/opt/homebrew/bin/pandoc",
-	"/usr/local/bin/pandoc",
-];
+const isWindows = process.platform === "win32";
+const programFiles = process.env.PROGRAMFILES ?? "C:\\Program Files";
+const localAppData = process.env.LOCALAPPDATA ?? "";
 
-export const BREW_FALLBACK_PATHS = [
-	"/opt/homebrew/bin/brew",
-	"/usr/local/bin/brew",
-];
+export const PANDOC_FALLBACK_PATHS = isWindows
+	? [`${programFiles}\\Pandoc\\pandoc.exe`]
+	: ["/opt/homebrew/bin/pandoc", "/usr/local/bin/pandoc"];
 
-export const BROWSER_FALLBACK_PATHS = [
-	"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-	"/Applications/Chromium.app/Contents/MacOS/Chromium",
-	"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
-	"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-];
+export const BREW_FALLBACK_PATHS = isWindows
+	? []
+	: ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"];
 
-export const MERMAID_FALLBACK_PATHS = [
-	"/opt/homebrew/bin/mmdc",
-	"/usr/local/bin/mmdc",
-];
+export const BROWSER_FALLBACK_PATHS = isWindows
+	? [
+			`${programFiles}\\Google\\Chrome\\Application\\chrome.exe`,
+			`${programFiles} (x86)\\Google\\Chrome\\Application\\chrome.exe`,
+			`${localAppData}\\Google\\Chrome\\Application\\chrome.exe`,
+			`${programFiles}\\Microsoft\\Edge\\Application\\msedge.exe`,
+			`${programFiles}\\BraveSoftware\\Brave-Browser\\Application\\brave.exe`,
+		]
+	: [
+			"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+			"/Applications/Chromium.app/Contents/MacOS/Chromium",
+			"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+			"/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+		];
+
+export const MERMAID_FALLBACK_PATHS = isWindows
+	? []
+	: ["/opt/homebrew/bin/mmdc", "/usr/local/bin/mmdc"];
 
 export function resolveExecutable(name: string, fallbackPaths: string[] = []): string | undefined {
 	for (const candidate of fallbackPaths) {
@@ -30,13 +39,19 @@ export function resolveExecutable(name: string, fallbackPaths: string[] = []): s
 		}
 	}
 
-	const result = spawnSync("sh", ["-lc", `command -v ${name}`], {
-		encoding: "utf8",
-		stdio: ["ignore", "pipe", "ignore"],
-	});
+	const isWindows = process.platform === "win32";
+	const result = isWindows
+		? spawnSync("cmd", ["/c", `where ${name}`], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+			})
+		: spawnSync("sh", ["-lc", `command -v ${name}`], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+			});
 
 	if (result.status === 0) {
-		const resolved = result.stdout.trim();
+		const resolved = result.stdout.trim().split(/\r?\n/)[0];
 		if (resolved) {
 			return resolved;
 		}

src/system/node-version.ts

@@ -0,0 +1,45 @@
+export const MIN_NODE_VERSION = "20.19.0";
+
+type ParsedNodeVersion = {
+	major: number;
+	minor: number;
+	patch: number;
+};
+
+function parseNodeVersion(version: string): ParsedNodeVersion {
+	const [major = "0", minor = "0", patch = "0"] = version.replace(/^v/, "").split(".");
+	return {
+		major: Number.parseInt(major, 10) || 0,
+		minor: Number.parseInt(minor, 10) || 0,
+		patch: Number.parseInt(patch, 10) || 0,
+	};
+}
+
+function compareNodeVersions(left: ParsedNodeVersion, right: ParsedNodeVersion): number {
+	if (left.major !== right.major) return left.major - right.major;
+	if (left.minor !== right.minor) return left.minor - right.minor;
+	return left.patch - right.patch;
+}
+
+export function isSupportedNodeVersion(version = process.versions.node): boolean {
+	return compareNodeVersions(parseNodeVersion(version), parseNodeVersion(MIN_NODE_VERSION)) >= 0;
+}
+
+export function getUnsupportedNodeVersionLines(version = process.versions.node): string[] {
+	const isWindows = process.platform === "win32";
+	return [
+		`feynman requires Node.js ${MIN_NODE_VERSION} or later (detected ${version}).`,
+		isWindows
+			? "Install a newer Node.js from https://nodejs.org, or use the standalone installer:"
+			: "Switch to Node 20 with `nvm install 20 && nvm use 20`, or use the standalone installer:",
+		isWindows
+			? "irm https://feynman.is/install.ps1 | iex"
+			: "curl -fsSL https://feynman.is/install | bash",
+	];
+}
+
+export function ensureSupportedNodeVersion(version = process.versions.node): void {
+	if (!isSupportedNodeVersion(version)) {
+		throw new Error(getUnsupportedNodeVersionLines(version).join("\n"));
+	}
+}

src/system/open-url.ts

@@ -0,0 +1,51 @@
+import { spawn } from "node:child_process";
+
+import { resolveExecutable } from "./executables.js";
+
+type ResolveExecutableFn = (name: string, fallbackPaths?: string[]) => string | undefined;
+
+type OpenUrlCommand = {
+	command: string;
+	args: string[];
+};
+
+export function getOpenUrlCommand(
+	url: string,
+	platform = process.platform,
+	resolveCommand: ResolveExecutableFn = resolveExecutable,
+): OpenUrlCommand | undefined {
+	if (platform === "win32") {
+		return {
+			command: "cmd",
+			args: ["/c", "start", "", url],
+		};
+	}
+
+	if (platform === "darwin") {
+		const command = resolveCommand("open");
+		return command ? { command, args: [url] } : undefined;
+	}
+
+	const command = resolveCommand("xdg-open");
+	return command ? { command, args: [url] } : undefined;
+}
+
+export function openUrl(url: string): boolean {
+	const command = getOpenUrlCommand(url);
+	if (!command) {
+		return false;
+	}
+
+	try {
+		const child = spawn(command.command, command.args, {
+			detached: true,
+			stdio: "ignore",
+			windowsHide: true,
+		});
+		child.on("error", () => {});
+		child.unref();
+		return true;
+	} catch {
+		return false;
+	}
+}

src/ui/terminal.ts

@@ -1,6 +1,6 @@
 import { FEYNMAN_ASCII_LOGO } from "../../logo.mjs";
 
-const RESET = "\x1b[0m";
+export const RESET = "\x1b[0m";
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
 
@@ -11,9 +11,9 @@ function rgb(red: number, green: number, blue: number): string {
 // Match the outer CLI to the bundled Feynman Pi theme instead of generic magenta panels.
 const INK = rgb(211, 198, 170);
 const STONE = rgb(157, 169, 160);
-const ASH = rgb(133, 146, 137);
+export const ASH = rgb(133, 146, 137);
 const DARK_ASH = rgb(92, 106, 114);
-const SAGE = rgb(167, 192, 128);
+export const SAGE = rgb(167, 192, 128);
 const TEAL = rgb(127, 187, 179);
 const ROSE = rgb(230, 126, 128);
 

tests/bootstrap-sync.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
@@ -49,3 +49,34 @@ test("syncBundledAssets preserves user-modified files and updates managed files"
 	assert.equal(readFileSync(join(agentDir, "themes", "feynman.json"), "utf8"), '{"theme":"v2"}\n');
 	assert.equal(readFileSync(join(agentDir, "agents", "researcher.md"), "utf8"), "# user-custom\n");
 });
+
+test("syncBundledAssets removes deleted managed files but preserves user-modified stale files", () => {
+	const appRoot = createAppRoot();
+	const home = mkdtempSync(join(tmpdir(), "feynman-home-"));
+	process.env.FEYNMAN_HOME = home;
+	const agentDir = join(home, "agent");
+	mkdirSync(agentDir, { recursive: true });
+
+	mkdirSync(join(appRoot, "skills", "paper-eli5"), { recursive: true });
+	writeFileSync(join(appRoot, "skills", "paper-eli5", "SKILL.md"), "# old skill\n", "utf8");
+	syncBundledAssets(appRoot, agentDir);
+
+	rmSync(join(appRoot, "skills", "paper-eli5"), { recursive: true, force: true });
+	mkdirSync(join(appRoot, "skills", "eli5"), { recursive: true });
+	writeFileSync(join(appRoot, "skills", "eli5", "SKILL.md"), "# new skill\n", "utf8");
+
+	const firstResult = syncBundledAssets(appRoot, agentDir);
+	assert.deepEqual(firstResult.copied, ["eli5/SKILL.md"]);
+	assert.equal(existsSync(join(agentDir, "skills", "paper-eli5", "SKILL.md")), false);
+	assert.equal(readFileSync(join(agentDir, "skills", "eli5", "SKILL.md"), "utf8"), "# new skill\n");
+
+	mkdirSync(join(appRoot, "skills", "legacy"), { recursive: true });
+	writeFileSync(join(appRoot, "skills", "legacy", "SKILL.md"), "# managed legacy\n", "utf8");
+	syncBundledAssets(appRoot, agentDir);
+	writeFileSync(join(agentDir, "skills", "legacy", "SKILL.md"), "# user legacy override\n", "utf8");
+	rmSync(join(appRoot, "skills", "legacy"), { recursive: true, force: true });
+
+	const secondResult = syncBundledAssets(appRoot, agentDir);
+	assert.deepEqual(secondResult.skipped, ["legacy/SKILL.md"]);
+	assert.equal(readFileSync(join(agentDir, "skills", "legacy", "SKILL.md"), "utf8"), "# user legacy override\n");
+});

tests/catalog-snapshot.test.ts

@@ -0,0 +1,110 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { buildModelStatusSnapshotFromRecords } from "../src/model/catalog.js";
+
+test("buildModelStatusSnapshotFromRecords returns empty guidance when model is set and valid", () => {
+	const snapshot = buildModelStatusSnapshotFromRecords(
+		[{ provider: "anthropic", id: "claude-opus-4-6" }],
+		[{ provider: "anthropic", id: "claude-opus-4-6" }],
+		"anthropic/claude-opus-4-6",
+	);
+
+	assert.equal(snapshot.currentValid, true);
+	assert.equal(snapshot.current, "anthropic/claude-opus-4-6");
+	assert.equal(snapshot.guidance.length, 0);
+});
+
+test("buildModelStatusSnapshotFromRecords emits guidance when no models are available", () => {
+	const snapshot = buildModelStatusSnapshotFromRecords([], [], undefined);
+
+	assert.equal(snapshot.currentValid, false);
+	assert.equal(snapshot.current, undefined);
+	assert.equal(snapshot.recommended, undefined);
+	assert.ok(snapshot.guidance.some((line) => line.includes("No authenticated Pi models")));
+});
+
+test("buildModelStatusSnapshotFromRecords emits guidance when no default model is set", () => {
+	const snapshot = buildModelStatusSnapshotFromRecords(
+		[{ provider: "openai", id: "gpt-5.4" }],
+		[{ provider: "openai", id: "gpt-5.4" }],
+		undefined,
+	);
+
+	assert.equal(snapshot.currentValid, false);
+	assert.equal(snapshot.current, undefined);
+	assert.ok(snapshot.guidance.some((line) => line.includes("No default research model")));
+});
+
+test("buildModelStatusSnapshotFromRecords marks provider as configured only when it has available models", () => {
+	const snapshot = buildModelStatusSnapshotFromRecords(
+		[
+			{ provider: "anthropic", id: "claude-opus-4-6" },
+			{ provider: "openai", id: "gpt-5.4" },
+		],
+		[{ provider: "openai", id: "gpt-5.4" }],
+		"openai/gpt-5.4",
+	);
+
+	const anthropicProvider = snapshot.providers.find((provider) => provider.id === "anthropic");
+	const openaiProvider = snapshot.providers.find((provider) => provider.id === "openai");
+
+	assert.ok(anthropicProvider);
+	assert.equal(anthropicProvider!.configured, false);
+	assert.equal(anthropicProvider!.supportedModels, 1);
+	assert.equal(anthropicProvider!.availableModels, 0);
+
+	assert.ok(openaiProvider);
+	assert.equal(openaiProvider!.configured, true);
+	assert.equal(openaiProvider!.supportedModels, 1);
+	assert.equal(openaiProvider!.availableModels, 1);
+});
+
+test("buildModelStatusSnapshotFromRecords marks provider as current when selected model belongs to it", () => {
+	const snapshot = buildModelStatusSnapshotFromRecords(
+		[
+			{ provider: "anthropic", id: "claude-opus-4-6" },
+			{ provider: "openai", id: "gpt-5.4" },
+		],
+		[
+			{ provider: "anthropic", id: "claude-opus-4-6" },
+			{ provider: "openai", id: "gpt-5.4" },
+		],
+		"anthropic/claude-opus-4-6",
+	);
+
+	const anthropicProvider = snapshot.providers.find((provider) => provider.id === "anthropic");
+	const openaiProvider = snapshot.providers.find((provider) => provider.id === "openai");
+
+	assert.equal(anthropicProvider!.current, true);
+	assert.equal(openaiProvider!.current, false);
+});
+
+test("buildModelStatusSnapshotFromRecords returns available models sorted by research preference", () => {
+	const snapshot = buildModelStatusSnapshotFromRecords(
+		[
+			{ provider: "openai", id: "gpt-5.4" },
+			{ provider: "anthropic", id: "claude-opus-4-6" },
+		],
+		[
+			{ provider: "openai", id: "gpt-5.4" },
+			{ provider: "anthropic", id: "claude-opus-4-6" },
+		],
+		undefined,
+	);
+
+	assert.equal(snapshot.availableModels[0], "anthropic/claude-opus-4-6");
+	assert.equal(snapshot.availableModels[1], "openai/gpt-5.4");
+	assert.equal(snapshot.recommended, "anthropic/claude-opus-4-6");
+});
+
+test("buildModelStatusSnapshotFromRecords sets currentValid false when current model is not in available list", () => {
+	const snapshot = buildModelStatusSnapshotFromRecords(
+		[{ provider: "anthropic", id: "claude-opus-4-6" }],
+		[],
+		"anthropic/claude-opus-4-6",
+	);
+
+	assert.equal(snapshot.currentValid, false);
+	assert.equal(snapshot.current, "anthropic/claude-opus-4-6");
+});

tests/config-paths.test.ts

@@ -0,0 +1,92 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import {
+	ensureFeynmanHome,
+	getBootstrapStatePath,
+	getDefaultSessionDir,
+	getFeynmanAgentDir,
+	getFeynmanHome,
+	getFeynmanMemoryDir,
+	getFeynmanStateDir,
+} from "../src/config/paths.js";
+
+test("getFeynmanHome uses FEYNMAN_HOME env var when set", () => {
+	const previous = process.env.FEYNMAN_HOME;
+	try {
+		process.env.FEYNMAN_HOME = "/custom/home";
+		assert.equal(getFeynmanHome(), resolve("/custom/home", ".feynman"));
+	} finally {
+		if (previous === undefined) {
+			delete process.env.FEYNMAN_HOME;
+		} else {
+			process.env.FEYNMAN_HOME = previous;
+		}
+	}
+});
+
+test("getFeynmanHome falls back to homedir when FEYNMAN_HOME is unset", () => {
+	const previous = process.env.FEYNMAN_HOME;
+	try {
+		delete process.env.FEYNMAN_HOME;
+		const home = getFeynmanHome();
+		assert.ok(home.endsWith(".feynman"), `expected path ending in .feynman, got: ${home}`);
+		assert.ok(!home.includes("undefined"), `expected no 'undefined' in path, got: ${home}`);
+	} finally {
+		if (previous === undefined) {
+			delete process.env.FEYNMAN_HOME;
+		} else {
+			process.env.FEYNMAN_HOME = previous;
+		}
+	}
+});
+
+test("getFeynmanAgentDir resolves to <home>/agent", () => {
+	assert.equal(getFeynmanAgentDir("/some/home"), resolve("/some/home", "agent"));
+});
+
+test("getFeynmanMemoryDir resolves to <home>/memory", () => {
+	assert.equal(getFeynmanMemoryDir("/some/home"), resolve("/some/home", "memory"));
+});
+
+test("getFeynmanStateDir resolves to <home>/.state", () => {
+	assert.equal(getFeynmanStateDir("/some/home"), resolve("/some/home", ".state"));
+});
+
+test("getDefaultSessionDir resolves to <home>/sessions", () => {
+	assert.equal(getDefaultSessionDir("/some/home"), resolve("/some/home", "sessions"));
+});
+
+test("getBootstrapStatePath resolves to <home>/.state/bootstrap.json", () => {
+	assert.equal(getBootstrapStatePath("/some/home"), resolve("/some/home", ".state", "bootstrap.json"));
+});
+
+test("ensureFeynmanHome creates all required subdirectories", () => {
+	const root = mkdtempSync(join(tmpdir(), "feynman-paths-"));
+	try {
+		const home = join(root, "home");
+		ensureFeynmanHome(home);
+
+		assert.ok(existsSync(home), "home dir should exist");
+		assert.ok(existsSync(join(home, "agent")), "agent dir should exist");
+		assert.ok(existsSync(join(home, "memory")), "memory dir should exist");
+		assert.ok(existsSync(join(home, ".state")), ".state dir should exist");
+		assert.ok(existsSync(join(home, "sessions")), "sessions dir should exist");
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("ensureFeynmanHome is idempotent when dirs already exist", () => {
+	const root = mkdtempSync(join(tmpdir(), "feynman-paths-"));
+	try {
+		const home = join(root, "home");
+		ensureFeynmanHome(home);
+		assert.doesNotThrow(() => ensureFeynmanHome(home));
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});

tests/content-policy.test.ts

@@ -0,0 +1,32 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const bannedPatterns = [/ValiChord/i, /Harmony Record/i, /harmony_record_/i];
+
+function collectMarkdownFiles(root: string): string[] {
+	const files: string[] = [];
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		const fullPath = join(root, entry.name);
+		if (entry.isDirectory()) {
+			files.push(...collectMarkdownFiles(fullPath));
+			continue;
+		}
+		if (entry.isFile() && fullPath.endsWith(".md")) {
+			files.push(fullPath);
+		}
+	}
+	return files;
+}
+
+test("bundled prompts and skills do not contain blocked promotional product content", () => {
+	for (const filePath of [...collectMarkdownFiles(join(repoRoot, "prompts")), ...collectMarkdownFiles(join(repoRoot, "skills"))]) {
+		const content = readFileSync(filePath, "utf8");
+		for (const pattern of bannedPatterns) {
+			assert.doesNotMatch(content, pattern, `${filePath} contains blocked promotional pattern ${pattern}`);
+		}
+	}
+});

tests/model-harness.test.ts

@@ -57,6 +57,16 @@ test("buildModelStatusSnapshotFromRecords flags an invalid current model and sug
 	assert.ok(snapshot.guidance.some((line) => line.includes("Configured default model is unavailable")));
 });
 
+test("chooseRecommendedModel prefers MiniMax M2.7 over highspeed when that is the authenticated provider", () => {
+	const authPath = createAuthPath({
+		minimax: { type: "api_key", key: "minimax-test-key" },
+	});
+
+	const recommendation = chooseRecommendedModel(authPath);
+
+	assert.equal(recommendation?.spec, "minimax/MiniMax-M2.7");
+});
+
 test("resolveInitialPrompt maps top-level research commands to Pi slash workflows", () => {
 	const workflows = new Set(["lit", "watch", "jobs", "deepresearch"]);
 	assert.equal(resolveInitialPrompt("lit", ["tool-using", "agents"], undefined, workflows), "/lit tool-using agents");
@@ -65,4 +75,3 @@ test("resolveInitialPrompt maps top-level research commands to Pi slash workflow
 	assert.equal(resolveInitialPrompt("chat", ["hello"], undefined, workflows), "hello");
 	assert.equal(resolveInitialPrompt("unknown", ["topic"], undefined, workflows), "unknown topic");
 });
-

tests/models-json.test.ts

@@ -0,0 +1,32 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { upsertProviderConfig } from "../src/model/models-json.js";
+
+test("upsertProviderConfig creates models.json and merges provider config", () => {
+	const dir = mkdtempSync(join(tmpdir(), "feynman-models-"));
+	const modelsPath = join(dir, "models.json");
+
+	const first = upsertProviderConfig(modelsPath, "custom", {
+		baseUrl: "http://localhost:11434/v1",
+		apiKey: "ollama",
+		api: "openai-completions",
+		authHeader: true,
+		models: [{ id: "llama3.1:8b" }],
+	});
+	assert.deepEqual(first, { ok: true });
+
+	const second = upsertProviderConfig(modelsPath, "custom", {
+		baseUrl: "http://localhost:9999/v1",
+	});
+	assert.deepEqual(second, { ok: true });
+
+	const parsed = JSON.parse(readFileSync(modelsPath, "utf8")) as any;
+	assert.equal(parsed.providers.custom.baseUrl, "http://localhost:9999/v1");
+	assert.equal(parsed.providers.custom.api, "openai-completions");
+	assert.equal(parsed.providers.custom.authHeader, true);
+	assert.deepEqual(parsed.providers.custom.models, [{ id: "llama3.1:8b" }]);
+});

tests/node-version.test.ts

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+	MIN_NODE_VERSION,
+	ensureSupportedNodeVersion,
+	getUnsupportedNodeVersionLines,
+	isSupportedNodeVersion,
+} from "../src/system/node-version.js";
+
+test("isSupportedNodeVersion enforces the exact minimum floor", () => {
+	assert.equal(isSupportedNodeVersion("20.19.0"), true);
+	assert.equal(isSupportedNodeVersion("20.19.0"), true);
+	assert.equal(isSupportedNodeVersion("21.0.0"), true);
+	assert.equal(isSupportedNodeVersion("20.18.1"), false);
+	assert.equal(isSupportedNodeVersion("18.17.0"), false);
+});
+
+test("ensureSupportedNodeVersion throws a guided upgrade message", () => {
+	assert.throws(
+		() => ensureSupportedNodeVersion("18.17.0"),
+		(error: unknown) =>
+			error instanceof Error &&
+			error.message.includes(`Node.js ${MIN_NODE_VERSION}`) &&
+			error.message.includes("nvm install 20 && nvm use 20") &&
+			error.message.includes("https://feynman.is/install"),
+	);
+});
+
+test("unsupported version guidance reports the detected version", () => {
+	const lines = getUnsupportedNodeVersionLines("18.17.0");
+
+	assert.equal(lines[0], "feynman requires Node.js 20.19.0 or later (detected 18.17.0).");
+	assert.ok(lines.some((line) => line.includes("curl -fsSL https://feynman.is/install | bash")));
+});

tests/open-url.test.ts

@@ -0,0 +1,45 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { getOpenUrlCommand } from "../src/system/open-url.js";
+
+test("getOpenUrlCommand uses open on macOS when available", () => {
+	const command = getOpenUrlCommand(
+		"https://example.com",
+		"darwin",
+		(name) => (name === "open" ? "/usr/bin/open" : undefined),
+	);
+
+	assert.deepEqual(command, {
+		command: "/usr/bin/open",
+		args: ["https://example.com"],
+	});
+});
+
+test("getOpenUrlCommand uses xdg-open on Linux when available", () => {
+	const command = getOpenUrlCommand(
+		"https://example.com",
+		"linux",
+		(name) => (name === "xdg-open" ? "/usr/bin/xdg-open" : undefined),
+	);
+
+	assert.deepEqual(command, {
+		command: "/usr/bin/xdg-open",
+		args: ["https://example.com"],
+	});
+});
+
+test("getOpenUrlCommand uses cmd start on Windows", () => {
+	const command = getOpenUrlCommand("https://example.com", "win32");
+
+	assert.deepEqual(command, {
+		command: "cmd",
+		args: ["/c", "start", "", "https://example.com"],
+	});
+});
+
+test("getOpenUrlCommand returns undefined when no opener is available", () => {
+	const command = getOpenUrlCommand("https://example.com", "linux", () => undefined);
+
+	assert.equal(command, undefined);
+});

tests/pi-extension-loader-patch.test.ts

@@ -0,0 +1,42 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { patchPiExtensionLoaderSource } from "../scripts/lib/pi-extension-loader-patch.mjs";
+
+test("patchPiExtensionLoaderSource rewrites Windows extension imports to file URLs", () => {
+	const input = [
+		'import * as path from "node:path";',
+		'import { fileURLToPath } from "node:url";',
+		"async function loadExtensionModule(extensionPath) {",
+		"    const jiti = createJiti(import.meta.url);",
+		'    const module = await jiti.import(extensionPath, { default: true });',
+		"    return module;",
+		"}",
+		"",
+	].join("\n");
+
+	const patched = patchPiExtensionLoaderSource(input);
+
+	assert.match(patched, /pathToFileURL/);
+	assert.match(patched, /process\.platform === "win32"/);
+	assert.match(patched, /path\.isAbsolute\(extensionPath\)/);
+	assert.match(patched, /jiti\.import\(extensionSpecifier, \{ default: true \}\)/);
+});
+
+test("patchPiExtensionLoaderSource is idempotent", () => {
+	const input = [
+		'import * as path from "node:path";',
+		'import { fileURLToPath } from "node:url";',
+		"async function loadExtensionModule(extensionPath) {",
+		"    const jiti = createJiti(import.meta.url);",
+		'    const module = await jiti.import(extensionPath, { default: true });',
+		"    return module;",
+		"}",
+		"",
+	].join("\n");
+
+	const once = patchPiExtensionLoaderSource(input);
+	const twice = patchPiExtensionLoaderSource(once);
+
+	assert.equal(twice, once);
+});

tests/pi-google-legacy-schema-patch.test.ts

@@ -0,0 +1,42 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { patchPiGoogleLegacySchemaSource } from "../scripts/lib/pi-google-legacy-schema-patch.mjs";
+
+test("patchPiGoogleLegacySchemaSource rewrites legacy parameters conversion to normalize const", () => {
+	const input = [
+		"export function convertTools(tools, useParameters = false) {",
+		"    if (tools.length === 0) return undefined;",
+		"    return [",
+		"        {",
+		"            functionDeclarations: tools.map((tool) => ({",
+		"                name: tool.name,",
+		"                description: tool.description,",
+		'                ...(useParameters ? { parameters: tool.parameters } : { parametersJsonSchema: tool.parameters }),',
+		"            })),",
+		"        },",
+		"    ];",
+		"}",
+		"",
+	].join("\n");
+
+	const patched = patchPiGoogleLegacySchemaSource(input);
+
+	assert.match(patched, /function normalizeLegacyToolSchema\(schema\)/);
+	assert.match(patched, /normalized\.enum = \[value\]/);
+	assert.match(patched, /parameters: normalizeLegacyToolSchema\(tool\.parameters\)/);
+});
+
+test("patchPiGoogleLegacySchemaSource is idempotent", () => {
+	const input = [
+		"export function convertTools(tools, useParameters = false) {",
+		'                ...(useParameters ? { parameters: tool.parameters } : { parametersJsonSchema: tool.parameters }),',
+		"}",
+		"",
+	].join("\n");
+
+	const once = patchPiGoogleLegacySchemaSource(input);
+	const twice = patchPiGoogleLegacySchemaSource(once);
+
+	assert.equal(twice, once);
+});

tests/pi-launch.test.ts

@@ -0,0 +1,9 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { exitCodeFromSignal } from "../src/pi/launch.js";
+
+test("exitCodeFromSignal maps POSIX signals to conventional shell exit codes", () => {
+	assert.equal(exitCodeFromSignal("SIGTERM"), 143);
+	assert.equal(exitCodeFromSignal("SIGSEGV"), 139);
+});

tests/pi-runtime.test.ts

@@ -1,7 +1,8 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { pathToFileURL } from "node:url";
 
-import { buildPiArgs, buildPiEnv, resolvePiPaths } from "../src/pi/runtime.js";
+import { applyFeynmanPackageManagerEnv, buildPiArgs, buildPiEnv, resolvePiPaths, toNodeImportSpecifier } from "../src/pi/runtime.js";
 
 test("buildPiArgs includes configured runtime paths and prompt", () => {
 	const args = buildPiArgs({
@@ -9,6 +10,7 @@ test("buildPiArgs includes configured runtime paths and prompt", () => {
 		workingDir: "/workspace",
 		sessionDir: "/sessions",
 		feynmanAgentDir: "/home/.feynman/agent",
+		mode: "rpc",
 		initialPrompt: "hello",
 		explicitModelSpec: "openai:gpt-5.4",
 		thinkingLevel: "medium",
@@ -21,6 +23,8 @@ test("buildPiArgs includes configured runtime paths and prompt", () => {
 		"/repo/feynman/extensions/research-tools.ts",
 		"--prompt-template",
 		"/repo/feynman/prompts",
+		"--mode",
+		"rpc",
 		"--model",
 		"openai:gpt-5.4",
 		"--thinking",
@@ -30,6 +34,11 @@ test("buildPiArgs includes configured runtime paths and prompt", () => {
 });
 
 test("buildPiEnv wires Feynman paths into the Pi environment", () => {
+	const previousUppercasePrefix = process.env.NPM_CONFIG_PREFIX;
+	const previousLowercasePrefix = process.env.npm_config_prefix;
+	process.env.NPM_CONFIG_PREFIX = "/tmp/global-prefix";
+	process.env.npm_config_prefix = "/tmp/global-prefix-lower";
+
 	const env = buildPiEnv({
 		appRoot: "/repo/feynman",
 		workingDir: "/workspace",
@@ -38,9 +47,62 @@ test("buildPiEnv wires Feynman paths into the Pi environment", () => {
 		feynmanVersion: "0.1.5",
 	});
 
-	assert.equal(env.FEYNMAN_SESSION_DIR, "/sessions");
-	assert.equal(env.FEYNMAN_BIN_PATH, "/repo/feynman/bin/feynman.js");
-	assert.equal(env.FEYNMAN_MEMORY_DIR, "/home/.feynman/memory");
+	try {
+		assert.equal(env.FEYNMAN_SESSION_DIR, "/sessions");
+		assert.equal(env.FEYNMAN_BIN_PATH, "/repo/feynman/bin/feynman.js");
+		assert.equal(env.FEYNMAN_MEMORY_DIR, "/home/.feynman/memory");
+		assert.equal(env.FEYNMAN_NPM_PREFIX, "/home/.feynman/npm-global");
+		assert.equal(env.NPM_CONFIG_PREFIX, "/home/.feynman/npm-global");
+		assert.equal(env.npm_config_prefix, "/home/.feynman/npm-global");
+		assert.equal(env.PI_CODING_AGENT_DIR, "/home/.feynman/agent");
+		assert.ok(
+			env.PATH?.startsWith(
+				"/repo/feynman/node_modules/.bin:/repo/feynman/.feynman/npm/node_modules/.bin:/home/.feynman/npm-global/bin:",
+			),
+		);
+	} finally {
+		if (previousUppercasePrefix === undefined) {
+			delete process.env.NPM_CONFIG_PREFIX;
+		} else {
+			process.env.NPM_CONFIG_PREFIX = previousUppercasePrefix;
+		}
+		if (previousLowercasePrefix === undefined) {
+			delete process.env.npm_config_prefix;
+		} else {
+			process.env.npm_config_prefix = previousLowercasePrefix;
+		}
+	}
+});
+
+test("applyFeynmanPackageManagerEnv pins npm globals to the Feynman prefix", () => {
+	const previousFeynmanPrefix = process.env.FEYNMAN_NPM_PREFIX;
+	const previousUppercasePrefix = process.env.NPM_CONFIG_PREFIX;
+	const previousLowercasePrefix = process.env.npm_config_prefix;
+
+	try {
+		const prefix = applyFeynmanPackageManagerEnv("/home/.feynman/agent");
+
+		assert.equal(prefix, "/home/.feynman/npm-global");
+		assert.equal(process.env.FEYNMAN_NPM_PREFIX, "/home/.feynman/npm-global");
+		assert.equal(process.env.NPM_CONFIG_PREFIX, "/home/.feynman/npm-global");
+		assert.equal(process.env.npm_config_prefix, "/home/.feynman/npm-global");
+	} finally {
+		if (previousFeynmanPrefix === undefined) {
+			delete process.env.FEYNMAN_NPM_PREFIX;
+		} else {
+			process.env.FEYNMAN_NPM_PREFIX = previousFeynmanPrefix;
+		}
+		if (previousUppercasePrefix === undefined) {
+			delete process.env.NPM_CONFIG_PREFIX;
+		} else {
+			process.env.NPM_CONFIG_PREFIX = previousUppercasePrefix;
+		}
+		if (previousLowercasePrefix === undefined) {
+			delete process.env.npm_config_prefix;
+		} else {
+			process.env.npm_config_prefix = previousLowercasePrefix;
+		}
+	}
 });
 
 test("resolvePiPaths includes the Promise.withResolvers polyfill path", () => {
@@ -48,3 +110,11 @@ test("resolvePiPaths includes the Promise.withResolvers polyfill path", () => {
 
 	assert.equal(paths.promisePolyfillPath, "/repo/feynman/dist/system/promise-polyfill.js");
 });
+
+test("toNodeImportSpecifier converts absolute preload paths to file URLs", () => {
+	assert.equal(
+		toNodeImportSpecifier("/repo/feynman/dist/system/promise-polyfill.js"),
+		pathToFileURL("/repo/feynman/dist/system/promise-polyfill.js").href,
+	);
+	assert.equal(toNodeImportSpecifier("tsx"), "tsx");
+});

tests/pi-subagents-patch.test.ts

@@ -0,0 +1,104 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { patchPiSubagentsSource } from "../scripts/lib/pi-subagents-patch.mjs";
+
+const CASES = [
+	{
+		name: "index.ts config path",
+		file: "index.ts",
+		input: [
+			'import * as os from "node:os";',
+			'import * as path from "node:path";',
+			'const configPath = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent", "config.json");',
+			"",
+		].join("\n"),
+		original: 'const configPath = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent", "config.json");',
+		expected: 'const configPath = path.join(resolvePiAgentDir(), "extensions", "subagent", "config.json");',
+	},
+	{
+		name: "agents.ts user agents dir",
+		file: "agents.ts",
+		input: [
+			'import * as os from "node:os";',
+			'import * as path from "node:path";',
+			'const userDir = path.join(os.homedir(), ".pi", "agent", "agents");',
+			"",
+		].join("\n"),
+		original: 'const userDir = path.join(os.homedir(), ".pi", "agent", "agents");',
+		expected: 'const userDir = path.join(resolvePiAgentDir(), "agents");',
+	},
+	{
+		name: "artifacts.ts sessions dir",
+		file: "artifacts.ts",
+		input: [
+			'import * as os from "node:os";',
+			'import * as path from "node:path";',
+			'const sessionsBase = path.join(os.homedir(), ".pi", "agent", "sessions");',
+			"",
+		].join("\n"),
+		original: 'const sessionsBase = path.join(os.homedir(), ".pi", "agent", "sessions");',
+		expected: 'const sessionsBase = path.join(resolvePiAgentDir(), "sessions");',
+	},
+	{
+		name: "run-history.ts history file",
+		file: "run-history.ts",
+		input: [
+			'import * as os from "node:os";',
+			'import * as path from "node:path";',
+			'const HISTORY_PATH = path.join(os.homedir(), ".pi", "agent", "run-history.jsonl");',
+			"",
+		].join("\n"),
+		original: 'const HISTORY_PATH = path.join(os.homedir(), ".pi", "agent", "run-history.jsonl");',
+		expected: 'const HISTORY_PATH = path.join(resolvePiAgentDir(), "run-history.jsonl");',
+	},
+	{
+		name: "skills.ts agent dir",
+		file: "skills.ts",
+		input: [
+			'import * as os from "node:os";',
+			'import * as path from "node:path";',
+			'const AGENT_DIR = path.join(os.homedir(), ".pi", "agent");',
+			"",
+		].join("\n"),
+		original: 'const AGENT_DIR = path.join(os.homedir(), ".pi", "agent");',
+		expected: "const AGENT_DIR = resolvePiAgentDir();",
+	},
+	{
+		name: "chain-clarify.ts chain save dir",
+		file: "chain-clarify.ts",
+		input: [
+			'import * as os from "node:os";',
+			'import * as path from "node:path";',
+			'const dir = path.join(os.homedir(), ".pi", "agent", "agents");',
+			"",
+		].join("\n"),
+		original: 'const dir = path.join(os.homedir(), ".pi", "agent", "agents");',
+		expected: 'const dir = path.join(resolvePiAgentDir(), "agents");',
+	},
+];
+
+for (const scenario of CASES) {
+	test(`patchPiSubagentsSource rewrites ${scenario.name}`, () => {
+		const patched = patchPiSubagentsSource(scenario.file, scenario.input);
+
+		assert.match(patched, /function resolvePiAgentDir\(\): string \{/);
+		assert.match(patched, /process\.env\.PI_CODING_AGENT_DIR\?\.trim\(\)/);
+		assert.ok(patched.includes(scenario.expected));
+		assert.ok(!patched.includes(scenario.original));
+	});
+}
+
+test("patchPiSubagentsSource is idempotent", () => {
+	const input = [
+		'import * as os from "node:os";',
+		'import * as path from "node:path";',
+		'const configPath = path.join(os.homedir(), ".pi", "agent", "extensions", "subagent", "config.json");',
+		"",
+	].join("\n");
+
+	const once = patchPiSubagentsSource("index.ts", input);
+	const twice = patchPiSubagentsSource("index.ts", once);
+
+	assert.equal(twice, once);
+});