Fix extension repair and add Opus 4.7 overlay

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,6 +6,20 @@ 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=

.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-research skill 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.
@@ -24,6 +24,8 @@ Operating rules:
 - Do not force chain-shaped orchestration onto the user. Multi-agent decomposition is an internal tactic, not the primary UX.
 - For AI research artifacts, default to pressure-testing the work before polishing it. Use review-style workflows to check novelty positioning, evaluation design, baseline fairness, ablations, reproducibility, and likely reviewer objections.
 - Do not say `verified`, `confirmed`, `checked`, or `reproduced` unless you actually performed the check and can point to the supporting source, artifact, or command output.
+- Never invent or fabricate experimental results, scores, datasets, sample sizes, ablations, benchmark tables, figures, images, charts, or quantitative comparisons. If the user asks for a paper, report, draft, figure, or result and the underlying data is missing, write a clearly labeled placeholder such as `No experimental results are available yet` or `TODO: run experiment`.
+- Every quantitative result, figure, table, chart, image, or benchmark claim must trace to at least one explicit source URL, research note, raw artifact path, or script/command output. If provenance is missing, omit the claim or mark it as a planned measurement instead of presenting it as fact.
 - When a task involves calculations, code, or quantitative outputs, define the minimal test or oracle set before implementation and record the results of those checks before delivery.
 - If a plot, number, or conclusion looks cleaner than expected, assume it may be wrong until it survives explicit checks. Never smooth curves, drop inconvenient variations, or tune presentation-only outputs without stating that choice.
 - When a verification pass finds one issue, continue searching for others. Do not stop after the first error unless the whole branch is blocked.

.feynman/agents/verifier.md

@@ -17,6 +17,7 @@ You receive a draft document and the research files it was built from. Your job
 4. **Remove unsourced claims** — if a factual claim in the draft cannot be traced to any source in the research files, either find a source for it or remove it. Do not leave unsourced factual claims.
 5. **Verify meaning, not just topic overlap.** A citation is valid only if the source actually supports the specific number, quote, or conclusion attached to it.
 6. **Refuse fake certainty.** Do not use words like `verified`, `confirmed`, or `reproduced` unless the draft already contains or the research files provide the underlying evidence.
+7. **Enforce the system prompt's provenance rule.** Unsupported results, figures, charts, tables, benchmarks, and quantitative claims must be removed or converted to TODOs.
 
 ## Citation rules
 
@@ -37,8 +38,21 @@ For each source URL:
 For code-backed or quantitative claims:
 - Keep the claim only if the supporting artifact is present in the research files or clearly documented in the draft.
 - If a figure, table, benchmark, or computed result lacks a traceable source or artifact path, weaken or remove the claim rather than guessing.
+- Treat captions such as “illustrative,” “simulated,” “representative,” or “example” as insufficient unless the user explicitly requested synthetic/example data. Otherwise remove the visual and mark the missing experiment.
 - Do not preserve polished summaries that outrun the raw evidence.
 
+## Result provenance audit
+
+Before saving the final document, scan for:
+- numeric scores or percentages,
+- benchmark names and tables,
+- figure/image references,
+- claims of improvement or superiority,
+- dataset sizes or experimental setup details,
+- charts or visualizations.
+
+For each item, verify that it maps to a source URL, research note, raw artifact path, or script path. If not, remove it or replace it with a TODO. Add a short `Removed Unsupported Claims` section only when you remove material.
+
 ## Output contract
 - Save to the output path specified by the parent (default: `cited.md`).
 - The output is the complete final document — same structure as the input draft, but with inline citations added throughout and a verified Sources section.

.feynman/agents/writer.md

@@ -15,6 +15,7 @@ You are Feynman's writing subagent.
 3. **Be explicit about gaps.** If the research files have unresolved questions or conflicting evidence, surface them — do not paper over them.
 4. **Do not promote draft text into fact.** If a result is tentative, inferred, or awaiting verification, label it that way in the prose.
 5. **No aesthetic laundering.** Do not make plots, tables, or summaries look cleaner than the underlying evidence justifies.
+6. **Follow the system prompt's provenance rule.** Missing results become gaps or TODOs, never plausible-looking data.
 
 ## Output structure
 
@@ -36,9 +37,10 @@ Unresolved issues, disagreements between sources, gaps in evidence.
 
 ## Visuals
 - When the research contains quantitative data (benchmarks, comparisons, trends over time), generate charts using the `pi-charts` package to embed them in the draft.
-- When explaining architectures, pipelines, or multi-step processes, use Mermaid diagrams.
-- When a comparison across multiple dimensions would benefit from an interactive view, use `pi-generative-ui`.
-- Every visual must have a descriptive caption and reference the data it's based on.
+- Do not create charts from invented or example data. If values are missing, describe the planned measurement instead.
+- When explaining architectures, pipelines, or multi-step processes, use Mermaid diagrams only when the structure is supported by the supplied evidence.
+- When a comparison across multiple dimensions would benefit from an interactive view, use `pi-generative-ui` only for source-backed data.
+- Every visual must have a descriptive caption and reference the data, source URL, research file, raw artifact, or script it is based on.
 - Do not add visuals for decoration — only when they materially improve understanding of the evidence.
 
 ## Operating rules
@@ -48,6 +50,7 @@ Unresolved issues, disagreements between sources, gaps in evidence.
 - Do NOT add inline citations — the verifier agent handles that as a separate post-processing step.
 - Do NOT add a Sources section — the verifier agent builds that.
 - Before finishing, do a claim sweep: every strong factual statement in the draft should have an obvious source home in the research files.
+- Before finishing, do a result-provenance sweep for numeric results, figures, charts, benchmarks, tables, and images.
 
 ## Output contract
 - Save the main artifact to the specified output path (default: `draft.md`).

.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

@@ -10,66 +10,89 @@ on:
 
 jobs:
   version-check:
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
     outputs:
       version: ${{ steps.version.outputs.version }}
-      should_publish: ${{ steps.version.outputs.should_publish }}
+      should_release: ${{ steps.version.outputs.should_release }}
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
-          node-version: 24.14.0
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
       - 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"
+          PUBLISHED=$(npm view @companion-ai/feynman version 2>/dev/null || true)
+          if [ "$PUBLISHED" = "$LOCAL" ] || 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_release=true" >> "$GITHUB_OUTPUT"
           fi
 
-  publish-npm:
+  verify:
     needs: version-check
-    if: needs.version-check.outputs.should_publish == 'true'
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    if: needs.version-check.outputs.should_release == 'true'
+    runs-on: ubuntu-latest
     permissions:
       contents: read
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
-          node-version: 24.14.0
-          registry-url: https://registry.npmjs.org
-      - run: npm ci --ignore-scripts
-      - run: npm run build
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
       - run: npm test
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: npm pack
+
+  publish-npm:
+    needs:
+      - version-check
+      - verify
+    if: needs.version-check.outputs.should_release == 'true' && needs.verify.result == 'success'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+      - run: npm publish --provenance --access public
 
   build-native-bundles:
     needs: version-check
+    if: needs.version-check.outputs.should_release == 'true'
     strategy:
       fail-fast: false
       matrix:
         include:
           - id: linux-x64
-            os: blacksmith-4vcpu-ubuntu-2404
+            os: ubuntu-latest
           - id: darwin-x64
             os: macos-15-intel
           - id: darwin-arm64
             os: macos-14
           - id: win32-x64
-            os: blacksmith-4vcpu-windows-2025
+            os: windows-latest
     runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v6
-      - uses: actions/setup-node@v5
+      - uses: actions/setup-node@v6
         with:
-          node-version: 24.14.0
+          node-version: 24
       - run: npm ci --ignore-scripts
       - run: npm run build
       - run: npm run build:native-bundle
@@ -97,53 +120,13 @@ jobs:
           name: native-${{ matrix.id }}
           path: dist/release/*
 
-  release-edge:
-    needs:
-      - version-check
-      - build-native-bundles
-    if: needs.build-native-bundles.result == 'success'
-    runs-on: blacksmith-4vcpu-ubuntu-2404
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          path: release-assets
-          merge-multiple: true
-      - shell: bash
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          VERSION: ${{ needs.version-check.outputs.version }}
-        run: |
-          NOTES="Rolling Feynman bundles from main for the curl/PowerShell installer."
-          if gh release view edge >/dev/null 2>&1; then
-            gh release view edge --json assets --jq '.assets[].name' | while IFS= read -r asset; do
-              [ -n "$asset" ] || continue
-              gh release delete-asset edge "$asset" --yes
-            done
-            gh release upload edge release-assets/*
-            gh release edit edge \
-              --title "edge" \
-              --notes "$NOTES" \
-              --prerelease \
-              --draft=false \
-              --target "$GITHUB_SHA"
-          else
-            gh release create edge release-assets/* \
-              --title "edge" \
-              --notes "$NOTES" \
-              --prerelease \
-              --latest=false \
-              --target "$GITHUB_SHA"
-          fi
-
   release-github:
     needs:
       - version-check
       - publish-npm
       - build-native-bundles
-    if: needs.version-check.outputs.should_publish == 'true' && needs.build-native-bundles.result == 'success' && needs.publish-npm.result == 'success'
-    runs-on: blacksmith-4vcpu-ubuntu-2404
+    if: needs.version-check.outputs.should_release == 'true' && needs.publish-npm.result == 'success' && needs.build-native-bundles.result == 'success'
+    runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
@@ -151,8 +134,10 @@ jobs:
         with:
           path: release-assets
           merge-multiple: true
-      - shell: bash
+      - name: Create GitHub release
+        shell: bash
         env:
+          GH_REPO: ${{ github.repository }}
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           VERSION: ${{ needs.version-check.outputs.version }}
         run: |
@@ -162,7 +147,7 @@ jobs:
               --title "v$VERSION" \
               --notes "Standalone Feynman bundles for native installation." \
               --draft=false \
-              --target "$GITHUB_SHA"
+              --latest
           else
             gh release create "v$VERSION" release-assets/* \
               --title "v$VERSION" \

.nvmrc

@@ -0,0 +1 @@
+22

CHANGELOG.md

@@ -14,3 +14,301 @@ Use this file to track chronology, not release notes. Keep entries short, factua
 - Failed / learned: ...
 - Blockers: ...
 - Next: ...
+
+### 2026-04-12 00:00 local — capital-france
+
+- Objective: Run an unattended deep-research workflow for the question "What is the capital of France?"
+- Changed: Created plan artifact at `outputs/.plans/capital-france.md`; scoped the workflow as a narrow fact-verification run with direct lead-agent evidence gathering instead of researcher subagents.
+- Verified: Read existing `CHANGELOG.md` and recalled prior saved plan memory for `capital-france` before finalizing the new run plan.
+- Failed / learned: None yet.
+- Blockers: Need at least two current independent authoritative sources and a quick ambiguity check before drafting.
+- Next: Collect current official/public sources, resolve any legal nuance, then draft and verify the brief.
+
+### 2026-04-12 00:20 local — capital-france
+
+- Objective: Complete evidence gathering and ambiguity check for the capital-of-France workflow.
+- Changed: Wrote `notes/capital-france-research-web.md` and `notes/capital-france-legal-context.md`; identified Insee (2024) and a Sénat report as the two main corroborating sources.
+- Verified: Cross-read current public French sources that explicitly describe Paris as the capital/capital city of France; found no current contradiction.
+- Failed / learned: The Presidency homepage was useful contextual support but not explicit enough to carry the core claim alone.
+- Blockers: Need citation pass and final review pass before promotion.
+- Next: Draft the brief, then run verifier and reviewer passes.
+
+### 2026-04-12 00:35 local — capital-france
+
+- Objective: Move from gathered evidence to a citable draft.
+- Changed: Wrote `outputs/.drafts/capital-france-draft.md` and updated the plan ledger to mark drafting complete.
+- Verified: Kept the core claim narrowly scoped to what the Insee and Sénat sources explicitly support; treated the Élysée page as contextual only.
+- Failed / learned: None.
+- Blockers: Need verifier URL/citation pass and reviewer verification pass before final promotion.
+- Next: Run verifier on the draft, then review and promote the final brief.
+
+### 2026-04-12 00:50 local — capital-france
+
+- Objective: Complete citation, verification, and final promotion for the capital-of-France workflow.
+- Changed: Produced `outputs/capital-france-brief.md`, ran verification into `notes/capital-france-verification.md`, promoted the final brief to `outputs/capital-france.md`, and wrote `outputs/capital-france.provenance.md`.
+- Verified: Reviewer found no FATAL or MAJOR issues. Core claim remains backed by two independent French public-institution sources, with Insee as the primary explicit source and the Sénat report as corroboration.
+- Failed / learned: The runtime did not expose a named `verifier` subagent, so I used an available worker in a verifier-equivalent role and recorded that deviation in the plan.
+- Blockers: None.
+- Next: If needed, extend the brief with deeper legal-historical sourcing, but the narrow factual question is sufficiently answered.
+
+### 2026-04-12 10:05 local — capital-france
+
+- Objective: Run the citation-verification pass on the capital-of-France draft and promote a final cited brief.
+- Changed: Verified the three draft source URLs were live (HTTP 200 at check time), added numbered inline citations, downgraded unsupported phrasing around the Élysée/context and broad ambiguity claims, and wrote `outputs/capital-france-brief.md`.
+- Verified: Confirmed Insee explicitly says Paris is the capital of France; confirmed the Sénat report describes Paris’s capital status and the presence of national institutions; confirmed the Élysée homepage is contextual only and not explicit enough to carry the core claim.
+- Failed / learned: The draft wording about the Presidency being seated in Paris was not directly supported by the cited homepage, so it was removed rather than carried forward.
+- Blockers: Reviewer pass still pending if the workflow requires an adversarial final check.
+- Next: If needed, run a final reviewer pass; otherwise use `outputs/capital-france-brief.md` as the canonical brief.
+
+### 2026-04-12 10:20 local — capital-france
+
+- Objective: Close the workflow with final review, final artifact promotion, and provenance.
+- Changed: Ran a reviewer pass recorded in `notes/capital-france-verification.md`; promoted the cited brief into `outputs/capital-france.md`; wrote `outputs/capital-france.provenance.md`; updated the run plan to mark all tasks complete.
+- Verified: Reviewer verdict was PASS WITH MINOR REVISIONS only; those minor wording fixes were applied before delivery.
+- Failed / learned: The runtime did not expose a project-named `verifier` agent, so the citation pass used an available worker agent as a verifier-equivalent step.
+- Blockers: None.
+- Next: Optional only — produce a legal memorandum on the basis of Paris's capital status if requested.
+
+### 2026-04-14 12:00 local — capital-belgium
+
+- Objective: Run a deep-research workflow for the question "What is the capital of Belgium?"
+- Changed: Created plan artifact at `outputs/.plans/capital-belgium.md`; gathered evidence into `notes/capital-belgium-research-web.md` from Belgium.be, FPS Foreign Affairs, Britannica, and a Belgian Senate constitution check.
+- Verified: Found two explicit current Belgian government statements that Brussels is the federal capital of Belgium, plus independent Britannica corroboration; no conflicting nuance surfaced in the consulted legal text.
+- Failed / learned: This is narrow enough that researcher subagents would add overhead without increasing evidence quality.
+- Blockers: Need draft, citation/URL verification pass, final review pass, and promotion.
+- Next: Draft the brief, run verifier-equivalent and reviewer passes, then promote final output with provenance.
+
+### 2026-04-14 12:25 local — capital-belgium
+
+- Objective: Complete citation, verification, and final promotion for the capital-of-Belgium workflow.
+- Changed: Wrote `outputs/.drafts/capital-belgium-draft.md`; produced cited brief `outputs/capital-belgium-brief.md`; ran verification into `notes/capital-belgium-verification.md`; promoted final output to `outputs/capital-belgium.md`; wrote `outputs/capital-belgium.provenance.md`; updated the plan ledger and verification log.
+- Verified: Core claim is now backed by Belgium.be, Belgian Foreign Affairs, Britannica, and direct constitutional text from Senate-hosted Article 194 stating that Brussels is the capital of Belgium and the seat of the federal government.
+- Failed / learned: The runtime did not expose a named `verifier` subagent, so a worker performed a verifier-equivalent citation/URL check; reviewer surfaced a stronger constitutional source than the first draft had emphasized.
+- Blockers: None.
+- Next: Optional only — if requested, expand this into a legal-historical note on Brussels’s capital status and the distinction between city, region, and federal institutions.
+
+### 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.
+
+### 2026-04-12 09:32 PDT — pi-0.66.1-upgrade-pass
+
+- Objective: Update Feynman from Pi `0.64.0` to the current `0.66.1` packages and absorb any downstream SDK/runtime compatibility changes instead of leaving the repo pinned behind upstream.
+- Changed: Bumped `@mariozechner/pi-ai` and `@mariozechner/pi-coding-agent` to `0.66.1` plus `@companion-ai/alpha-hub` to `0.1.3` in `package.json` and `package-lock.json`; updated `extensions/research-tools.ts` to stop listening for the removed `session_switch` extension event and rely on `session_start`, which now carries startup/reload/new/resume/fork reasons in Pi `0.66.x`.
+- Verified: Ran `npm test`, `npm run typecheck`, and `npm run build` successfully after the upgrade; smoke-ran `node bin/feynman.js --version`, `node bin/feynman.js doctor`, and `node bin/feynman.js status` successfully; checked upstream package diffs and confirmed the breaking change that affected this repo was the typed extension lifecycle change in `pi-coding-agent`, while `pi-ai` mainly brought refreshed provider/model catalog code including Bedrock/OpenAI provider updates and new generated model entries.
+- Failed / learned: `ctx7` resolved Pi correctly to `/badlogic/pi-mono`, but its docs snapshot was not release-note oriented; the concrete downstream-impact analysis came from the actual `0.64.0` → `0.66.1` package diffs and local validation, not from prose docs alone.
+- Failed / learned: The first post-upgrade CLI smoke test failed before Feynman startup because `@companion-ai/alpha-hub@0.1.2` shipped a zero-byte `src/lib/auth.js`; bumping to `0.1.3` fixed that adjacent runtime blocker.
+- Blockers: `npm install` reports two high-severity vulnerabilities remain in the dependency tree; this pass focused on the Pi upgrade and did not remediate unrelated audit findings.
+- Next: Push the Pi upgrade, then decide whether to layer the pending model-command fixes on top of this branch or land them separately to keep the dependency bump easy to review.
+
+### 2026-04-12 13:00 PDT — model-command-and-bedrock-fix-pass
+
+- Objective: Finish the remaining user-facing model-management regressions instead of stopping at the Pi dependency bump.
+- Changed: Updated `src/model/commands.ts` so `feynman model login <provider>` resolves both OAuth and API-key providers; `feynman model logout <provider>` clears either auth mode; `feynman model set` accepts both `provider/model` and `provider:model`; ambiguous bare model IDs now prefer explicitly configured providers from auth storage; added an `amazon-bedrock` setup path that validates the AWS credential chain with the AWS SDK and stores Pi's `<authenticated>` sentinel so Bedrock models appear in `model list`; synced `src/cli.ts`, `metadata/commands.mjs`, `README.md`, and the website docs to the new behavior.
+- Verified: Added regression tests in `tests/model-harness.test.ts` for `provider:model`, API-key provider resolution, and ambiguous bare-ID handling; ran `npm test`, `npm run typecheck`, `npm run build`, and `cd website && npm run build`; exercised command-level flows against throwaway `FEYNMAN_HOME` directories: interactive `node bin/feynman.js model login google`, `node bin/feynman.js model set google:gemini-3-pro-preview`, `node bin/feynman.js model set gpt-5.4` with only OpenAI configured, and `node bin/feynman.js model login amazon-bedrock`; confirmed `model list` shows Bedrock models after the new setup path; ran a live one-shot prompt `node bin/feynman.js --prompt "Reply with exactly OK"` and got `OK`.
+- Failed / learned: The website build still emits duplicate-id warnings for a handful of docs pages, but it completes successfully; those warnings predate this pass and were not introduced by the model-command edits.
+- Blockers: The Bedrock path is verified with the current shell's AWS credential chain, not with a fresh machine lacking AWS config; broader upstream Pi behavior around IMDS/default-profile autodiscovery without the sentinel is still outside this repo.
+- Next: Commit and push the combined Pi/model/docs maintenance branch, then decide whether to tackle the deeper search/deepresearch hang issues separately or leave them for focused repro work.
+
+### 2026-04-12 13:35 PDT — workflow-unattended-and-search-curator-fix-pass
+
+- Objective: Fix the remaining workflow deadlocks instead of leaving `deepresearch` and terminal web search half-functional after the maintenance push.
+- Changed: Updated the built-in research workflow prompts (`deepresearch`, `lit`, `review`, `audit`, `compare`, `draft`, `watch`) so they present the plan and continue automatically rather than blocking for approval; extended the `pi-web-access` runtime patch so Feynman rewrites its default workflow from browser-based `summary-review` to `none`; added explicit `workflow: "none"` persistence in `src/search/commands.ts` and `src/pi/web-access.ts`, plus surfaced the workflow in doctor/status-style output.
+- Verified: Reproduced the original `deepresearch` failure mode in print mode, where the run created `outputs/.plans/capital-france.md` and then stopped waiting for user confirmation; after the prompt changes, reran `deepresearch "What is the capital of France?"` and confirmed it progressed beyond planning and produced `outputs/.drafts/capital-france-draft.md`; inspected `pi-web-access@0.10.6` and confirmed the exact `waiting for summary approval...` string and `summary-review` default live in that package; added regression tests for the new `pi-web-access` patch and workflow-none status handling; reran `npm test`, `npm run typecheck`, and `npm run build`; smoke-tested `feynman search set exa exa_test_key` under a throwaway `FEYNMAN_HOME` and confirmed it writes `"workflow": "none"` to `web-search.json`.
+- Failed / learned: The long-running deepresearch session still spends substantial time in later reasoning/writing steps for even a narrow query, but the plan-confirmation deadlock itself is resolved; the remaining slowness is model/workflow behavior, not the original stop-after-plan bug.
+- Blockers: I did not install and execute the full optional `pi-session-search` package locally, so the terminal `summary approval` fix is validated by source inspection plus the Feynman patch path and config persistence rather than a local end-to-end package install.
+- Next: Commit and push the workflow/search fix pass, then close or answer the remaining deepresearch/search issues with the specific root causes and shipped fixes.
+
+### 2026-04-12 14:05 PDT — final-artifact-hardening-pass
+
+- Objective: Reduce the chance of unattended research workflows stopping at intermediate artifacts like `<slug>-brief.md` without promoting the final deliverable and provenance sidecar.
+- Changed: Tightened `prompts/deepresearch.md` so the agent must verify on disk that the plan, draft, cited brief, promoted final output, and provenance sidecar all exist before stopping; tightened `prompts/lit.md` so it explicitly checks for the final output plus provenance sidecar instead of stopping at an intermediate cited draft.
+- Verified: Cross-read the current deepresearch/lit deliver steps after the earlier unattended-run reproductions and confirmed the missing enforcement point was the final on-disk artifact check, not the naming convention itself.
+- Failed / learned: This is still prompt-level enforcement rather than a deterministic post-processing hook, so it improves completion reliability but does not provide the same guarantees as a dedicated artifact-finalization wrapper.
+- Blockers: I did not rerun a full broad deepresearch workflow end-to-end after this prompt-only hardening because those runs are materially longer and more expensive than the narrow reproductions already used to isolate the earlier deadlocks.
+- Next: Commit and push the prompt hardening, then, if needed, add a deterministic wrapper around final artifact promotion instead of relying only on prompt adherence.
+
+### 2026-04-14 09:30 PDT — wsl-login-and-uninstall-docs-pass
+
+- Objective: Fix the remaining WSL setup blocker and close the last actionable support issue instead of leaving the tracker open after the earlier workflow/model fixes.
+- Changed: Added a dedicated alpha-hub auth patch helper and tests; extended the alphaXiv login patch so WSL uses `wslview` when available and falls back to `cmd.exe /c start`, while also printing the auth URL explicitly for manual copy/paste if browser launch still fails; documented standalone uninstall steps in `README.md` and `website/src/content/docs/getting-started/installation.md`.
+- Verified: Added regression tests for the alpha-hub auth patch, reran `npm test`, `npm run typecheck`, and `npm run build`, and smoke-checked the patched alpha-hub source rewrite to confirm it injects both the WSL browser path and the explicit auth URL logging.
+- Failed / learned: This repo can patch alpha-hub's login UX reliably, but it still does not ship a destructive `feynman uninstall` command; the practical fix for the support issue is documented uninstall steps rather than a rushed cross-platform remover.
+- Blockers: I did not run a true WSL shell here, so the WSL fix is validated by the deterministic source patch plus tests rather than an actual Windows-hosted browser-launch repro.
+- Next: Push the WSL/login pass and close the stale issues and PRs that are already superseded by `main`.
+
+### 2026-04-14 09:35 PDT — review-findings-and-audit-cleanup
+
+- Objective: Fix the remaining concrete issues found in the deeper review pass instead of stopping at tracker cleanup.
+- Changed: Updated the `pi-web-access` patch so Feynman defaults search workflow to `none` without disabling explicit `summary-review`; softened the research workflow prompts so only unattended/one-shot runs auto-continue while interactive users still get a chance to request plan changes; corrected uninstall docs to mention `~/.ahub` alongside `~/.feynman`; bumped the root `basic-ftp` override from `5.2.1` to `5.2.2`.
+- Verified: Ran `npm test`, `npm run typecheck`, `npm run build`, `cd website && npm run build`, and `npm audit`; root audit is now clean.
+- Failed / learned: Astro still emits a duplicate-content-id warning for `website/src/content/docs/getting-started/installation.md`, but the website build succeeds and I did not identify a low-risk repo-side fix for that warning in this pass.
+- Blockers: The duplicate-id warning remains as a build warning only, not a failing correctness gate.
+- Next: If desired, isolate the Astro duplicate-id warning separately with a minimal reproduction rather than mixing it into runtime/CLI maintenance.
+
+### 2026-04-14 10:55 PDT — summarize-workflow-restore
+
+- Objective: Restore the useful summarization workflow that had been closed in PR `#69` without being merged.
+- Changed: Added `prompts/summarize.md` as a top-level CLI workflow so `feynman summarize <source>` is available again; kept the RLM-based tiering approach from the original proposal and aligned Tier 3 confirmation behavior with the repo's unattended-run conventions.
+- Verified: Confirmed `feynman summarize <source>` appears in CLI help; ran `node bin/feynman.js summarize /tmp/feynman-summary-smoke.txt` against a local smoke file and verified it produced `outputs/feynman-summary-smoke-summary.md` plus the raw fetched note artifact under `outputs/.notes/`.
+- Failed / learned: None in the restored Tier 1 path; broader Tier 2/Tier 3 behavior still depends on runtime/model/tool availability, just like the other prompt-driven workflows.
+- Blockers: None for the prompt restoration itself.
+- Next: If desired, add dedicated docs for `summarize` and decide whether to reopen PR `#69` for historical continuity or leave it closed as superseded by the landed equivalent on `main`.
+
+### 2026-04-12 13:20 PDT — capital-france (citation verification brief)
+
+- Objective: Verify citations in the capital-of-France draft and produce a cited verifier brief.
+- Changed: Read `outputs/.drafts/capital-france-draft.md`, `notes/capital-france-research-web.md`, and `notes/capital-france-legal-context.md`; fetched the three draft URLs directly; wrote `notes/capital-france-brief.md` with inline numbered citations and a numbered direct-URL sources list.
+- Verified: Confirmed the Insee, Sénat, and Élysée URLs were reachable on 2026-04-12; confirmed Insee and Sénat support the core claim that Paris is the capital of France; marked the Élysée homepage as contextual-only support.
+- Failed / learned: The Élysée homepage does not explicitly state the core claim, so it should not be used as sole evidence for capital status.
+- Blockers: None for the verifier brief; any stronger legal memo would still need a more direct constitutional/statutory basis if that specific question is asked.
+- Next: Promote the brief into the final output or downgrade/remove any claim that leans on the Élysée URL alone.

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 `22.x` for local development. The supported runtime range is Node.js `20.19.0` through `24.x`; `.nvmrc` pins the preferred local version while `package.json`, `website/package.json`, and the runtime version guard define the broader supported range.
+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

@@ -13,19 +13,63 @@
 
 ### Installation
 
+**macOS / Linux:**
+
 ```bash
 curl -fsSL https://feynman.is/install | bash
-
-# stable release channel
-curl -fsSL https://feynman.is/install | bash -s -- stable
-
-# package manager fallback
-pnpm add -g @companion-ai/feynman
-
-bun add -g @companion-ai/feynman
 ```
 
-The one-line installer tracks the latest `main` build. Use `stable` or an exact version to pin a release. Then run `feynman setup` to configure your model and get started.
+**Windows (PowerShell):**
+
+```powershell
+irm https://feynman.is/install.ps1 | iex
+```
+
+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.21`.
+
+The installer downloads a standalone native bundle with its own Node.js runtime.
+
+To upgrade the standalone app later, rerun the installer. `feynman update` only refreshes installed Pi packages inside Feynman's environment; it does not replace the standalone runtime bundle itself.
+
+To uninstall the standalone app, remove the launcher and runtime bundle, then optionally remove `~/.feynman` if you also want to delete settings, sessions, and installed package state. If you also want to delete alphaXiv login state, remove `~/.ahub`. See the installation guide for platform-specific paths.
+
+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
+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
+curl -fsSL https://feynman.is/install-skills | bash -s -- --repo
+```
+
+**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.
 
 ---
 
@@ -45,7 +89,7 @@ $ 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
+→ Replicates experiments on local or cloud GPUs
 ```
 
 ---
@@ -60,7 +104,7 @@ 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 |
@@ -98,11 +142,30 @@ Built on [Pi](https://github.com/badlogic/pi-mono) for the agent runtime, [alpha
 
 ---
 
+### Star History
+
+<a href="https://www.star-history.com/?repos=getcompanion-ai%2Ffeynman&type=date&legend=top-left">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=getcompanion-ai/feynman&type=date&theme=dark&legend=top-left" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=getcompanion-ai/feynman&type=date&legend=top-left" />
+    <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=getcompanion-ai/feynman&type=date&legend=top-left" />
+  </picture>
+</a>
+
+---
+
 ### Contributing
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide.
+
 ```bash
 git clone https://github.com/getcompanion-ai/feynman.git
-cd feynman && pnpm install && pnpm 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,9 +1,41 @@
 #!/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";
+const MAX_NODE_MAJOR = 24;
+const PREFERRED_NODE_MAJOR = 22;
+
+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;
+}
+
+const parsedNodeVersion = parseNodeVersion(process.versions.node);
+if (compareNodeVersions(parsedNodeVersion, parseNodeVersion(MIN_NODE_VERSION)) < 0 || parsedNodeVersion.major > MAX_NODE_MAJOR) {
+  const isWindows = process.platform === "win32";
+  console.error(`feynman supports Node.js ${MIN_NODE_VERSION} through ${MAX_NODE_MAJOR}.x (detected ${process.versions.node}).`);
+  console.error(parsedNodeVersion.major > MAX_NODE_MAJOR
+    ? "This newer Node release is not supported yet because native Pi packages may fail to build."
+    : isWindows
+      ? "Install a supported Node.js release from https://nodejs.org, or use the standalone installer:"
+      : `Switch to a supported Node release with \`nvm install ${PREFERRED_NODE_MAJOR} && nvm use ${PREFERRED_NODE_MAJOR}\`, 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);
 }
-await import("../scripts/patch-embedded-pi.mjs");
-await 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,21 +1,26 @@
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
+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, 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[] }> } = {};
 
+	// Pi 0.66.x folds post-switch/resume lifecycle into session_start.
 	pi.on("session_start", async (_event, ctx) => {
 		await installFeynmanHeader(pi, ctx, cache);
 	});
 
-	pi.on("session_switch", async (_event, ctx) => {
-		await installFeynmanHeader(pi, ctx, cache);
-	});
-
+	registerAlphaTools(pi);
+	registerDiscoveryCommands(pi);
+	registerFeynmanModelCommand(pi);
 	registerHelpCommand(pi);
 	registerInitCommand(pi);
 	registerOutputsCommand(pi);
+	registerServiceTierControls(pi);
 }

extensions/research-tools/alpha.ts

@@ -0,0 +1,107 @@
+import {
+	askPaper,
+	annotatePaper,
+	clearPaperAnnotation,
+	getPaper,
+	listPaperAnnotations,
+	readPaperCode,
+	searchPapers,
+} from "@companion-ai/alpha-hub/lib";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+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 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: "Search query." }),
+			mode: Type.Optional(
+				Type.String({ description: "Search mode: semantic, keyword, both, agentic, or all." }),
+			),
+		}),
+		async execute(_toolCallId, params) {
+			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'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 AI report." })),
+		}),
+		async execute(_toolCallId, params) {
+			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. 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 about the paper." }),
+		}),
+		async execute(_toolCallId, params) {
+			const result = await askPaper(params.paper, params.question);
+			return { content: [{ type: "text", text: formatText(result) }], details: result };
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_annotate_paper",
+		label: "Alpha Annotate Paper",
+		description: "Write or clear a persistent local annotation for a paper.",
+		parameters: Type.Object({
+			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: formatText(result) }], details: result };
+		},
+	});
+
+	pi.registerTool({
+		name: "alpha_list_annotations",
+		label: "Alpha List Annotations",
+		description: "List all persistent local paper annotations.",
+		parameters: Type.Object({}),
+		async execute() {
+			const result = await listPaperAnnotations();
+			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. Use '/' for repo overview.",
+		parameters: Type.Object({
+			githubUrl: Type.String({ description: "GitHub repository URL." }),
+			path: Type.Optional(Type.String({ description: "File or directory path. Default: '/'" })),
+		}),
+		async execute(_toolCallId, params) {
+			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/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");
+		},
+	});
+}

metadata/commands.mjs

@@ -35,9 +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: "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 = [
@@ -57,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" },
@@ -80,9 +86,10 @@ export const cliCommandSections = [
 		title: "Model Management",
 		commands: [
 			{ usage: "feynman model list", description: "List available models in Pi auth storage." },
-			{ 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 login [id]", description: "Authenticate a model provider with OAuth or API-key setup." },
+			{ usage: "feynman model logout [id]", description: "Clear stored auth for a model provider." },
+			{ usage: "feynman model set <provider/model>", description: "Set the default model (also accepts provider:model)." },
+			{ usage: "feynman model tier [value]", description: "View or set the request service tier override." },
 		],
 	},
 	{
@@ -99,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." },
 		],
 	},
@@ -109,7 +118,8 @@ export const legacyFlags = [
 	{ usage: "--alpha-login", description: "Sign in to alphaXiv and exit." },
 	{ 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: "--model <provider/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,19 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.2.13",
+  "version": "0.2.21",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@companion-ai/feynman",
-      "version": "0.2.13",
+      "version": "0.2.21",
+      "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",
+        "@clack/prompts": "^1.2.0",
+        "@companion-ai/alpha-hub": "^0.1.3",
+        "@mariozechner/pi-ai": "^0.66.1",
+        "@mariozechner/pi-coding-agent": "^0.66.1",
         "@sinclair/typebox": "^0.34.48",
         "dotenv": "^17.3.1"
       },
@@ -24,7 +26,7 @@
         "typescript": "^5.9.3"
       },
       "engines": {
-        "node": ">=20.18.1"
+        "node": ">=20.19.0"
       }
     },
     "node_modules/@anthropic-ai/sdk": {
@@ -779,10 +781,32 @@
         "url": "https://github.com/sponsors/Borewit"
       }
     },
+    "node_modules/@clack/core": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@clack/core/-/core-1.2.0.tgz",
+      "integrity": "sha512-qfxof/3T3t9DPU/Rj3OmcFyZInceqj/NVtO9rwIuJqCUgh32gwPjpFQQp/ben07qKlhpwq7GzfWpST4qdJ5Drg==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-wrap-ansi": "^0.1.3",
+        "sisteransi": "^1.0.5"
+      }
+    },
+    "node_modules/@clack/prompts": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@clack/prompts/-/prompts-1.2.0.tgz",
+      "integrity": "sha512-4jmztR9fMqPMjz6H/UZXj0zEmE43ha1euENwkckKKel4XpSfokExPo5AiVStdHSAlHekz4d0CA/r45Ok1E4D3w==",
+      "license": "MIT",
+      "dependencies": {
+        "@clack/core": "1.2.0",
+        "fast-string-width": "^1.1.0",
+        "fast-wrap-ansi": "^0.1.3",
+        "sisteransi": "^1.0.5"
+      }
+    },
     "node_modules/@companion-ai/alpha-hub": {
-      "version": "0.1.2",
-      "resolved": "https://registry.npmjs.org/@companion-ai/alpha-hub/-/alpha-hub-0.1.2.tgz",
-      "integrity": "sha512-YAFh4B6loo7lKRjW3UFsdoiW3ZRvLdSdP7liDsHhCxY1dzfbxNU8vDAloodiK4ieDVRqMBTmG9NYbnsb4NZUGw==",
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/@companion-ai/alpha-hub/-/alpha-hub-0.1.3.tgz",
+      "integrity": "sha512-g/JoqeGDCoSvkgs1ZSTYJhbTak0zVanQyoYOvf2tDgfqJ09gfkqmSGFDmiP4PkTn1bocPqywZIABgmv25x1uYA==",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.27.1",
@@ -1264,9 +1288,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 +1492,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.66.1",
+      "resolved": "https://registry.npmjs.org/@mariozechner/pi-agent-core/-/pi-agent-core-0.66.1.tgz",
+      "integrity": "sha512-Nj54A7SuB/EQi8r3Gs+glFOr9wz/a9uxYFf0pCLf2DE7VmzA9O7WSejrvArna17K6auftLSdNyRRe2bIO0qezg==",
       "license": "MIT",
       "dependencies": {
-        "@mariozechner/pi-ai": "^0.62.0"
+        "@mariozechner/pi-ai": "^0.66.1"
       },
       "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.66.1",
+      "resolved": "https://registry.npmjs.org/@mariozechner/pi-ai/-/pi-ai-0.66.1.tgz",
+      "integrity": "sha512-7IZHvpsFdKEBkTmjNrdVL7JLUJVIpha6bwTr12cZ5XyDrxij06wP6Ncpnf4HT5BXAzD5w2JnoqTOSbMEIZj3dg==",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.73.0",
@@ -1507,16 +1531,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.66.1",
+      "resolved": "https://registry.npmjs.org/@mariozechner/pi-coding-agent/-/pi-coding-agent-0.66.1.tgz",
+      "integrity": "sha512-cNmatT+5HvYzQ78cRhRih00wCeUTH/fFx9ecJh5AbN7axgWU+bwiZYy0cjrTsGVgMGF4xMYlPRn/Nze9JEB+/w==",
       "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.66.1",
+        "@mariozechner/pi-ai": "^0.66.1",
+        "@mariozechner/pi-tui": "^0.66.1",
         "@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 +1568,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.66.1",
+      "resolved": "https://registry.npmjs.org/@mariozechner/pi-tui/-/pi-tui-0.66.1.tgz",
+      "integrity": "sha512-hNFN42ebjwtfGooqoUwM+QaPR1XCyqPuueuP3aLOWS1bZ2nZP/jq8MBuGNrmMw1cgiDcotvOlSNj3BatzEOGsw==",
       "license": "MIT",
       "dependencies": {
         "@types/mime-types": "^2.1.4",
@@ -2528,9 +2553,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.2",
+      "resolved": "https://registry.npmjs.org/basic-ftp/-/basic-ftp-5.2.2.tgz",
+      "integrity": "sha512-1tDrzKsdCg70WGvbFss/ulVAxupNauGnOlgpyjKzeQxzyllBLS0CGLV7tjIXTK3ZQA9/FBEm9qyFFN1bciA6pw==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"
@@ -2576,9 +2601,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"
@@ -3204,6 +3229,21 @@
       "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
       "license": "MIT"
     },
+    "node_modules/fast-string-truncated-width": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/fast-string-truncated-width/-/fast-string-truncated-width-1.2.1.tgz",
+      "integrity": "sha512-Q9acT/+Uu3GwGj+5w/zsGuQjh9O1TyywhIwAxHudtWrgF09nHOPrvTLhQevPbttcxjr/SNN7mJmfOw/B1bXgow==",
+      "license": "MIT"
+    },
+    "node_modules/fast-string-width": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/fast-string-width/-/fast-string-width-1.1.0.tgz",
+      "integrity": "sha512-O3fwIVIH5gKB38QNbdg+3760ZmGz0SZMgvwJbA1b2TGXceKE6A2cOlfogh1iw8lr049zPyd7YADHy+B7U4W9bQ==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-string-truncated-width": "^1.2.0"
+      }
+    },
     "node_modules/fast-uri": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
@@ -3220,6 +3260,15 @@
       ],
       "license": "BSD-3-Clause"
     },
+    "node_modules/fast-wrap-ansi": {
+      "version": "0.1.6",
+      "resolved": "https://registry.npmjs.org/fast-wrap-ansi/-/fast-wrap-ansi-0.1.6.tgz",
+      "integrity": "sha512-HlUwET7a5gqjURj70D5jl7aC3Zmy4weA1SHUfM0JFI0Ptq987NH2TwbBFLoERhfwk+E+eaq4EK3jXoT+R3yp3w==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-string-width": "^1.1.0"
+      }
+    },
     "node_modules/fast-xml-builder": {
       "version": "1.1.4",
       "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.1.4.tgz",
@@ -3621,9 +3670,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"
@@ -3842,9 +3891,9 @@
       }
     },
     "node_modules/koffi": {
-      "version": "2.15.2",
-      "resolved": "https://registry.npmjs.org/koffi/-/koffi-2.15.2.tgz",
-      "integrity": "sha512-r9tjJLVRSOhCRWdVyQlF3/Ugzeg13jlzS4czS82MAgLff4W+BcYOW7g8Y62t9O5JYjYOLAjAovAZDNlDfZNu+g==",
+      "version": "2.15.6",
+      "resolved": "https://registry.npmjs.org/koffi/-/koffi-2.15.6.tgz",
+      "integrity": "sha512-WQBpM5uo74UQ17UpsFN+PUOrQQg4/nYdey4SGVluQun2drYYfePziLLWdSmFb4wSdWlJC1aimXQnjhPCheRKuw==",
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
@@ -4216,9 +4265,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",
@@ -4609,6 +4658,12 @@
       "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
       "license": "ISC"
     },
+    "node_modules/sisteransi": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
+      "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==",
+      "license": "MIT"
+    },
     "node_modules/smart-buffer": {
       "version": "4.2.0",
       "resolved": "https://registry.npmjs.org/smart-buffer/-/smart-buffer-4.2.0.tgz",

package.json

@@ -1,11 +1,11 @@
 {
   "name": "@companion-ai/feynman",
-  "version": "0.2.13",
+  "version": "0.2.21",
   "description": "Research-first CLI agent built on Pi and alphaXiv",
   "license": "MIT",
   "type": "module",
   "engines": {
-    "node": ">=20.18.1"
+    "node": ">=20.19.0 <25"
   },
   "bin": {
     "feynman": "bin/feynman.js"
@@ -26,14 +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": "npm run build && node ./scripts/prepare-runtime-workspace.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",
@@ -57,12 +59,35 @@
     ]
   },
   "dependencies": {
-    "@companion-ai/alpha-hub": "^0.1.2",
-    "@mariozechner/pi-ai": "^0.62.0",
-    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "@clack/prompts": "^1.2.0",
+    "@companion-ai/alpha-hub": "^0.1.3",
+    "@mariozechner/pi-ai": "^0.66.1",
+    "@mariozechner/pi-coding-agent": "^0.66.1",
     "@sinclair/typebox": "^0.34.48",
     "dotenv": "^17.3.1"
   },
+  "overrides": {
+    "basic-ftp": "5.2.2",
+    "@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.2"
+        }
+      }
+    },
+    "minimatch": {
+      "brace-expansion": "5.0.5"
+    }
+  },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsx": "^4.21.0",

prompts/audit.md

@@ -9,7 +9,7 @@ Audit the paper and codebase for: $@
 Derive a short slug from the audit target (lowercase, hyphens, no filler words, ≤5 words). Use this slug for all files in this run.
 
 Requirements:
-- Before starting, outline the audit plan: which paper, which repo, which claims to check. Write the plan to `outputs/.plans/<slug>.md`. Present the plan to the user and confirm before proceeding.
+- Before starting, outline the audit plan: which paper, which repo, which claims to check. Write the plan to `outputs/.plans/<slug>.md`. Present the plan to the user. If this is an unattended or one-shot run, continue automatically. If the user is actively interacting, give them a brief chance to request changes before proceeding.
 - Use the `researcher` subagent for evidence gathering and the `verifier` subagent to verify sources and add inline citations when the audit is non-trivial.
 - Compare claimed methods, defaults, metrics, and data handling against the actual code.
 - Call out missing code, mismatches, ambiguous defaults, and reproduction risks.

prompts/compare.md

@@ -9,7 +9,7 @@ Compare sources for: $@
 Derive a short slug from the comparison topic (lowercase, hyphens, no filler words, ≤5 words). Use this slug for all files in this run.
 
 Requirements:
-- Before starting, outline the comparison plan: which sources to compare, which dimensions to evaluate, expected output structure. Write the plan to `outputs/.plans/<slug>.md`. Present the plan to the user and confirm before proceeding.
+- Before starting, outline the comparison plan: which sources to compare, which dimensions to evaluate, expected output structure. Write the plan to `outputs/.plans/<slug>.md`. Present the plan to the user. If this is an unattended or one-shot run, continue automatically. If the user is actively interacting, give them a brief chance to request changes before proceeding.
 - Use the `researcher` subagent to gather source material when the comparison set is broad, and the `verifier` subagent to verify sources and add inline citations to the final matrix.
 - Build a comparison matrix covering: source, key claim, evidence type, caveats, confidence.
 - Generate charts with `pi-charts` when the comparison involves quantitative metrics. Use Mermaid for method or architecture comparisons.

prompts/deepresearch.md

@@ -51,7 +51,7 @@ If `CHANGELOG.md` exists, read the most recent relevant entries before finalizin
 
 Also save the plan with `memory_remember` (type: `fact`, key: `deepresearch.<slug>.plan`) so it survives context truncation.
 
-Present the plan to the user and ask them to confirm before proceeding. If the user wants changes, revise the plan first.
+Present the plan to the user. If this is an unattended or one-shot run, continue automatically. If the user is actively interacting in the terminal, give them a brief chance to request plan changes before proceeding.
 
 ## 2. Scale decision
 
@@ -182,6 +182,15 @@ Write a provenance record alongside it as `<slug>.provenance.md`:
 - **Research files:** [list of intermediate <slug>-research-*.md files]
 ```
 
+Before you stop, verify on disk that all of these exist:
+- `outputs/.plans/<slug>.md`
+- `outputs/.drafts/<slug>-draft.md`
+- `<slug>-brief.md` intermediate cited brief
+- `outputs/<slug>.md` or `papers/<slug>.md` final promoted deliverable
+- `outputs/<slug>.provenance.md` or `papers/<slug>.provenance.md` provenance sidecar
+
+Do not stop at `<slug>-brief.md` alone. If the cited brief exists but the promoted final output or provenance sidecar does not, create them before responding.
+
 ## Background execution
 
 If the user wants unattended execution or the sweep will clearly take a while:

prompts/draft.md

@@ -9,11 +9,12 @@ Write a paper-style draft for: $@
 Derive a short slug from the topic (lowercase, hyphens, no filler words, ≤5 words). Use this slug for all files in this run.
 
 Requirements:
-- Before writing, outline the draft structure: proposed title, sections, key claims to make, source material to draw from, and a verification log for the critical claims, figures, and calculations. Write the outline to `outputs/.plans/<slug>.md`. Present the outline to the user and confirm before proceeding.
+- Before writing, outline the draft structure: proposed title, sections, key claims to make, source material to draw from, and a verification log for the critical claims, figures, and calculations. Write the outline to `outputs/.plans/<slug>.md`. Present the outline to the user. If this is an unattended or one-shot run, continue automatically. If the user is actively interacting, give them a brief chance to request changes before proceeding.
 - Use the `writer` subagent when the draft should be produced from already-collected notes, then use the `verifier` subagent to add inline citations and verify sources.
 - Include at minimum: title, abstract, problem statement, related work, method or synthesis, evidence or experiments, limitations, conclusion.
 - Use clean Markdown with LaTeX where equations materially help.
-- Generate charts with `pi-charts` for quantitative data, benchmarks, and comparisons. Use Mermaid for architectures and pipelines. Every figure needs a caption.
+- Follow the system prompt's provenance rules for all results, figures, charts, images, tables, benchmarks, and quantitative comparisons. If evidence is missing, leave a placeholder or proposed experimental plan instead of claiming an outcome.
+- Generate charts with `pi-charts` only for source-backed quantitative data, benchmarks, and comparisons. Use Mermaid for architectures and pipelines only when the structure is supported by sources. Every figure needs a provenance-bearing caption.
 - Before delivery, sweep the draft for any claim that sounds stronger than its support. Mark tentative results as tentative and remove unsupported numerics instead of letting the verifier discover them later.
 - Save exactly one draft to `papers/<slug>.md`.
 - End with a `Sources` appendix with direct URLs for all primary references.

prompts/lit.md

@@ -10,9 +10,9 @@ Derive a short slug from the topic (lowercase, hyphens, no filler words, ≤5 wo
 
 ## Workflow
 
-1. **Plan** — Outline the scope: key questions, source types to search (papers, web, repos), time period, expected sections, and a small task ledger plus verification log. Write the plan to `outputs/.plans/<slug>.md`. Present the plan to the user and confirm before proceeding.
+1. **Plan** — Outline the scope: key questions, source types to search (papers, web, repos), time period, expected sections, and a small task ledger plus verification log. Write the plan to `outputs/.plans/<slug>.md`. Present the plan to the user. If this is an unattended or one-shot run, continue automatically. If the user is actively interacting, give them a brief chance to request changes before proceeding.
 2. **Gather** — Use the `researcher` subagent when the sweep is wide enough to benefit from delegated paper triage before synthesis. For narrow topics, search directly. Researcher outputs go to `<slug>-research-*.md`. Do not silently skip assigned questions; mark them `done`, `blocked`, or `superseded`.
 3. **Synthesize** — Separate consensus, disagreements, and open questions. When useful, propose concrete next experiments or follow-up reading. Generate charts with `pi-charts` for quantitative comparisons across papers and Mermaid diagrams for taxonomies or method pipelines. Before finishing the draft, sweep every strong claim against the verification log and downgrade anything that is inferred or single-source critical.
 4. **Cite** — Spawn the `verifier` agent to add inline citations and verify every source URL in the draft.
 5. **Verify** — Spawn the `reviewer` agent to check the cited draft for unsupported claims, logical gaps, zombie sections, and single-source critical findings. Fix FATAL issues before delivering. Note MAJOR issues in Open Questions. If FATAL issues were found, run one more verification pass after the fixes.
-6. **Deliver** — Save the final literature review to `outputs/<slug>.md`. Write a provenance record alongside it as `outputs/<slug>.provenance.md` listing: date, sources consulted vs. accepted vs. rejected, verification status, and intermediate research files used.
+6. **Deliver** — Save the final literature review to `outputs/<slug>.md`. Write a provenance record alongside it as `outputs/<slug>.provenance.md` listing: date, sources consulted vs. accepted vs. rejected, verification status, and intermediate research files used. Before you stop, verify on disk that both files exist; do not stop at an intermediate cited draft alone.

prompts/review.md

@@ -9,7 +9,7 @@ Review this AI research artifact: $@
 Derive a short slug from the artifact name (lowercase, hyphens, no filler words, ≤5 words). Use this slug for all files in this run.
 
 Requirements:
-- Before starting, outline what will be reviewed, the review criteria (novelty, empirical rigor, baselines, reproducibility, etc.), and any verification-specific checks needed for claims, figures, and reported metrics. Present the plan to the user and confirm before proceeding.
+- Before starting, outline what will be reviewed, the review criteria (novelty, empirical rigor, baselines, reproducibility, etc.), and any verification-specific checks needed for claims, figures, and reported metrics. Present the plan to the user. If this is an unattended or one-shot run, continue automatically. If the user is actively interacting, give them a brief chance to request changes before proceeding.
 - Spawn a `researcher` subagent to gather evidence on the artifact — inspect the paper, code, cited work, and any linked experimental artifacts. Save to `<slug>-research.md`.
 - Spawn a `reviewer` subagent with `<slug>-research.md` to produce the final peer review with inline annotations.
 - For small or simple artifacts where evidence gathering is overkill, run the `reviewer` subagent directly instead.

prompts/summarize.md

@@ -0,0 +1,165 @@
+---
+description: Summarize any URL, local file, or PDF using the RLM pattern — source stored on disk, never injected raw into context.
+args: <source>
+section: Research Workflows
+topLevelCli: true
+---
+Summarize the following source: $@
+
+Derive a short slug from the source filename or URL domain (lowercase, hyphens, no filler words, ≤5 words — e.g. `attention-is-all-you-need`). Use this slug for all files in this run.
+
+## Why this uses the RLM pattern
+
+Standard summarization injects the full document into context. Above ~15k tokens, early content degrades as the window fills (context rot). This workflow keeps the document on disk as an external variable and reads only bounded windows — so context pressure is proportional to the window size, not the document size.
+
+Tier 1 (< 8k chars) is a deliberate exception: direct injection is safe at ~2k tokens and windowed reading would add unnecessary friction.
+
+---
+
+## Step 1 — Fetch, validate, measure
+
+Run all guards before any tier logic. A failure here is cheap; a failure mid-Tier-3 is not.
+
+- **GitHub repo URL** (`https://github.com/owner/repo` — exactly 4 slashes): fetch the raw README instead. Try `https://raw.githubusercontent.com/{owner}/{repo}/main/README.md`, then `/master/README.md`. A repo HTML page is not the document the user wants to summarize.
+- **Remote URL**: fetch to disk with `curl -sL -o outputs/.notes/<slug>-raw.txt <url>`. Do NOT use fetch_content — its return value enters context directly, bypassing the RLM external-variable principle.
+- **Local file or PDF**: copy or extract to `outputs/.notes/<slug>-raw.txt`. For PDFs, extract text via `pdftotext` or equivalent before measuring.
+- **Empty or failed fetch**: if the file is < 50 bytes after fetching, stop and surface the error to the user — do not proceed to tier selection.
+- **Binary content**: if the file is > 1 KB but contains < 100 readable text characters, stop and tell the user the content appears binary or unextracted.
+- **Existing output**: if `outputs/<slug>-summary.md` already exists, ask the user whether to overwrite or use a different slug. Do not proceed until confirmed.
+
+Measure decoded text characters (not bytes — UTF-8 multi-byte chars would overcount). Log: `[summarize] source=<source> slug=<slug> chars=<count>`
+
+---
+
+## Step 2 — Choose tier
+
+| Chars | Tier | Strategy |
+|---|---|---|
+| < 8 000 | 1 | Direct read — full content enters context (safe at ~2k tokens) |
+| 8 000 – 60 000 | 2 | RLM-lite — windowed bash extraction, progressive notes to disk |
+| > 60 000 | 3 | Full RLM — bash chunking + parallel researcher subagents |
+
+Log: `[summarize] tier=<N> chars=<count>`
+
+---
+
+## Tier 1 — Direct read
+
+Read `outputs/.notes/<slug>-raw.txt` in full. Summarize directly using the output format. Write to `outputs/<slug>-summary.md`.
+
+---
+
+## Tier 2 — RLM-lite windowed read
+
+The document stays on disk. Extract 6 000-char windows via bash:
+
+```python
+# WHY f.seek/f.read: the read tool uses line offsets, not char offsets.
+# For exact char-boundary windowing across arbitrary text, bash is required.
+with open("outputs/.notes/<slug>-raw.txt", encoding="utf-8") as f:
+    f.seek(n * 6000)
+    window = f.read(6000)
+```
+
+For each window:
+1. Extract key claims and evidence.
+2. Append to `outputs/.notes/<slug>-notes.md` before reading the next window. This is the checkpoint: if the session is interrupted, processed windows survive.
+3. Log: `[summarize] window <N>/<total> done`
+
+Synthesize `outputs/.notes/<slug>-notes.md` into `outputs/<slug>-summary.md`.
+
+---
+
+## Tier 3 — Full RLM parallel chunks
+
+Each chunk gets a fresh researcher subagent context window — context rot is impossible because no subagent sees more than 6 000 chars.
+
+WHY 500-char overlap: academic papers contain multi-sentence arguments that span chunk boundaries. 500 chars (~80 words) ensures a cross-boundary claim appears fully in at least one adjacent chunk.
+
+### 3a. Chunk the document
+
+```python
+import os
+os.makedirs("outputs/.notes", exist_ok=True)
+
+with open("outputs/.notes/<slug>-raw.txt", encoding="utf-8") as f:
+    text = f.read()
+
+chunk_size, overlap = 6000, 500
+chunks, i = [], 0
+while i < len(text):
+    chunks.append(text[i : i + chunk_size])
+    i += chunk_size - overlap
+
+for n, chunk in enumerate(chunks):
+    # Zero-pad index so files sort correctly (chunk-002 before chunk-010)
+    with open(f"outputs/.notes/<slug>-chunk-{n:03d}.txt", "w", encoding="utf-8") as f:
+        f.write(chunk)
+
+print(f"[summarize] chunks={len(chunks)} chunk_size={chunk_size} overlap={overlap}")
+```
+
+### 3b. Confirm before spawning
+
+If this is an unattended or one-shot run, continue automatically. Otherwise tell the user: "Source is ~<chars> chars -> <N> chunks -> <N> researcher subagents. This may take several minutes. Proceed?" Wait for confirmation before launching Tier 3.
+
+### 3c. Dispatch researcher subagents
+
+```json
+{
+  "tasks": [{
+    "agent": "researcher",
+    "task": "Read ONLY `outputs/.notes/<slug>-chunk-NNN.txt`. Extract: (1) key claims, (2) methodology or technical approach, (3) cited evidence. Do NOT use web_search or fetch external URLs — this is single-source summarization. If a claim appears to start or end mid-sentence at the file boundary, mark it BOUNDARY PARTIAL. Write to `outputs/.notes/<slug>-summary-chunk-NNN.md`.",
+    "output": "outputs/.notes/<slug>-summary-chunk-NNN.md"
+  }],
+  "concurrency": 4,
+  "failFast": false
+}
+```
+
+### 3d. Aggregate
+
+After all subagents return, verify every expected `outputs/.notes/<slug>-summary-chunk-NNN.md` exists. Note any missing chunk indices — they will appear in the Coverage gaps section of the output. Do not abort on partial coverage; a partial summary with gaps noted is more useful than no summary.
+
+When synthesizing:
+- **Deduplicate**: a claim in multiple chunks is one claim — keep the most complete formulation.
+- **Resolve boundary conflicts**: for adjacent-chunk contradictions, prefer the version with more supporting context.
+- **Remove BOUNDARY PARTIAL markers** where a complete version exists in a neighbouring chunk.
+
+Write to `outputs/<slug>-summary.md`.
+
+---
+
+## Output format
+
+All tiers produce the same artifact at `outputs/<slug>-summary.md`:
+
+```markdown
+# Summary: [document title or source filename]
+
+**Source:** [URL or file path]
+**Date:** [YYYY-MM-DD]
+**Tier:** [1 / 2 (N windows) / 3 (N chunks)]
+
+## Key Claims
+[3-7 most important assertions, each as a bullet]
+
+## Methodology
+[Approach, dataset, evaluation, baselines — omit for non-research documents]
+
+## Limitations
+[What the source explicitly flags as weak, incomplete, or out of scope]
+
+## Verdict
+[One paragraph: what this document establishes, its credibility, who should read it]
+
+## Sources
+1. [Title or filename] — [URL or file path]
+
+## Coverage gaps *(Tier 3 only — omit if all chunks succeeded)*
+[Missing chunk indices and their approximate byte ranges]
+```
+
+Before you stop, verify on disk that `outputs/<slug>-summary.md` exists.
+
+Sources contains only the single source confirmed reachable in Step 1. No verifier subagent is needed — there are no URLs constructed from memory to verify.

prompts/watch.md

@@ -9,7 +9,7 @@ Create a research watch for: $@
 Derive a short slug from the watch topic (lowercase, hyphens, no filler words, ≤5 words). Use this slug for all files in this run.
 
 Requirements:
-- Before starting, outline the watch plan: what to monitor, what signals matter, what counts as a meaningful change, and the check frequency. Write the plan to `outputs/.plans/<slug>.md`. Present the plan to the user and confirm before proceeding.
+- Before starting, outline the watch plan: what to monitor, what signals matter, what counts as a meaningful change, and the check frequency. Write the plan to `outputs/.plans/<slug>.md`. Present the plan to the user. If this is an unattended or one-shot run, continue automatically. If the user is actively interacting, give them a brief chance to request changes before proceeding.
 - Start with a baseline sweep of the topic.
 - Use `schedule_prompt` to create the recurring or delayed follow-up instead of merely promising to check later.
 - Save exactly one baseline artifact to `outputs/<slug>-baseline.md`.

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";
@@ -243,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",

scripts/check-node-version.mjs

@@ -0,0 +1,46 @@
+const MIN_NODE_VERSION = "20.19.0";
+const MAX_NODE_MAJOR = 24;
+const PREFERRED_NODE_MAJOR = 22;
+
+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) {
+	const parsed = parseNodeVersion(version);
+	return compareNodeVersions(parsed, parseNodeVersion(MIN_NODE_VERSION)) >= 0 && parsed.major <= MAX_NODE_MAJOR;
+}
+
+function getUnsupportedNodeVersionLines(version = process.versions.node) {
+	const isWindows = process.platform === "win32";
+	const parsed = parseNodeVersion(version);
+	return [
+		`feynman supports Node.js ${MIN_NODE_VERSION} through ${MAX_NODE_MAJOR}.x (detected ${version}).`,
+		parsed.major > MAX_NODE_MAJOR
+			? "This newer Node release is not supported yet because native Pi packages may fail to build."
+			: isWindows
+				? "Install a supported Node.js release from https://nodejs.org, or use the standalone installer:"
+				: `Switch to a supported Node release with \`nvm install ${PREFERRED_NODE_MAJOR} && nvm use ${PREFERRED_NODE_MAJOR}\`, 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

@@ -1,5 +1,5 @@
 param(
-  [string]$Version = "edge"
+  [string]$Version = "latest"
 )
 
 $ErrorActionPreference = "Stop"
@@ -8,17 +8,27 @@ function Normalize-Version {
   param([string]$RequestedVersion)
 
   if (-not $RequestedVersion) {
-    return "edge"
+    return "latest"
   }
 
   switch ($RequestedVersion.ToLowerInvariant()) {
-    "edge" { return "edge" }
     "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-ReleaseMetadata {
   param(
     [string]$RequestedVersion,
@@ -28,34 +38,8 @@ function Resolve-ReleaseMetadata {
 
   $normalizedVersion = Normalize-Version -RequestedVersion $RequestedVersion
 
-  if ($normalizedVersion -eq "edge") {
-    $release = Invoke-RestMethod -Uri "https://api.github.com/repos/getcompanion-ai/feynman/releases/tags/edge"
-    $asset = $release.assets | Where-Object { $_.name -like "feynman-*-$AssetTarget.$BundleExtension" } | Select-Object -First 1
-    if (-not $asset) {
-      throw "Failed to resolve the latest Feynman edge bundle."
-    }
-
-    $archiveName = $asset.name
-    $suffix = ".$BundleExtension"
-    $bundleName = $archiveName.Substring(0, $archiveName.Length - $suffix.Length)
-    $resolvedVersion = $bundleName.Substring("feynman-".Length)
-    $resolvedVersion = $resolvedVersion.Substring(0, $resolvedVersion.Length - ("-$AssetTarget").Length)
-
-    return [PSCustomObject]@{
-      ResolvedVersion = $resolvedVersion
-      BundleName = $bundleName
-      ArchiveName = $archiveName
-      DownloadUrl = $asset.browser_download_url
-    }
-  }
-
   if ($normalizedVersion -eq "latest") {
-    $release = Invoke-RestMethod -Uri "https://api.github.com/repos/getcompanion-ai/feynman/releases/latest"
-    if (-not $release.tag_name) {
-      throw "Failed to resolve the latest Feynman release version."
-    }
-
-    $resolvedVersion = $release.tag_name.TrimStart("v")
+    $resolvedVersion = Resolve-LatestReleaseVersion
   } else {
     $resolvedVersion = $normalizedVersion
   }
@@ -73,12 +57,26 @@ function Resolve-ReleaseMetadata {
 }
 
 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" }
-    default { throw "Unsupported architecture: $arch" }
     }
+  } catch {}
+
+  throw "Unsupported architecture: $envArch"
 }
 
 $archSuffix = Get-ArchSuffix
@@ -111,8 +109,8 @@ This usually means the release exists, but not all platform bundles were uploade
 
 Workarounds:
   - try again after the release finishes publishing
-  - install via pnpm instead: pnpm add -g @companion-ai/feynman
-  - install via bun instead: bun add -g @companion-ai/feynman
+  - pass the latest published version explicitly, e.g.:
+    & ([scriptblock]::Create((irm https://feynman.is/install.ps1))) -Version 0.2.21
 "@
   }
 
@@ -127,14 +125,24 @@ Workarounds:
   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 {
@@ -146,6 +154,14 @@ Workarounds:
     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

@@ -2,7 +2,7 @@
 
 set -eu
 
-VERSION="${1:-edge}"
+VERSION="${1:-latest}"
 INSTALL_BIN_DIR="${FEYNMAN_INSTALL_BIN_DIR:-$HOME/.local/bin}"
 INSTALL_APP_DIR="${FEYNMAN_INSTALL_APP_DIR:-$HOME/.local/share/feynman}"
 SKIP_PATH_UPDATE="${FEYNMAN_INSTALL_SKIP_PATH_UPDATE:-0}"
@@ -54,12 +54,16 @@ run_with_spinner() {
 
 normalize_version() {
   case "$1" in
-    "" | edge)
-      printf 'edge\n'
+    "")
+      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}"
       ;;
@@ -160,39 +164,29 @@ require_command() {
   fi
 }
 
-resolve_release_metadata() {
-  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" = "edge" ]; then
-    release_json="$(download_text "https://api.github.com/repos/getcompanion-ai/feynman/releases/tags/edge")"
-    asset_url=""
-
-    for candidate in $(printf '%s\n' "$release_json" | sed -n 's/.*"browser_download_url":[[:space:]]*"\([^"]*\)".*/\1/p'); do
-      case "$candidate" in
-        */feynman-*-${asset_target}.${archive_extension})
-          asset_url="$candidate"
-          break
-          ;;
-      esac
-    done
-
-    if [ -z "$asset_url" ]; then
-      echo "Failed to resolve the latest Feynman edge bundle." >&2
-      exit 1
-    fi
-
-    archive_name="${asset_url##*/}"
-    bundle_name="${archive_name%.$archive_extension}"
-    resolved_version="${bundle_name#feynman-}"
-    resolved_version="${resolved_version%-${asset_target}}"
-
-    printf '%s\n%s\n%s\n%s\n' "$resolved_version" "$bundle_name" "$archive_name" "$asset_url"
+  if [ -z "$resolved_path" ]; then
     return
   fi
 
+  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"
+
+    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_json="$(download_text "https://api.github.com/repos/getcompanion-ai/feynman/releases/latest")"
-    resolved_version="$(printf '%s\n' "$release_json" | sed -n 's/.*"tag_name":[[:space:]]*"v\([^"]*\)".*/\1/p' | head -n 1)"
+    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
@@ -266,8 +260,8 @@ This usually means the release exists, but not all platform bundles were uploade
 
 Workarounds:
   - try again after the release finishes publishing
-  - install via pnpm instead: pnpm add -g @companion-ai/feynman
-  - install via bun instead: bun add -g @companion-ai/feynman
+  - pass the latest published version explicitly, e.g.:
+    curl -fsSL https://feynman.is/install | bash -s -- 0.2.21
 EOF
   exit 1
 fi
@@ -290,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/alpha-hub-auth-patch.d.mts

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

scripts/lib/alpha-hub-auth-patch.mjs

@@ -0,0 +1,66 @@
+const LEGACY_SUCCESS_HTML = "'<html><body><h2>Logged in to Alpha Hub</h2><p>You can close this tab.</p></body></html>'";
+const LEGACY_ERROR_HTML = "'<html><body><h2>Login failed</h2><p>You can close this tab.</p></body></html>'";
+
+const bodyAttr = 'style="font-family:system-ui,sans-serif;text-align:center;padding-top:20vh;background:#050a08;color:#f0f5f2"';
+const logo = '<h1 style="font-family:monospace;font-size:48px;color:#34d399;margin:0">feynman</h1>';
+
+const FEYNMAN_SUCCESS_HTML = `'<html><body ${bodyAttr}>${logo}<h2 style="color:#34d399;margin-top:16px">Logged in</h2><p style="color:#8aaa9a">You can close this tab.</p></body></html>'`;
+const FEYNMAN_ERROR_HTML = `'<html><body ${bodyAttr}>${logo}<h2 style="color:#ef4444;margin-top:16px">Login failed</h2><p style="color:#8aaa9a">You can close this tab.</p></body></html>'`;
+
+const CURRENT_OPEN_BROWSER = [
+	"function openBrowser(url) {",
+	"  try {",
+	"    const plat = platform();",
+	"    if (plat === 'darwin') execSync(`open \"${url}\"`);",
+	"    else if (plat === 'linux') execSync(`xdg-open \"${url}\"`);",
+	"    else if (plat === 'win32') execSync(`start \"\" \"${url}\"`);",
+	"  } catch {}",
+	"}",
+].join("\n");
+
+const PATCHED_OPEN_BROWSER = [
+	"function openBrowser(url) {",
+	"  try {",
+	"    const plat = platform();",
+	"    const isWsl = plat === 'linux' && (Boolean(process.env.WSL_DISTRO_NAME) || Boolean(process.env.WSL_INTEROP));",
+	"    if (plat === 'darwin') execSync(`open \"${url}\"`);",
+	"    else if (isWsl) {",
+	"      try {",
+	"        execSync(`wslview \"${url}\"`);",
+	"      } catch {",
+	"        execSync(`cmd.exe /c start \"\" \"${url}\"`);",
+	"      }",
+	"    }",
+	"    else if (plat === 'linux') execSync(`xdg-open \"${url}\"`);",
+	"    else if (plat === 'win32') execSync(`cmd /c start \"\" \"${url}\"`);",
+	"  } catch {}",
+	"}",
+].join("\n");
+
+const LEGACY_WIN_OPEN = "else if (plat === 'win32') execSync(`start \"${url}\"`);";
+const FIXED_WIN_OPEN = "else if (plat === 'win32') execSync(`cmd /c start \"\" \"${url}\"`);";
+
+const OPEN_BROWSER_LOG = "process.stderr.write('Opening browser for alphaXiv login...\\n');";
+const OPEN_BROWSER_LOG_WITH_URL = "process.stderr.write(`Opening browser for alphaXiv login...\\nAuth URL: ${authUrl.toString()}\\n`);";
+
+export function patchAlphaHubAuthSource(source) {
+	let patched = source;
+
+	if (patched.includes(LEGACY_SUCCESS_HTML)) {
+		patched = patched.replace(LEGACY_SUCCESS_HTML, FEYNMAN_SUCCESS_HTML);
+	}
+	if (patched.includes(LEGACY_ERROR_HTML)) {
+		patched = patched.replace(LEGACY_ERROR_HTML, FEYNMAN_ERROR_HTML);
+	}
+	if (patched.includes(CURRENT_OPEN_BROWSER)) {
+		patched = patched.replace(CURRENT_OPEN_BROWSER, PATCHED_OPEN_BROWSER);
+	}
+	if (patched.includes(LEGACY_WIN_OPEN)) {
+		patched = patched.replace(LEGACY_WIN_OPEN, FIXED_WIN_OPEN);
+	}
+	if (patched.includes(OPEN_BROWSER_LOG)) {
+		patched = patched.replace(OPEN_BROWSER_LOG, OPEN_BROWSER_LOG_WITH_URL);
+	}
+
+	return patched;
+}

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,184 @@
+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");',
+			);
+			patched = replaceAll(
+				patched,
+				[
+					'export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {',
+					'\tconst userDirOld = path.join(os.homedir(), ".pi", "agent", "agents");',
+					'\tconst userDirNew = path.join(os.homedir(), ".agents");',
+				].join("\n"),
+				[
+					'export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {',
+					'\tconst userDir = path.join(resolvePiAgentDir(), "agents");',
+				].join("\n"),
+			);
+			patched = replaceAll(
+				patched,
+				[
+					'\tconst userAgentsOld = scope === "project" ? [] : loadAgentsFromDir(userDirOld, "user");',
+					'\tconst userAgentsNew = scope === "project" ? [] : loadAgentsFromDir(userDirNew, "user");',
+					'\tconst userAgents = [...userAgentsOld, ...userAgentsNew];',
+				].join("\n"),
+				'\tconst userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");',
+			);
+			patched = replaceAll(
+				patched,
+				[
+					'const userDirOld = path.join(os.homedir(), ".pi", "agent", "agents");',
+					'const userDirNew = path.join(os.homedir(), ".agents");',
+				].join("\n"),
+				'const userDir = path.join(resolvePiAgentDir(), "agents");',
+			);
+			patched = replaceAll(
+				patched,
+				[
+					'\tconst user = [',
+					'\t\t...loadAgentsFromDir(userDirOld, "user"),',
+					'\t\t...loadAgentsFromDir(userDirNew, "user"),',
+					'\t];',
+				].join("\n"),
+				'\tconst user = loadAgentsFromDir(userDir, "user");',
+			);
+			patched = replaceAll(
+				patched,
+				[
+					'\tconst chains = [',
+					'\t\t...loadChainsFromDir(userDirOld, "user"),',
+					'\t\t...loadChainsFromDir(userDirNew, "user"),',
+					'\t\t...(projectDir ? loadChainsFromDir(projectDir, "project") : []),',
+					'\t];',
+				].join("\n"),
+				[
+					'\tconst chains = [',
+					'\t\t...loadChainsFromDir(userDir, "user"),',
+					'\t\t...(projectDir ? loadChainsFromDir(projectDir, "project") : []),',
+					'\t];',
+				].join("\n"),
+			);
+			patched = replaceAll(
+				patched,
+				'\tconst userDir = fs.existsSync(userDirNew) ? userDirNew : userDirOld;',
+				'\tconst 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,48 @@
+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;
+	let changed = false;
+
+	if (!patched.includes(PATCHED_CONFIG_EXPR)) {
+		patched = patched.split(LEGACY_CONFIG_EXPR).join(PATCHED_CONFIG_EXPR);
+		changed = patched !== source;
+	}
+
+	if (relativePath === "index.ts") {
+		const workflowDefaultOriginal = 'const workflow = resolveWorkflow(params.workflow ?? configWorkflow, ctx?.hasUI !== false);';
+		const workflowDefaultPatched = 'const workflow = resolveWorkflow(params.workflow ?? configWorkflow ?? "none", ctx?.hasUI !== false);';
+		if (patched.includes(workflowDefaultOriginal)) {
+			patched = patched.replace(workflowDefaultOriginal, workflowDefaultPatched);
+			changed = true;
+		}
+		if (patched.includes('summary-review = open curator with auto summary draft (default)')) {
+			patched = patched.replace(
+				'summary-review = open curator with auto summary draft (default)',
+				'summary-review = open curator with auto summary draft (opt-in)',
+			);
+			changed = true;
+		}
+	}
+
+	if (relativePath === "index.ts" && changed) {
+		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,12 +1,23 @@
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { delimiter, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { FEYNMAN_LOGO_HTML } from "../logo.mjs";
+import { patchAlphaHubAuthSource } from "./lib/alpha-hub-auth-patch.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";
 
@@ -51,8 +62,20 @@ 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,
@@ -65,12 +88,46 @@ const piMemoryPath = resolve(workspaceRoot, "@samfp", "pi-memory", "src", "index
 const settingsPath = resolve(appRoot, ".feynman", "settings.json");
 const workspaceDir = resolve(appRoot, ".feynman", "npm");
 const workspacePackageJsonPath = resolve(workspaceDir, "package.json");
+const workspaceManifestPath = resolve(workspaceDir, ".runtime-manifest.json");
 const workspaceArchivePath = resolve(appRoot, ".feynman", "runtime-workspace.tgz");
+const globalNodeModulesRoot = resolve(feynmanNpmPrefix, "lib", "node_modules");
+const PRUNE_VERSION = 3;
+const NATIVE_PACKAGE_SPECS = new Set([
+	"@kaiserlich-dev/pi-session-search",
+	"@samfp/pi-memory",
+]);
+const FILTERED_INSTALL_OUTPUT_PATTERNS = [
+	/npm warn deprecated node-domexception@1\.0\.0/i,
+	/npm notice/i,
+	/^(added|removed|changed) \d+ packages?( in .+)?$/i,
+	/^\d+ packages are looking for funding$/i,
+	/^run `npm fund` for details$/i,
+];
+
+function arraysMatch(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function supportsNativePackageSources(version = process.versions.node) {
+	const [major = "0"] = version.replace(/^v/, "").split(".");
+	return (Number.parseInt(major, 10) || 0) <= 24;
+}
 
 function createInstallCommand(packageManager, packageSpecs) {
 	switch (packageManager) {
 		case "npm":
-			return ["install", "--prefer-offline", "--no-audit", "--no-fund", "--loglevel", "error", ...packageSpecs];
+			return [
+				"install",
+				"--global=false",
+				"--location=project",
+				"--prefer-offline",
+				"--no-audit",
+				"--no-fund",
+				"--legacy-peer-deps",
+				"--loglevel",
+				"error",
+				...packageSpecs,
+			];
 		case "pnpm":
 			return ["add", "--prefer-offline", "--reporter", "silent", ...packageSpecs];
 		case "bun":
@@ -109,12 +166,24 @@ function installWorkspacePackages(packageSpecs) {
 
 	const result = spawnSync(packageManager, createInstallCommand(packageManager, packageSpecs), {
 		cwd: workspaceDir,
-		stdio: ["ignore", "ignore", "pipe"],
+		stdio: ["ignore", "pipe", "pipe"],
 		timeout: 300000,
+		env: {
+			...process.env,
+			PATH: getPathWithCurrentNode(process.env.PATH),
+		},
 	});
 
+	for (const stream of [result.stdout, result.stderr]) {
+		if (!stream?.length) continue;
+		for (const line of stream.toString().split(/\r?\n/)) {
+			if (!line.trim()) continue;
+			if (FILTERED_INSTALL_OUTPUT_PATTERNS.some((pattern) => pattern.test(line.trim()))) continue;
+			process.stderr.write(`${line}\n`);
+		}
+	}
+
 	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;
 	}
@@ -127,6 +196,121 @@ function parsePackageName(spec) {
 	return match?.[1] ?? spec;
 }
 
+function filterUnsupportedPackageSpecs(packageSpecs) {
+	if (supportsNativePackageSources()) return packageSpecs;
+	return packageSpecs.filter((spec) => !NATIVE_PACKAGE_SPECS.has(parsePackageName(spec)));
+}
+
+function workspaceContainsPackages(packageSpecs) {
+	return packageSpecs.every((spec) => existsSync(resolve(workspaceRoot, parsePackageName(spec))));
+}
+
+function workspaceMatchesRuntime(packageSpecs) {
+	if (!existsSync(workspaceManifestPath)) return false;
+
+	try {
+		const manifest = JSON.parse(readFileSync(workspaceManifestPath, "utf8"));
+		if (!Array.isArray(manifest.packageSpecs)) {
+			return false;
+		}
+		if (!arraysMatch(manifest.packageSpecs, packageSpecs)) {
+			if (!(workspaceContainsPackages(packageSpecs) && packageSpecs.every((spec) => manifest.packageSpecs.includes(spec)))) {
+				return false;
+			}
+		}
+		if (!supportsNativePackageSources() && workspaceContainsPackages(packageSpecs)) {
+			return true;
+		}
+		if (
+			manifest.nodeAbi !== process.versions.modules ||
+			manifest.platform !== process.platform ||
+			manifest.arch !== process.arch ||
+			manifest.pruneVersion !== PRUNE_VERSION
+		) {
+			return false;
+		}
+
+		return packageSpecs.every((spec) => existsSync(resolve(workspaceRoot, parsePackageName(spec))));
+	} catch {
+		return false;
+	}
+}
+
+function writeWorkspaceManifest(packageSpecs) {
+	writeFileSync(
+		workspaceManifestPath,
+		JSON.stringify(
+			{
+				packageSpecs,
+				generatedAt: new Date().toISOString(),
+				nodeAbi: process.versions.modules,
+				nodeVersion: process.version,
+				platform: process.platform,
+				arch: process.arch,
+				pruneVersion: PRUNE_VERSION,
+			},
+			null,
+			2,
+		) + "\n",
+		"utf8",
+	);
+}
+
+function ensureParentDir(path) {
+	mkdirSync(dirname(path), { recursive: true });
+}
+
+function packageDependencyExists(packagePath, globalNodeModulesRoot, dependency) {
+	return existsSync(resolve(packagePath, "node_modules", dependency)) ||
+		existsSync(resolve(globalNodeModulesRoot, dependency));
+}
+
+function installedPackageLooksUsable(packagePath, globalNodeModulesRoot) {
+	if (!existsSync(resolve(packagePath, "package.json"))) return false;
+	try {
+		const pkg = JSON.parse(readFileSync(resolve(packagePath, "package.json"), "utf8"));
+		return Object.keys(pkg.dependencies ?? {}).every((dependency) =>
+			packageDependencyExists(packagePath, globalNodeModulesRoot, dependency)
+		);
+	} catch {
+		return false;
+	}
+}
+
+function linkPointsTo(linkPath, targetPath) {
+	try {
+		if (!lstatSync(linkPath).isSymbolicLink()) return false;
+		return resolve(dirname(linkPath), readlinkSync(linkPath)) === targetPath;
+	} catch {
+		return false;
+	}
+}
+
+function ensureBundledPackageLinks(packageSpecs) {
+	if (!workspaceMatchesRuntime(packageSpecs)) return;
+
+	for (const spec of packageSpecs) {
+		const packageName = parsePackageName(spec);
+		const sourcePath = resolve(workspaceRoot, packageName);
+		const targetPath = resolve(globalNodeModulesRoot, packageName);
+		if (!existsSync(sourcePath)) continue;
+		if (linkPointsTo(targetPath, sourcePath)) continue;
+		try {
+			if (lstatSync(targetPath).isSymbolicLink()) {
+				rmSync(targetPath, { force: true });
+			} else if (!installedPackageLooksUsable(targetPath, globalNodeModulesRoot)) {
+				rmSync(targetPath, { recursive: true, force: true });
+			}
+		} catch {}
+		if (existsSync(targetPath)) continue;
+
+		ensureParentDir(targetPath);
+		try {
+			symlinkSync(sourcePath, targetPath, process.platform === "win32" ? "junction" : "dir");
+		} catch {}
+	}
+}
+
 function restorePackagedWorkspace(packageSpecs) {
 	if (!existsSync(workspaceArchivePath)) return false;
 
@@ -138,16 +322,18 @@ 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))));
-}
-
-function refreshPackagedWorkspace(packageSpecs) {
-	return installWorkspacePackages(packageSpecs);
+	return false;
 }
 
 function resolveExecutable(name, fallbackPaths = []) {
@@ -155,17 +341,35 @@ function resolveExecutable(name, fallbackPaths = []) {
 		if (existsSync(candidate)) return candidate;
 	}
 
-	const result = spawnSync("sh", ["-lc", `command -v ${name}`], {
+	const isWindows = process.platform === "win32";
+	const env = {
+		...process.env,
+		PATH: process.env.PATH ?? "",
+	};
+	const result = isWindows
+		? spawnSync("cmd", ["/c", `where ${name}`], {
 				encoding: "utf8",
 				stdio: ["ignore", "pipe", "ignore"],
+				env,
+			})
+		: spawnSync("sh", ["-c", `command -v ${name}`], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				env,
 			});
 	if (result.status === 0) {
-		const resolved = result.stdout.trim();
+		const resolved = result.stdout.trim().split(/\r?\n/)[0];
 		if (resolved) return resolved;
 	}
 	return null;
 }
 
+function getPathWithCurrentNode(pathValue = process.env.PATH ?? "") {
+	const nodeDir = dirname(process.execPath);
+	const parts = pathValue.split(delimiter).filter(Boolean);
+	return parts.includes(nodeDir) ? pathValue : `${nodeDir}${delimiter}${pathValue}`;
+}
+
 function ensurePackageWorkspace() {
 	if (!existsSync(settingsPath)) return;
 
@@ -175,10 +379,17 @@ function ensurePackageWorkspace() {
 				.filter((v) => typeof v === "string" && v.startsWith("npm:"))
 				.map((v) => v.slice(4))
 		: [];
+	const supportedPackageSpecs = filterUnsupportedPackageSpecs(packageSpecs);
 
-	if (packageSpecs.length === 0) return;
-	if (existsSync(resolve(workspaceRoot, parsePackageName(packageSpecs[0])))) return;
-	if (restorePackagedWorkspace(packageSpecs) && refreshPackagedWorkspace(packageSpecs)) return;
+	if (supportedPackageSpecs.length === 0) return;
+	if (workspaceMatchesRuntime(supportedPackageSpecs)) {
+		ensureBundledPackageLinks(supportedPackageSpecs);
+		return;
+	}
+	if (restorePackagedWorkspace(packageSpecs) && workspaceMatchesRuntime(supportedPackageSpecs)) {
+		ensureBundledPackageLinks(supportedPackageSpecs);
+		return;
+	}
 
 	mkdirSync(workspaceDir, { recursive: true });
 	writeFileSync(
@@ -195,7 +406,7 @@ function ensurePackageWorkspace() {
 		process.stderr.write(`\r${frames[frame++ % frames.length]} setting up feynman... ${elapsed}s`);
 	}, 80);
 
-	const result = installWorkspacePackages(packageSpecs);
+	const result = installWorkspacePackages(supportedPackageSpecs);
 
 	clearInterval(spinner);
 	const elapsed = Math.round((Date.now() - start) / 1000);
@@ -203,7 +414,9 @@ function ensurePackageWorkspace() {
 	if (!result) {
 		process.stderr.write(`\r✗ setup failed (${elapsed}s)\n`);
 	} else {
-		process.stderr.write(`\r✓ feynman ready (${elapsed}s)\n`);
+		process.stderr.write("\r\x1b[2K");
+		writeWorkspaceManifest(supportedPackageSpecs);
+		ensureBundledPackageLinks(supportedPackageSpecs);
 	}
 }
 
@@ -230,6 +443,19 @@ function ensurePandoc() {
 
 ensurePandoc();
 
+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") {
@@ -247,10 +473,68 @@ for (const entryPath of [cliPath, bunCliPath].filter(Boolean)) {
 		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 (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)) {
@@ -266,6 +550,18 @@ if (interactiveModePath && existsSync(interactiveModePath)) {
 	}
 }
 
+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 = [
@@ -441,6 +737,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");';
@@ -452,6 +763,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");
@@ -464,25 +776,24 @@ 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;
 
 if (alphaHubAuthPath && existsSync(alphaHubAuthPath)) {
-	let source = readFileSync(alphaHubAuthPath, "utf8");
-	const oldSuccess = "'<html><body><h2>Logged in to Alpha Hub</h2><p>You can close this tab.</p></body></html>'";
-	const oldError = "'<html><body><h2>Login failed</h2><p>You can close this tab.</p></body></html>'";
-	const bodyAttr = `style="font-family:system-ui,sans-serif;text-align:center;padding-top:20vh;background:#050a08;color:#f0f5f2"`;
-	const logo = `<h1 style="font-family:monospace;font-size:48px;color:#34d399;margin:0">feynman</h1>`;
-	const newSuccess = `'<html><body ${bodyAttr}>${logo}<h2 style="color:#34d399;margin-top:16px">Logged in</h2><p style="color:#8aaa9a">You can close this tab.</p></body></html>'`;
-	const newError = `'<html><body ${bodyAttr}>${logo}<h2 style="color:#ef4444;margin-top:16px">Login failed</h2><p style="color:#8aaa9a">You can close this tab.</p></body></html>'`;
-	if (source.includes(oldSuccess)) {
-		source = source.replace(oldSuccess, newSuccess);
+	const source = readFileSync(alphaHubAuthPath, "utf8");
+	const patched = patchAlphaHubAuthSource(source);
+	if (patched !== source) {
+		writeFileSync(alphaHubAuthPath, patched, "utf8");
 	}
-	if (source.includes(oldError)) {
-		source = source.replace(oldError, newError);
-	}
-	writeFileSync(alphaHubAuthPath, source, "utf8");
 }
 
 if (existsSync(piMemoryPath)) {

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

@@ -11,7 +11,7 @@ Use the `alpha` CLI via bash for all paper research operations.
 
 | Command | Description |
 |---------|-------------|
-| `alpha search "<query>"` | Search papers. Modes: `--mode semantic`, `--mode keyword`, `--mode agentic` |
+| `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 |
@@ -22,7 +22,7 @@ Use the `alpha` CLI via bash for all paper research operations.
 
 ## Auth
 
-Run `alpha login` to authenticate with alphaXiv. Check status with `alpha status`.
+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
 

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/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/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/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/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,9 +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, "skills"), resolve(agentDir, "skills"), 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

@@ -1,6 +1,6 @@
 import "dotenv/config";
 
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { fileURLToPath } from "node:url";
@@ -11,25 +11,33 @@ import {
 	login as loginAlpha,
 	logout as logoutAlpha,
 } from "@companion-ai/alpha-hub/lib";
-import { AuthStorage, DefaultPackageManager, ModelRegistry, SettingsManager } from "@mariozechner/pi-coding-agent";
+import { 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 { installPackageSources, updateConfiguredPackages } from "./pi/package-ops.js";
+import { MAX_NATIVE_PACKAGE_NODE_MAJOR } from "./pi/package-presets.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 { buildModelStatusSnapshotFromRecords, getAvailableModelRecords, getSupportedModelRecords } from "./model/catalog.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 { ASH, printAsciiHeader, printInfo, printPanel, printSection, RESET, SAGE } from "./ui/terminal.js";
+import { createModelRegistry } from "./model/registry.js";
 import {
 	cliCommandSections,
 	formatCliWorkflowUsage,
@@ -124,7 +132,13 @@ async function handleModelCommand(subcommand: string | undefined, args: string[]
 	}
 
 	if (subcommand === "login") {
+		if (args[0]) {
+			// Specific provider given - resolve OAuth vs API-key setup automatically
 			await loginModelProvider(feynmanAuthPath, args[0], feynmanSettingsPath);
+		} else {
+			// No provider specified - show auth method choice
+			await authenticateModelProvider(feynmanAuthPath, feynmanSettingsPath);
+		}
 		return;
 	}
 
@@ -136,39 +150,67 @@ async function handleModelCommand(subcommand: string | undefined, args: string[]
 	if (subcommand === "set") {
 		const spec = args[0];
 		if (!spec) {
-			throw new Error("Usage: feynman model set <provider/model>");
+			throw new Error("Usage: feynman model set <provider/model|provider:model>");
 		}
 		setDefaultModelSpec(feynmanSettingsPath, feynmanAuthPath, spec);
 		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> {
-	const settingsManager = SettingsManager.create(workingDir, feynmanAgentDir);
-	const packageManager = new DefaultPackageManager({
-		cwd: workingDir,
-		agentDir: feynmanAgentDir,
-		settingsManager,
-	});
-
-	packageManager.setProgressCallback((event) => {
-		if (event.type === "start") {
-			console.log(`Updating ${event.source}...`);
-		} else if (event.type === "complete") {
-			console.log(`Updated ${event.source}`);
-		} else if (event.type === "error") {
-			console.error(`Failed to update ${event.source}: ${event.message ?? "unknown error"}`);
-		}
-	});
-
-	await packageManager.update(source);
-	await settingsManager.flush();
+	try {
+		const result = await updateConfiguredPackages(workingDir, feynmanAgentDir, source);
+		if (result.updated.length === 0) {
 			console.log("All packages up to date.");
+			return;
+		}
+
+		for (const updatedSource of result.updated) {
+			console.log(`Updated ${updatedSource}`);
+		}
+		for (const skippedSource of result.skipped) {
+			console.log(`Skipped ${skippedSource} on Node ${process.versions.node} (native packages are only supported through Node ${MAX_NATIVE_PACKAGE_NODE_MAJOR}.x).`);
+		}
+		console.log("All packages up to date.");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (message.includes("No supported package manager found")) {
+			console.log("No package manager is available for live package updates.");
+			console.log("If you installed the standalone app, rerun the installer to get newer bundled packages.");
+			return;
+		}
+
+		throw error;
+	}
 }
 
 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
@@ -208,38 +250,67 @@ async function handlePackagesCommand(subcommand: string | undefined, args: strin
 		throw new Error(`Unknown package preset: ${target}`);
 	}
 
-	const packageManager = new DefaultPackageManager({
-		cwd: workingDir,
-		agentDir: feynmanAgentDir,
-		settingsManager,
-	});
-	packageManager.setProgressCallback((event) => {
-		if (event.type === "start") {
-			console.log(`Installing ${event.source}...`);
-		} else if (event.type === "complete") {
-			console.log(`Installed ${event.source}`);
-		} else if (event.type === "error") {
-			console.error(`Failed to install ${event.source}: ${event.message ?? "unknown error"}`);
+	const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+	const isStandaloneBundle = !existsSync(resolve(appRoot, ".feynman", "runtime-workspace.tgz")) && existsSync(resolve(appRoot, ".feynman", "npm"));
+	if (target === "generative-ui" && process.platform === "darwin" && isStandaloneBundle) {
+		console.log("The generative-ui preset is currently unavailable in the standalone macOS bundle.");
+		console.log("Its native glimpseui dependency fails to compile reliably in that environment.");
+		console.log("If you need generative-ui, install Feynman through npm instead of the standalone bundle.");
+		return;
 	}
-	});
 
+	const pendingSources = sources.filter((source) => !configuredSources.has(source));
 	for (const source of sources) {
 		if (configuredSources.has(source)) {
 			console.log(`${source} already installed`);
-			continue;
 		}
-		await packageManager.install(source);
+	}
+
+	if (pendingSources.length === 0) {
+		console.log("Optional packages installed.");
+		return;
+	}
+
+	try {
+		const result = await installPackageSources(workingDir, feynmanAgentDir, pendingSources, { persist: true });
+		for (const skippedSource of result.skipped) {
+			console.log(`Skipped ${skippedSource} on Node ${process.versions.node} (native packages are only supported through Node ${MAX_NATIVE_PACKAGE_NODE_MAJOR}.x).`);
 		}
 		await settingsManager.flush();
 		console.log("Optional packages installed.");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (message.includes("No supported package manager found")) {
+			console.log("No package manager is available for optional package installs.");
+			console.log("Install npm, pnpm, or bun, or rerun the standalone installer for bundled package updates.");
+			return;
+		}
+
+		throw error;
+	}
 }
 
-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}`);
 }
 
@@ -275,6 +346,24 @@ export function resolveInitialPrompt(
 	return undefined;
 }
 
+export function shouldRunInteractiveSetup(
+	explicitModelSpec: string | undefined,
+	currentModelSpec: string | undefined,
+	isInteractiveTerminal: boolean,
+	authPath: string,
+): boolean {
+	if (explicitModelSpec || !isInteractiveTerminal) {
+		return false;
+	}
+
+	const status = buildModelStatusSnapshotFromRecords(
+		getSupportedModelRecords(authPath),
+		getAvailableModelRecords(authPath),
+		currentModelSpec,
+	);
+	return !status.currentValid;
+}
+
 export async function main(): Promise<void> {
 	const here = dirname(fileURLToPath(import.meta.url));
 	const appRoot = resolve(here, "..");
@@ -297,9 +386,11 @@ export async function main(): Promise<void> {
 			"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" },
@@ -406,7 +497,7 @@ export async function main(): Promise<void> {
 	}
 
 	if (command === "search") {
-		handleSearchCommand(rest[0]);
+		handleSearchCommand(rest[0], rest.slice(1));
 		return;
 	}
 
@@ -426,15 +517,32 @@ 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}`);
 		}
 	}
 
-	if (!explicitModelSpec && !getCurrentModelSpec(feynmanSettingsPath) && process.stdin.isTTY && process.stdout.isTTY) {
+	const currentModelSpec = getCurrentModelSpec(feynmanSettingsPath);
+	if (shouldRunInteractiveSetup(
+		explicitModelSpec,
+		currentModelSpec,
+		Boolean(process.stdin.isTTY && process.stdout.isTTY),
+		feynmanAuthPath,
+	)) {
 		await runSetup({
 			settingsPath: feynmanSettingsPath,
 			bundledSettingsPath,
@@ -456,6 +564,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 { promptChoice, promptSelect, promptText, type PromptSelectOption } 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(
@@ -48,17 +55,558 @@ async function selectOAuthProvider(authPath: string, action: "login" | "logout")
 		return providers[0];
 	}
 
-	const choices = providers.map((provider) => `${provider.id} — ${provider.name ?? provider.id}`);
-	choices.push("Cancel");
-	const selection = await promptChoice(`Choose an OAuth provider to ${action}:`, choices, 0);
-	if (selection >= providers.length) {
+	const selection = await promptSelect<OAuthProviderInfo | "cancel">(
+		`Choose an OAuth provider to ${action}:`,
+		[
+			...providers.map((provider) => ({
+				value: provider,
+				label: provider.name ?? provider.id,
+				hint: provider.id,
+			})),
+			{ value: "cancel", label: "Cancel" },
+		],
+		providers[0],
+	);
+	if (selection === "cancel") {
 		return undefined;
 	}
-	return providers[selection];
+	return selection;
+}
+
+type ApiKeyProviderInfo = {
+	id: string;
+	label: string;
+	envVar?: string;
+};
+
+const API_KEY_PROVIDERS: ApiKeyProviderInfo[] = [
+	{ 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: "__custom__", label: "Custom provider (local/self-hosted/proxy)" },
+	{ id: "amazon-bedrock", label: "Amazon Bedrock (AWS credential chain)" },
+	{ 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" },
+];
+
+function resolveApiKeyProvider(input: string): ApiKeyProviderInfo | undefined {
+	const normalizedInput = normalizeProviderId(input);
+	if (!normalizedInput) {
+		return undefined;
+	}
+	return API_KEY_PROVIDERS.find((provider) => provider.id === normalizedInput);
+}
+
+export function resolveModelProviderForCommand(
+	authPath: string,
+	input: string,
+): { kind: "oauth" | "api-key"; id: string } | undefined {
+	const oauthProvider = resolveOAuthProvider(authPath, input);
+	if (oauthProvider) {
+		return { kind: "oauth", id: oauthProvider.id };
+	}
+
+	const apiKeyProvider = resolveApiKeyProvider(input);
+	if (apiKeyProvider) {
+		return { kind: "api-key", id: apiKeyProvider.id };
+	}
+
+	return undefined;
+}
+
+async function selectApiKeyProvider(): Promise<ApiKeyProviderInfo | undefined> {
+	const options: PromptSelectOption<ApiKeyProviderInfo | "cancel">[] = API_KEY_PROVIDERS.map((provider) => ({
+		value: provider,
+		label: provider.label,
+		hint: provider.id === "__custom__"
+			? "Ollama, vLLM, LM Studio, proxies"
+			: provider.envVar ?? provider.id,
+	}));
+	options.push({ value: "cancel", label: "Cancel" });
+
+	const defaultProvider = API_KEY_PROVIDERS.find((provider) => provider.id === "openai") ?? API_KEY_PROVIDERS[0];
+	const selection = await promptSelect("Choose an API-key provider:", options, defaultProvider);
+	if (selection === "cancel") {
+		return undefined;
+	}
+	return 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 verifyBedrockCredentialChain(): Promise<void> {
+	const { defaultProvider } = await import("@aws-sdk/credential-provider-node");
+	const credentials = await defaultProvider({})();
+	if (!credentials?.accessKeyId || !credentials?.secretAccessKey) {
+		throw new Error("AWS credential chain resolved without usable Bedrock credentials.");
+	}
+}
+
+async function configureBedrockProvider(authPath: string): Promise<boolean> {
+	printSection("AWS Credentials: Amazon Bedrock");
+	printInfo("Feynman will verify the AWS SDK credential chain used by Pi's Bedrock provider.");
+	printInfo("Supported sources include AWS_PROFILE, ~/.aws credentials/config, SSO, ECS/IRSA, and EC2 instance roles.");
+
+	try {
+		await verifyBedrockCredentialChain();
+		AuthStorage.create(authPath).set("amazon-bedrock", { type: "api_key", key: "<authenticated>" });
+		printSuccess("Verified AWS credential chain and marked Amazon Bedrock as configured.");
+		printInfo("Use `feynman model list` to see available Bedrock models.");
+		return true;
+	} catch (error) {
+		printWarning(`AWS credential verification failed: ${error instanceof Error ? error.message : String(error)}`);
+		printInfo("Configure AWS credentials first, for example:");
+		printInfo("  export AWS_PROFILE=default");
+		printInfo("  # or set AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY");
+		printInfo("  # or use an EC2/ECS/IRSA role with valid Bedrock access");
+		return false;
+	}
+}
+
+function maybeSetRecommendedDefaultModel(settingsPath: string | undefined, authPath: string): void {
+	if (!settingsPath) {
+		return;
+	}
+
+	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);
+		}
+	}
+}
+
+async function configureApiKeyProvider(authPath: string, providerId?: string): Promise<boolean> {
+	const provider = providerId ? resolveApiKeyProvider(providerId) : await selectApiKeyProvider();
+	if (!provider) {
+		if (providerId) {
+			throw new Error(`Unknown API-key model provider: ${providerId}`);
+		}
+		printInfo("API key setup cancelled.");
+		return false;
+	}
+
+	if (provider.id === "amazon-bedrock") {
+		return configureBedrockProvider(authPath);
+	}
+
+	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();
+	const normalizedInput = input.trim().replace(/^([^/:]+):(.+)$/, "$1/$2").toLowerCase();
 	if (!normalizedInput) {
 		return undefined;
 	}
@@ -74,6 +622,17 @@ function resolveAvailableModelSpec(authPath: string, input: string): string | un
 		return `${exactIdMatches[0]!.provider}/${exactIdMatches[0]!.id}`;
 	}
 
+	// When multiple providers expose the same bare model ID, prefer providers the
+	// user explicitly configured in auth storage.
+	if (exactIdMatches.length > 1) {
+		const authData = readJson(authPath) as Record<string, unknown>;
+		const configuredProviders = new Set(Object.keys(authData));
+		const configuredMatches = exactIdMatches.filter((model) => configuredProviders.has(model.provider));
+		if (configuredMatches.length === 1) {
+			return `${configuredMatches[0]!.provider}/${configuredMatches[0]!.id}`;
+		}
+	}
+
 	return undefined;
 }
 
@@ -110,14 +669,52 @@ 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 = [
+		"OAuth login (recommended: ChatGPT Plus/Pro, Claude Pro/Max, Copilot, ...)",
+		"API key or custom provider (OpenAI, Anthropic, Google, local/self-hosted, ...)",
+		"Cancel",
+	];
+	const selection = await promptChoice("How do you want to authenticate?", choices, 0);
+
+	if (selection === 0) {
+		return loginModelProvider(authPath, undefined, settingsPath);
+	}
+
+	if (selection === 1) {
+		const configured = await configureApiKeyProvider(authPath);
+		if (configured) {
+			maybeSetRecommendedDefaultModel(settingsPath, authPath);
+		}
+		return configured;
+	}
+
+	printInfo("Authentication cancelled.");
+	return false;
+}
+
+export async function loginModelProvider(authPath: string, providerId?: string, settingsPath?: string): Promise<boolean> {
+	if (providerId) {
+		const resolvedProvider = resolveModelProviderForCommand(authPath, providerId);
+		if (!resolvedProvider) {
+			throw new Error(`Unknown model provider: ${providerId}`);
+		}
+		if (resolvedProvider.kind === "api-key") {
+			const configured = await configureApiKeyProvider(authPath, resolvedProvider.id);
+			if (configured) {
+				maybeSetRecommendedDefaultModel(settingsPath, authPath);
+			}
+			return configured;
+		}
+	}
+
 	const provider = providerId ? resolveOAuthProvider(authPath, providerId) : await selectOAuthProvider(authPath, "login");
 	if (!provider) {
 		if (providerId) {
-			throw new Error(`Unknown OAuth model provider: ${providerId}`);
+			throw new Error(`Unknown model provider: ${providerId}`);
 		}
 		printInfo("Login cancelled.");
-		return;
+		return false;
 	}
 
 	const authStorage = AuthStorage.create(authPath);
@@ -126,7 +723,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);
 			}
@@ -145,33 +748,38 @@ export async function loginModelProvider(authPath: string, providerId?: string,
 
 	printSuccess(`Model provider login complete: ${provider.id}`);
 
-	if (settingsPath) {
-		const currentSpec = getCurrentModelSpec(settingsPath);
-		const available = getAvailableModelRecords(authPath);
-		const currentValid = currentSpec
-			? available.some((m) => `${m.provider}/${m.id}` === currentSpec)
-			: false;
+	maybeSetRecommendedDefaultModel(settingsPath, authPath);
 
-		if ((!currentSpec || !currentValid) && available.length > 0) {
-			const recommended = chooseRecommendedModel(authPath);
-			if (recommended) {
-				setDefaultModelSpec(settingsPath, authPath, recommended.spec);
-			}
-		}
-	}
+	return true;
 }
 
 export async function logoutModelProvider(authPath: string, providerId?: string): Promise<void> {
-	const provider = providerId ? resolveOAuthProvider(authPath, providerId) : await selectOAuthProvider(authPath, "logout");
-	if (!provider) {
+	const authStorage = AuthStorage.create(authPath);
 	if (providerId) {
-			throw new Error(`Unknown OAuth model provider: ${providerId}`);
+		const resolvedProvider = resolveModelProviderForCommand(authPath, providerId);
+		if (resolvedProvider) {
+			authStorage.logout(resolvedProvider.id);
+			printSuccess(`Model provider logout complete: ${resolvedProvider.id}`);
+			return;
 		}
+
+		const normalizedProviderId = normalizeProviderId(providerId);
+		if (authStorage.has(normalizedProviderId)) {
+			authStorage.logout(normalizedProviderId);
+			printSuccess(`Model provider logout complete: ${normalizedProviderId}`);
+			return;
+		}
+
+		throw new Error(`Unknown model provider: ${providerId}`);
+	}
+
+	const provider = await selectOAuthProvider(authPath, "logout");
+	if (!provider) {
 		printInfo("Logout cancelled.");
 		return;
 	}
 
-	AuthStorage.create(authPath).logout(provider.id);
+	authStorage.logout(provider.id);
 	printSuccess(`Model provider logout complete: ${provider.id}`);
 }
 
@@ -193,11 +801,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 = [
+			"OAuth login (recommended: ChatGPT Plus/Pro, Claude Pro/Max, Copilot, ...)",
+			"API key or custom provider (OpenAI, Anthropic, ZAI, Kimi, MiniMax, ...)",
+			"Cancel",
+		];
+		const selection = await promptChoice("Choose how to configure model access:", choices, 0);
+		if (selection === 0) {
+			const loggedIn = await loginModelProvider(authPath, undefined, settingsPath);
+			if (!loggedIn) {
+				status = collectModelStatus(settingsPath, authPath);
+				continue;
+			}
+		} else if (selection === 1) {
+			const configured = await configureApiKeyProvider(authPath);
+			if (!configured) {
+				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,41 @@
+import { dirname, resolve } from "node:path";
+
+import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
+import { getModels } from "@mariozechner/pi-ai";
+import { anthropicOAuthProvider } from "@mariozechner/pi-ai/oauth";
+
+export function getModelsJsonPath(authPath: string): string {
+	return resolve(dirname(authPath), "models.json");
+}
+
+function registerFeynmanModelOverlays(modelRegistry: ModelRegistry): void {
+	const anthropicModels = getModels("anthropic");
+	if (anthropicModels.some((model) => model.id === "claude-opus-4-7")) {
+		return;
+	}
+
+	const opus46 = anthropicModels.find((model) => model.id === "claude-opus-4-6");
+	if (!opus46) {
+		return;
+	}
+
+	modelRegistry.registerProvider("anthropic", {
+		baseUrl: "https://api.anthropic.com",
+		api: "anthropic-messages",
+		oauth: anthropicOAuthProvider,
+		models: [
+			...anthropicModels,
+			{
+				...opus46,
+				id: "claude-opus-4-7",
+				name: "Claude Opus 4.7",
+			},
+		],
+	});
+}
+
+export function createModelRegistry(authPath: string): ModelRegistry {
+	const registry = ModelRegistry.create(AuthStorage.create(authPath), getModelsJsonPath(authPath));
+	registerFeynmanModelOverlays(registry);
+	return registry;
+}

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-ops.ts

@@ -0,0 +1,501 @@
+import { spawn } from "node:child_process";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+import { DefaultPackageManager, SettingsManager } from "@mariozechner/pi-coding-agent";
+
+import { NATIVE_PACKAGE_SOURCES, supportsNativePackageSources } from "./package-presets.js";
+import { applyFeynmanPackageManagerEnv, getFeynmanNpmPrefixPath } from "./runtime.js";
+import { getPathWithCurrentNode, resolveExecutable } from "../system/executables.js";
+
+type PackageScope = "user" | "project";
+
+type ConfiguredPackage = {
+	source: string;
+	scope: PackageScope;
+	filtered: boolean;
+	installedPath?: string;
+};
+
+type NpmSource = {
+	name: string;
+	source: string;
+	spec: string;
+	pinned: boolean;
+};
+
+export type MissingConfiguredPackageSummary = {
+	missing: ConfiguredPackage[];
+	bundled: ConfiguredPackage[];
+};
+
+export type InstallPackageSourcesResult = {
+	installed: string[];
+	skipped: string[];
+};
+
+export type UpdateConfiguredPackagesResult = {
+	updated: string[];
+	skipped: string[];
+};
+
+const FILTERED_INSTALL_OUTPUT_PATTERNS = [
+	/npm warn deprecated node-domexception@1\.0\.0/i,
+	/npm notice/i,
+	/^(added|removed|changed) \d+ packages?( in .+)?$/i,
+	/^(\d+ )?packages are looking for funding$/i,
+	/^run `npm fund` for details$/i,
+];
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+function createPackageContext(workingDir: string, agentDir: string) {
+	applyFeynmanPackageManagerEnv(agentDir);
+	process.env.PATH = getPathWithCurrentNode(process.env.PATH);
+	const settingsManager = SettingsManager.create(workingDir, agentDir);
+	const packageManager = new DefaultPackageManager({
+		cwd: workingDir,
+		agentDir,
+		settingsManager,
+	});
+
+	return {
+		settingsManager,
+		packageManager,
+	};
+}
+
+function shouldSkipNativeSource(source: string, version = process.versions.node): boolean {
+	return !supportsNativePackageSources(version) && NATIVE_PACKAGE_SOURCES.includes(source as (typeof NATIVE_PACKAGE_SOURCES)[number]);
+}
+
+function filterUnsupportedSources(sources: string[], version = process.versions.node): { supported: string[]; skipped: string[] } {
+	const supported: string[] = [];
+	const skipped: string[] = [];
+
+	for (const source of sources) {
+		if (shouldSkipNativeSource(source, version)) {
+			skipped.push(source);
+			continue;
+		}
+		supported.push(source);
+	}
+
+	return { supported, skipped };
+}
+
+function relayFilteredOutput(chunk: Buffer | string, writer: NodeJS.WriteStream): void {
+	const text = chunk.toString();
+	for (const line of text.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		if (FILTERED_INSTALL_OUTPUT_PATTERNS.some((pattern) => pattern.test(line.trim()))) {
+			continue;
+		}
+		writer.write(`${line}\n`);
+	}
+}
+
+function parseNpmSource(source: string): NpmSource | undefined {
+	if (!source.startsWith("npm:")) {
+		return undefined;
+	}
+
+	const spec = source.slice("npm:".length).trim();
+	const match = spec.match(/^(@?[^@]+(?:\/[^@]+)?)(?:@(.+))?$/);
+	const name = match?.[1] ?? spec;
+	const version = match?.[2];
+
+	return {
+		name,
+		source,
+		spec,
+		pinned: Boolean(version),
+	};
+}
+
+function dedupeNpmSources(sources: string[], updateToLatest: boolean): string[] {
+	const specs = new Map<string, string>();
+
+	for (const source of sources) {
+		const parsed = parseNpmSource(source);
+		if (!parsed) continue;
+
+		specs.set(parsed.name, updateToLatest && !parsed.pinned ? `${parsed.name}@latest` : parsed.spec);
+	}
+
+	return [...specs.values()];
+}
+
+function ensureProjectInstallRoot(workingDir: string): string {
+	const installRoot = resolve(workingDir, ".feynman", "npm");
+	mkdirSync(installRoot, { recursive: true });
+
+	const ignorePath = join(installRoot, ".gitignore");
+	if (!existsSync(ignorePath)) {
+		writeFileSync(ignorePath, "*\n!.gitignore\n", "utf8");
+	}
+
+	const packageJsonPath = join(installRoot, "package.json");
+	if (!existsSync(packageJsonPath)) {
+		writeFileSync(packageJsonPath, JSON.stringify({ name: "feynman-packages", private: true }, null, 2) + "\n", "utf8");
+	}
+
+	return installRoot;
+}
+
+function resolveAdjacentNpmExecutable(): string | undefined {
+	const executableName = process.platform === "win32" ? "npm.cmd" : "npm";
+	const candidate = resolve(dirname(process.execPath), executableName);
+	return existsSync(candidate) ? candidate : undefined;
+}
+
+function resolvePackageManagerCommand(settingsManager: SettingsManager): { command: string; args: string[] } | undefined {
+	const configured = settingsManager.getNpmCommand();
+	if (!configured || configured.length === 0) {
+		const adjacentNpm = resolveAdjacentNpmExecutable() ?? resolveExecutable("npm");
+		return adjacentNpm ? { command: adjacentNpm, args: [] } : undefined;
+	}
+
+	const [command = "npm", ...args] = configured;
+	if (!command) {
+		return undefined;
+	}
+
+	const executable = resolveExecutable(command);
+	if (!executable) {
+		return undefined;
+	}
+
+	return { command: executable, args };
+}
+
+async function runPackageManagerInstall(
+	settingsManager: SettingsManager,
+	workingDir: string,
+	agentDir: string,
+	scope: PackageScope,
+	specs: string[],
+): Promise<void> {
+	if (specs.length === 0) {
+		return;
+	}
+
+	const packageManagerCommand = resolvePackageManagerCommand(settingsManager);
+	if (!packageManagerCommand) {
+		throw new Error("No supported package manager found. Install npm, pnpm, or bun, or configure `npmCommand`.");
+	}
+
+	const args = [
+		...packageManagerCommand.args,
+		"install",
+		"--no-audit",
+		"--no-fund",
+		"--legacy-peer-deps",
+		"--loglevel",
+		"error",
+	];
+
+	if (scope === "user") {
+		args.push("-g", "--prefix", getFeynmanNpmPrefixPath(agentDir));
+	} else {
+		args.push("--prefix", ensureProjectInstallRoot(workingDir));
+	}
+
+	args.push(...specs);
+
+	await new Promise<void>((resolvePromise, reject) => {
+		const child = spawn(packageManagerCommand.command, args, {
+			cwd: scope === "user" ? agentDir : workingDir,
+			stdio: ["ignore", "pipe", "pipe"],
+			env: {
+				...process.env,
+				PATH: getPathWithCurrentNode(process.env.PATH),
+			},
+		});
+
+		child.stdout?.on("data", (chunk) => relayFilteredOutput(chunk, process.stdout));
+		child.stderr?.on("data", (chunk) => relayFilteredOutput(chunk, process.stderr));
+
+		child.on("error", reject);
+		child.on("exit", (code) => {
+			if ((code ?? 1) !== 0) {
+				const installingGenerativeUi = specs.some((spec) => spec.startsWith("pi-generative-ui"));
+				if (installingGenerativeUi && process.platform === "darwin") {
+					reject(
+						new Error(
+							"Installing pi-generative-ui failed. Its native glimpseui dependency did not compile against the current macOS/Xcode toolchain. Try the npm-installed Feynman path with your local Node toolchain or skip this optional preset for now.",
+						),
+					);
+					return;
+				}
+				reject(new Error(`${packageManagerCommand.command} install failed with code ${code ?? 1}`));
+				return;
+			}
+
+			resolvePromise();
+		});
+	});
+}
+
+function groupConfiguredNpmSources(packages: ConfiguredPackage[]): Record<PackageScope, string[]> {
+	return {
+		user: packages.filter((entry) => entry.scope === "user").map((entry) => entry.source),
+		project: packages.filter((entry) => entry.scope === "project").map((entry) => entry.source),
+	};
+}
+
+function isBundledWorkspacePackagePath(installedPath: string | undefined, appRoot: string): boolean {
+	if (!installedPath) {
+		return false;
+	}
+
+	const bundledRoot = resolve(appRoot, ".feynman", "npm", "node_modules");
+	return installedPath.startsWith(bundledRoot);
+}
+
+export function getMissingConfiguredPackages(
+	workingDir: string,
+	agentDir: string,
+	appRoot: string,
+): MissingConfiguredPackageSummary {
+	const { packageManager } = createPackageContext(workingDir, agentDir);
+	const configured = packageManager.listConfiguredPackages();
+
+	return configured.reduce<MissingConfiguredPackageSummary>(
+		(summary, entry) => {
+			if (entry.installedPath) {
+				if (isBundledWorkspacePackagePath(entry.installedPath, appRoot)) {
+					summary.bundled.push(entry);
+				}
+				return summary;
+			}
+
+			summary.missing.push(entry);
+			return summary;
+		},
+		{ missing: [], bundled: [] },
+	);
+}
+
+export async function installPackageSources(
+	workingDir: string,
+	agentDir: string,
+	sources: string[],
+	options?: { local?: boolean; persist?: boolean },
+): Promise<InstallPackageSourcesResult> {
+	const { settingsManager, packageManager } = createPackageContext(workingDir, agentDir);
+	const scope: PackageScope = options?.local ? "project" : "user";
+	const installed: string[] = [];
+
+	const bundledSeeded = scope === "user" ? seedBundledWorkspacePackages(agentDir, APP_ROOT, sources) : [];
+	installed.push(...bundledSeeded);
+	const remainingSources = sources.filter((source) => !bundledSeeded.includes(source));
+	const grouped = groupConfiguredNpmSources(
+		remainingSources.map((source) => ({
+			source,
+			scope,
+			filtered: false,
+		})),
+	);
+	const { supported: supportedUserSources, skipped } = filterUnsupportedSources(grouped.user);
+	const { supported: supportedProjectSources, skipped: skippedProject } = filterUnsupportedSources(grouped.project);
+	skipped.push(...skippedProject);
+
+	const supportedNpmSources = scope === "user" ? supportedUserSources : supportedProjectSources;
+	if (supportedNpmSources.length > 0) {
+		await runPackageManagerInstall(settingsManager, workingDir, agentDir, scope, dedupeNpmSources(supportedNpmSources, false));
+		installed.push(...supportedNpmSources);
+	}
+
+	for (const source of sources) {
+		if (parseNpmSource(source)) {
+			continue;
+		}
+
+		await packageManager.install(source, { local: options?.local });
+		installed.push(source);
+	}
+
+	if (options?.persist) {
+		for (const source of installed) {
+			if (packageManager.addSourceToSettings(source, { local: options?.local })) {
+				continue;
+			}
+			skipped.push(source);
+		}
+		await settingsManager.flush();
+	}
+
+	return { installed, skipped };
+}
+
+export async function updateConfiguredPackages(
+	workingDir: string,
+	agentDir: string,
+	source?: string,
+): Promise<UpdateConfiguredPackagesResult> {
+	const { settingsManager, packageManager } = createPackageContext(workingDir, agentDir);
+
+	if (source) {
+		await packageManager.update(source);
+		return { updated: [source], skipped: [] };
+	}
+
+	const availableUpdates = await packageManager.checkForAvailableUpdates();
+	if (availableUpdates.length === 0) {
+		return { updated: [], skipped: [] };
+	}
+
+	const npmUpdatesByScope: Record<PackageScope, string[]> = { user: [], project: [] };
+	const gitUpdates: string[] = [];
+	const skipped: string[] = [];
+
+	for (const entry of availableUpdates) {
+		if (entry.type === "npm") {
+			if (shouldSkipNativeSource(entry.source)) {
+				skipped.push(entry.source);
+				continue;
+			}
+			npmUpdatesByScope[entry.scope].push(entry.source);
+			continue;
+		}
+
+		gitUpdates.push(entry.source);
+	}
+
+	for (const scope of ["user", "project"] as const) {
+		const sources = npmUpdatesByScope[scope];
+		if (sources.length === 0) continue;
+
+		await runPackageManagerInstall(settingsManager, workingDir, agentDir, scope, dedupeNpmSources(sources, true));
+	}
+
+	for (const gitSource of gitUpdates) {
+		await packageManager.update(gitSource);
+	}
+
+	return {
+		updated: availableUpdates
+			.map((entry) => entry.source)
+			.filter((source) => !skipped.includes(source)),
+		skipped,
+	};
+}
+
+function ensureParentDir(path: string): void {
+	mkdirSync(dirname(path), { recursive: true });
+}
+
+function pathsMatchSymlinkTarget(linkPath: string, targetPath: string): boolean {
+	try {
+		if (!lstatSync(linkPath).isSymbolicLink()) {
+			return false;
+		}
+		return resolve(dirname(linkPath), readlinkSync(linkPath)) === targetPath;
+	} catch {
+		return false;
+	}
+}
+
+function linkDirectory(linkPath: string, targetPath: string): void {
+	if (pathsMatchSymlinkTarget(linkPath, targetPath)) {
+		return;
+	}
+
+	try {
+		if (existsSync(linkPath) && lstatSync(linkPath).isSymbolicLink()) {
+			rmSync(linkPath, { force: true });
+		}
+	} catch {}
+
+	if (existsSync(linkPath)) {
+		return;
+	}
+
+	ensureParentDir(linkPath);
+	try {
+		symlinkSync(targetPath, linkPath, process.platform === "win32" ? "junction" : "dir");
+	} catch {
+		// Fallback for filesystems that do not allow symlinks.
+		if (!existsSync(linkPath)) {
+			cpSync(targetPath, linkPath, { recursive: true });
+		}
+	}
+}
+
+function packageNameToPath(root: string, packageName: string): string {
+	return resolve(root, packageName);
+}
+
+function packageDependencyExists(packagePath: string, globalNodeModulesRoot: string, dependency: string): boolean {
+	return existsSync(packageNameToPath(resolve(packagePath, "node_modules"), dependency)) ||
+		existsSync(packageNameToPath(globalNodeModulesRoot, dependency));
+}
+
+function installedPackageLooksUsable(packagePath: string, globalNodeModulesRoot: string): boolean {
+	if (!existsSync(resolve(packagePath, "package.json"))) {
+		return false;
+	}
+
+	try {
+		const pkg = JSON.parse(readFileSync(resolve(packagePath, "package.json"), "utf8")) as {
+			dependencies?: Record<string, string>;
+		};
+		const dependencies = Object.keys(pkg.dependencies ?? {});
+		return dependencies.every((dependency) => packageDependencyExists(packagePath, globalNodeModulesRoot, dependency));
+	} catch {
+		return false;
+	}
+}
+
+function replaceBrokenPackageWithBundledCopy(targetPath: string, bundledPackagePath: string, globalNodeModulesRoot: string): boolean {
+	if (!existsSync(targetPath)) {
+		return false;
+	}
+	if (pathsMatchSymlinkTarget(targetPath, bundledPackagePath)) {
+		return false;
+	}
+	if (installedPackageLooksUsable(targetPath, globalNodeModulesRoot)) {
+		return false;
+	}
+
+	rmSync(targetPath, { recursive: true, force: true });
+	linkDirectory(targetPath, bundledPackagePath);
+	return true;
+}
+
+export function seedBundledWorkspacePackages(
+	agentDir: string,
+	appRoot: string,
+	sources: string[],
+): string[] {
+	const bundledNodeModulesRoot = resolve(appRoot, ".feynman", "npm", "node_modules");
+	if (!existsSync(bundledNodeModulesRoot)) {
+		return [];
+	}
+
+	const globalNodeModulesRoot = resolve(getFeynmanNpmPrefixPath(agentDir), "lib", "node_modules");
+	const seeded: string[] = [];
+
+	for (const source of sources) {
+		if (shouldSkipNativeSource(source)) continue;
+
+		const parsed = parseNpmSource(source);
+		if (!parsed) continue;
+
+		const bundledPackagePath = resolve(bundledNodeModulesRoot, parsed.name);
+		if (!existsSync(bundledPackagePath)) continue;
+
+		const targetPath = resolve(globalNodeModulesRoot, parsed.name);
+		if (replaceBrokenPackageWithBundledCopy(targetPath, bundledPackagePath, globalNodeModulesRoot)) {
+			seeded.push(source);
+			continue;
+		}
+		if (!existsSync(targetPath)) {
+			linkDirectory(targetPath, bundledPackagePath);
+			seeded.push(source);
+		}
+	}
+
+	return seeded;
+}

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",
@@ -16,6 +17,13 @@ export const CORE_PACKAGE_SOURCES = [
 	"npm:@tmustier/pi-ralph-wiggum",
 ] as const;
 
+export const NATIVE_PACKAGE_SOURCES = [
+	"npm:@kaiserlich-dev/pi-session-search",
+	"npm:@samfp/pi-memory",
+] as const;
+
+export const MAX_NATIVE_PACKAGE_NODE_MAJOR = 24;
+
 export const OPTIONAL_PACKAGE_PRESETS = {
 	"generative-ui": {
 		description: "Interactive Glimpse UI widgets.",
@@ -49,6 +57,24 @@ export function shouldPruneLegacyDefaultPackages(packages: PackageSource[] | und
 	return arraysMatchAsSets(packages as string[], LEGACY_DEFAULT_PACKAGE_SOURCES);
 }
 
+function parseNodeMajor(version: string): number {
+	const [major = "0"] = version.replace(/^v/, "").split(".");
+	return Number.parseInt(major, 10) || 0;
+}
+
+export function supportsNativePackageSources(version = process.versions.node): boolean {
+	return parseNodeMajor(version) <= MAX_NATIVE_PACKAGE_NODE_MAJOR;
+}
+
+export function filterPackageSourcesForCurrentNode<T extends string>(sources: readonly T[], version = process.versions.node): T[] {
+	if (supportsNativePackageSources(version)) {
+		return [...sources];
+	}
+
+	const blocked = new Set<string>(NATIVE_PACKAGE_SOURCES);
+	return sources.filter((source) => !blocked.has(source));
+}
+
 export function getOptionalPackagePresetSources(name: string): string[] | undefined {
 	const normalized = name.trim().toLowerCase();
 	if (normalized === "ui") {

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,17 +15,32 @@ 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"),
@@ -33,12 +49,20 @@ export function resolvePiPaths(appRoot: string) {
 	};
 }
 
+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);
 
@@ -60,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);
 	}
@@ -77,23 +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 binPath = paths.nodeModulesBinPath;
+	const binEntries = [paths.nodeModulesBinPath, resolve(paths.piWorkspaceNodeModulesPath, ".bin"), feynmanNpmBinPath];
+	const binPath = binEntries.join(delimiter);
 
 	return {
 		...process.env,
-		PATH: `${binPath}:${currentPath}`,
+		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 { CORE_PACKAGE_SOURCES, filterPackageSourcesForCurrentNode, shouldPruneLegacyDefaultPackages } from "./package-presets.js";
+import { createModelRegistry } from "../model/registry.js";
 
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
@@ -66,6 +67,23 @@ function choosePreferredModel(
 	return availableModels[0];
 }
 
+function filterConfiguredPackagesForCurrentNode(packages: PackageSource[] | undefined): PackageSource[] {
+	if (!Array.isArray(packages)) {
+		return [];
+	}
+
+	const filteredStringSources = new Set(filterPackageSourcesForCurrentNode(
+		packages
+			.map((entry) => (typeof entry === "string" ? entry : entry.source))
+			.filter((entry): entry is string => typeof entry === "string"),
+	));
+
+	return packages.filter((entry) => {
+		const source = typeof entry === "string" ? entry : entry.source;
+		return filteredStringSources.has(source);
+	});
+}
+
 export function readJson(path: string): Record<string, unknown> {
 	if (!existsSync(path)) {
 		return {};
@@ -109,14 +127,16 @@ export function normalizeFeynmanSettings(
 	settings.theme = "feynman";
 	settings.quietStartup = true;
 	settings.collapseChangelog = true;
+	const supportedCorePackages = filterPackageSourcesForCurrentNode(CORE_PACKAGE_SOURCES);
 	if (!Array.isArray(settings.packages) || settings.packages.length === 0) {
-		settings.packages = [...CORE_PACKAGE_SOURCES];
+		settings.packages = supportedCorePackages;
 	} else if (shouldPruneLegacyDefaultPackages(settings.packages as PackageSource[])) {
-		settings.packages = [...CORE_PACKAGE_SOURCES];
+		settings.packages = supportedCorePackages;
+	} else {
+		settings.packages = filterConfiguredPackagesForCurrentNode(settings.packages as PackageSource[]);
 	}
 
-	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,17 @@
-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 PiWebSearchWorkflow = "none" | "summary-review";
 
 export type PiWebAccessConfig = Record<string, unknown> & {
+	route?: PiWebSearchProvider;
 	provider?: PiWebSearchProvider;
 	searchProvider?: PiWebSearchProvider;
+	workflow?: PiWebSearchWorkflow;
 	perplexityApiKey?: string;
+	exaApiKey?: string;
 	geminiApiKey?: string;
 	chromeProfile?: string;
 };
@@ -16,19 +20,26 @@ export type PiWebAccessStatus = {
 	configPath: string;
 	searchProvider: PiWebSearchProvider;
 	requestProvider: PiWebSearchProvider;
+	workflow: PiWebSearchWorkflow;
 	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 normalizeWorkflow(value: unknown): PiWebSearchWorkflow | undefined {
+	return value === "none" || value === "summary-review" ? value : undefined;
 }
 
 function normalizeNonEmptyString(value: unknown): string | undefined {
@@ -48,10 +59,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 +93,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 +106,12 @@ 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 workflow = normalizeWorkflow(config.workflow) ?? "none";
 	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;
@@ -85,7 +120,9 @@ export function getPiWebAccessStatus(
 		configPath,
 		searchProvider,
 		requestProvider,
+		workflow,
 		perplexityConfigured,
+		exaConfigured,
 		geminiApiConfigured,
 		chromeProfile,
 		routeLabel: formatRouteLabel(effectiveProvider),
@@ -100,7 +137,9 @@ export function formatPiWebAccessDoctorLines(
 		"web access: pi-web-access",
 		`  search route: ${status.routeLabel}`,
 		`  request route: ${status.requestProvider}`,
+		`  search workflow: ${status.workflow}`,
 		`  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,60 @@
-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(`Search workflow: ${status.workflow}`);
 	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,
+		workflow: "none",
+		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, workflow: "none" });
+
+	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,14 +13,36 @@ export function setupPreviewDependencies(): PreviewSetupResult {
 		return { status: "ready", message: `pandoc already installed at ${pandocPath}` };
 	}
 
+	if (process.platform === "darwin") {
 		const brewPath = resolveExecutable("brew", BREW_FALLBACK_PATHS);
-	if (process.platform === "darwin" && brewPath) {
+		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: "manual",

src/setup/prompts.ts

@@ -1,30 +1,130 @@
-import { stdin as input, stdout as output } from "node:process";
-import { createInterface } from "node:readline/promises";
+import {
+	confirm as clackConfirm,
+	intro as clackIntro,
+	isCancel,
+	multiselect as clackMultiselect,
+	outro as clackOutro,
+	select as clackSelect,
+	text as clackText,
+	type Option,
+} from "@clack/prompts";
 
-export async function promptText(question: string, defaultValue = ""): Promise<string> {
-	if (!input.isTTY || !output.isTTY) {
+export class SetupCancelledError extends Error {
+	constructor(message = "setup cancelled") {
+		super(message);
+		this.name = "SetupCancelledError";
+	}
+}
+
+export type PromptSelectOption<T = string> = {
+	value: T;
+	label: string;
+	hint?: string;
+};
+
+function ensureInteractiveTerminal(): void {
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
 		throw new Error("feynman setup requires an interactive terminal.");
 	}
-	const rl = createInterface({ input, output });
-	try {
-		const suffix = defaultValue ? ` [${defaultValue}]` : "";
-		const value = (await rl.question(`${question}${suffix}: `)).trim();
-		return value || defaultValue;
-	} finally {
-		rl.close();
+}
+
+function guardCancelled<T>(value: T | symbol): T {
+	if (isCancel(value)) {
+		throw new SetupCancelledError();
 	}
+
+	return value;
+}
+
+export function isInteractiveTerminal(): boolean {
+	return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+export async function promptIntro(title: string): Promise<void> {
+	ensureInteractiveTerminal();
+	clackIntro(title);
+}
+
+export async function promptOutro(message: string): Promise<void> {
+	ensureInteractiveTerminal();
+	clackOutro(message);
+}
+
+export async function promptText(question: string, defaultValue = "", placeholder?: string): Promise<string> {
+	ensureInteractiveTerminal();
+
+	const value = guardCancelled(
+		await clackText({
+			message: question,
+			initialValue: defaultValue || undefined,
+			placeholder: placeholder ?? (defaultValue || undefined),
+		}),
+	);
+
+	const normalized = String(value ?? "").trim();
+	return normalized || defaultValue;
+}
+
+export async function promptSelect<T>(
+	question: string,
+	options: PromptSelectOption<T>[],
+	initialValue?: T,
+): Promise<T> {
+	ensureInteractiveTerminal();
+
+	const selection = guardCancelled(
+		await clackSelect({
+			message: question,
+			options: options.map((option) => ({
+				value: option.value,
+				label: option.label,
+				hint: option.hint,
+			})) as Option<T>[],
+			initialValue,
+		}),
+	);
+
+	return selection;
 }
 
 export async function promptChoice(question: string, choices: string[], defaultIndex = 0): Promise<number> {
-	console.log(question);
-	for (const [index, choice] of choices.entries()) {
-		const marker = index === defaultIndex ? "*" : " ";
-		console.log(`  ${marker} ${index + 1}. ${choice}`);
-	}
-	const answer = await promptText("Select", String(defaultIndex + 1));
-	const parsed = Number(answer);
-	if (!Number.isFinite(parsed) || parsed < 1 || parsed > choices.length) {
-		return defaultIndex;
-	}
-	return parsed - 1;
+	const options = choices.map((choice, index) => ({
+		value: index,
+		label: choice,
+	}));
+	return promptSelect(question, options, Math.max(0, Math.min(defaultIndex, choices.length - 1)));
+}
+
+export async function promptConfirm(question: string, initialValue = true): Promise<boolean> {
+	ensureInteractiveTerminal();
+
+	return guardCancelled(
+		await clackConfirm({
+			message: question,
+			initialValue,
+		}),
+	);
+}
+
+export async function promptMultiSelect<T>(
+	question: string,
+	options: PromptSelectOption<T>[],
+	initialValues: T[] = [],
+): Promise<T[]> {
+	ensureInteractiveTerminal();
+
+	const selection = guardCancelled(
+		await clackMultiselect({
+			message: question,
+			options: options.map((option) => ({
+				value: option.value,
+				label: option.label,
+				hint: option.hint,
+			})) as Option<T>[],
+			initialValues,
+			required: false,
+		}),
+	);
+
+	return selection;
 }

src/setup/setup.ts

@@ -1,15 +1,24 @@
 import { isLoggedIn as isAlphaLoggedIn, login as loginAlpha } from "@companion-ai/alpha-hub/lib";
+import { dirname } from "node:path";
 
-import { getDefaultSessionDir, getFeynmanHome } from "../config/paths.js";
-import { getPiWebAccessStatus, getPiWebSearchConfigPath } from "../pi/web-access.js";
+import { getPiWebAccessStatus } from "../pi/web-access.js";
 import { normalizeFeynmanSettings } from "../pi/settings.js";
 import type { ThinkingLevel } from "../pi/settings.js";
+import { getMissingConfiguredPackages, installPackageSources } from "../pi/package-ops.js";
+import { listOptionalPackagePresets } from "../pi/package-presets.js";
 import { getCurrentModelSpec, runModelSetup } from "../model/commands.js";
 import { buildModelStatusSnapshotFromRecords, getAvailableModelRecords, getSupportedModelRecords } from "../model/catalog.js";
 import { PANDOC_FALLBACK_PATHS, resolveExecutable } from "../system/executables.js";
 import { setupPreviewDependencies } from "./preview.js";
-import { runDoctor } from "./doctor.js";
 import { printInfo, printSection, printSuccess } from "../ui/terminal.js";
+import {
+	isInteractiveTerminal,
+	promptConfirm,
+	promptIntro,
+	promptMultiSelect,
+	promptOutro,
+	SetupCancelledError,
+} from "./prompts.js";
 
 type SetupOptions = {
 	settingsPath: string;
@@ -21,33 +30,161 @@ type SetupOptions = {
 	defaultThinkingLevel?: ThinkingLevel;
 };
 
-function isInteractiveTerminal(): boolean {
-	return Boolean(process.stdin.isTTY && process.stdout.isTTY);
-}
-
 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");
 }
 
+function summarizePackageSources(sources: string[]): string {
+	if (sources.length <= 3) {
+		return sources.join(", ");
+	}
+
+	return `${sources.slice(0, 3).join(", ")} +${sources.length - 3} more`;
+}
+
+async function maybeInstallBundledPackages(options: SetupOptions): Promise<void> {
+	const agentDir = dirname(options.authPath);
+	const { missing, bundled } = getMissingConfiguredPackages(options.workingDir, agentDir, options.appRoot);
+	const userMissing = missing.filter((entry) => entry.scope === "user").map((entry) => entry.source);
+	const projectMissing = missing.filter((entry) => entry.scope === "project").map((entry) => entry.source);
+
+	printSection("Packages");
+	if (bundled.length > 0) {
+		printInfo(`Bundled research packages ready: ${summarizePackageSources(bundled.map((entry) => entry.source))}`);
+	}
+
+	if (missing.length === 0) {
+		printInfo("No additional package install required.");
+		return;
+	}
+
+	printInfo(`Missing packages: ${summarizePackageSources(missing.map((entry) => entry.source))}`);
+	const shouldInstall = await promptConfirm("Install missing Feynman packages now?", true);
+	if (!shouldInstall) {
+		printInfo("Skipping package install. Feynman may install missing packages later if needed.");
+		return;
+	}
+
+	if (userMissing.length > 0) {
+		try {
+			await installPackageSources(options.workingDir, agentDir, userMissing);
+			printSuccess(`Installed bundled packages: ${summarizePackageSources(userMissing)}`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			printInfo(message.includes("No supported package manager found")
+				? "No package manager available for additional installs. The standalone bundle can still run with its shipped packages."
+				: `Package install skipped: ${message}`);
+		}
+	}
+
+	if (projectMissing.length > 0) {
+		try {
+			await installPackageSources(options.workingDir, agentDir, projectMissing, { local: true });
+			printSuccess(`Installed project packages: ${summarizePackageSources(projectMissing)}`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			printInfo(`Project package install skipped: ${message}`);
+		}
+	}
+}
+
+async function maybeInstallOptionalPackages(options: SetupOptions): Promise<void> {
+	const agentDir = dirname(options.authPath);
+	const presets = listOptionalPackagePresets();
+	if (presets.length === 0) {
+		return;
+	}
+
+	const selectedPresets = await promptMultiSelect(
+		"Optional packages",
+		presets.map((preset) => ({
+			value: preset.name,
+			label: preset.name,
+			hint: preset.description,
+		})),
+		[],
+	);
+
+	if (selectedPresets.length === 0) {
+		printInfo("No optional packages selected.");
+		return;
+	}
+
+	for (const presetName of selectedPresets) {
+		const preset = presets.find((entry) => entry.name === presetName);
+		if (!preset) continue;
+		try {
+			await installPackageSources(options.workingDir, agentDir, preset.sources, {
+				persist: true,
+			});
+			printSuccess(`Installed optional preset: ${preset.name}`);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			printInfo(message.includes("No supported package manager found")
+				? `Skipped optional preset ${preset.name}: no package manager available.`
+				: `Skipped optional preset ${preset.name}: ${message}`);
+		}
+	}
+}
+
+async function maybeLoginAlpha(): Promise<void> {
+	if (isAlphaLoggedIn()) {
+		printInfo("alphaXiv already configured.");
+		return;
+	}
+
+	const shouldLogin = await promptConfirm("Connect alphaXiv now?", true);
+	if (!shouldLogin) {
+		printInfo("Skipping alphaXiv login for now.");
+		return;
+	}
+
+	try {
+		await loginAlpha();
+		printSuccess("alphaXiv login complete");
+	} catch (error) {
+		printInfo(`alphaXiv login skipped: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+async function maybeInstallPreviewDependencies(): Promise<void> {
+	if (resolveExecutable("pandoc", PANDOC_FALLBACK_PATHS)) {
+		printInfo("Preview support already configured.");
+		return;
+	}
+
+	const shouldInstall = await promptConfirm("Install pandoc for preview/export support?", false);
+	if (!shouldInstall) {
+		printInfo("Skipping preview dependency install.");
+		return;
+	}
+
+	try {
+		const result = setupPreviewDependencies();
+		printSuccess(result.message);
+	} catch (error) {
+		printInfo(`Preview setup skipped: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
 export async function runSetup(options: SetupOptions): Promise<void> {
 	if (!isInteractiveTerminal()) {
 		printNonInteractiveSetupGuidance();
 		return;
 	}
 
+	try {
+		await promptIntro("Feynman setup");
 		await runModelSetup(options.settingsPath, options.authPath);
-
-	if (!isAlphaLoggedIn()) {
-		await loginAlpha();
-		printSuccess("alphaXiv login complete");
-	}
-
-	const result = setupPreviewDependencies();
-	printSuccess(result.message);
+		await maybeInstallBundledPackages(options);
+		await maybeInstallOptionalPackages(options);
+		await maybeLoginAlpha();
+		await maybeInstallPreviewDependencies();
 
 		normalizeFeynmanSettings(
 			options.settingsPath,
@@ -66,4 +203,17 @@ export async function runSetup(options: SetupOptions): Promise<void> {
 		printInfo(`alphaXiv: ${isAlphaLoggedIn() ? "configured" : "not configured"}`);
 		printInfo(`Preview: ${resolveExecutable("pandoc", PANDOC_FALLBACK_PATHS) ? "configured" : "not configured"}`);
 		printInfo(`Web: ${getPiWebAccessStatus().routeLabel}`);
+		if (modelStatus.recommended && !modelStatus.currentValid) {
+			printInfo(`Recommended model: ${modelStatus.recommended}`);
+		}
+
+		await promptOutro("Feynman is ready");
+	} catch (error) {
+		if (error instanceof SetupCancelledError) {
+			printInfo("Setup cancelled.");
+			return;
+		}
+
+		throw error;
+	}
 }

src/system/executables.ts

@@ -1,27 +1,37 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
+import { dirname, delimiter } from "node:path";
 
-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 = [
+export const BREW_FALLBACK_PATHS = isWindows
+	? []
+	: ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"];
+
+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 = [
-	"/opt/homebrew/bin/mmdc",
-	"/usr/local/bin/mmdc",
-];
+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 +40,25 @@ export function resolveExecutable(name: string, fallbackPaths: string[] = []): s
 		}
 	}
 
-	const result = spawnSync("sh", ["-lc", `command -v ${name}`], {
+	const isWindows = process.platform === "win32";
+	const env = {
+		...process.env,
+		PATH: process.env.PATH ?? "",
+	};
+	const result = isWindows
+		? spawnSync("cmd", ["/c", `where ${name}`], {
 				encoding: "utf8",
 				stdio: ["ignore", "pipe", "ignore"],
+				env,
+			})
+		: spawnSync("sh", ["-c", `command -v ${name}`], {
+				encoding: "utf8",
+				stdio: ["ignore", "pipe", "ignore"],
+				env,
 			});
 
 	if (result.status === 0) {
-		const resolved = result.stdout.trim();
+		const resolved = result.stdout.trim().split(/\r?\n/)[0];
 		if (resolved) {
 			return resolved;
 		}
@@ -44,3 +66,9 @@ export function resolveExecutable(name: string, fallbackPaths: string[] = []): s
 
 	return undefined;
 }
+
+export function getPathWithCurrentNode(pathValue = process.env.PATH ?? ""): string {
+	const nodeDir = dirname(process.execPath);
+	const parts = pathValue.split(delimiter).filter(Boolean);
+	return parts.includes(nodeDir) ? pathValue : `${nodeDir}${delimiter}${pathValue}`;
+}

src/system/node-version.ts

@@ -0,0 +1,52 @@
+export const MIN_NODE_VERSION = "20.19.0";
+export const MAX_NODE_MAJOR = 24;
+export const PREFERRED_NODE_MAJOR = 22;
+
+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 {
+	const parsed = parseNodeVersion(version);
+	return compareNodeVersions(parsed, parseNodeVersion(MIN_NODE_VERSION)) >= 0 && parsed.major <= MAX_NODE_MAJOR;
+}
+
+export function getUnsupportedNodeVersionLines(version = process.versions.node): string[] {
+	const isWindows = process.platform === "win32";
+	const parsed = parseNodeVersion(version);
+	const rangeText = `Node.js ${MIN_NODE_VERSION} through ${MAX_NODE_MAJOR}.x`;
+	return [
+		`feynman supports ${rangeText} (detected ${version}).`,
+		parsed.major > MAX_NODE_MAJOR
+			? "This newer Node release is not supported yet because native Pi packages may fail to build."
+			: isWindows
+				? "Install a supported Node.js release from https://nodejs.org, or use the standalone installer:"
+				: `Switch to a supported Node release with \`nvm install ${PREFERRED_NODE_MAJOR} && nvm use ${PREFERRED_NODE_MAJOR}\`, 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;
+	}
+}

tests/alpha-hub-auth-patch.test.ts

@@ -0,0 +1,51 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { patchAlphaHubAuthSource } from "../scripts/lib/alpha-hub-auth-patch.mjs";
+
+test("patchAlphaHubAuthSource fixes browser open logic for WSL and Windows", () => {
+	const input = [
+		"function openBrowser(url) {",
+		"  try {",
+		"    const plat = platform();",
+		"    if (plat === 'darwin') execSync(`open \"${url}\"`);",
+		"    else if (plat === 'linux') execSync(`xdg-open \"${url}\"`);",
+		"    else if (plat === 'win32') execSync(`start \"\" \"${url}\"`);",
+		"  } catch {}",
+		"}",
+	].join("\n");
+
+	const patched = patchAlphaHubAuthSource(input);
+
+	assert.match(patched, /const isWsl = plat === 'linux'/);
+	assert.match(patched, /wslview/);
+	assert.match(patched, /cmd\.exe \/c start/);
+	assert.match(patched, /cmd \/c start/);
+});
+
+test("patchAlphaHubAuthSource includes the auth URL in login output", () => {
+	const input = "process.stderr.write('Opening browser for alphaXiv login...\\n');";
+
+	const patched = patchAlphaHubAuthSource(input);
+
+	assert.match(patched, /Auth URL: \$\{authUrl\.toString\(\)\}/);
+});
+
+test("patchAlphaHubAuthSource is idempotent", () => {
+	const input = [
+		"function openBrowser(url) {",
+		"  try {",
+		"    const plat = platform();",
+		"    if (plat === 'darwin') execSync(`open \"${url}\"`);",
+		"    else if (plat === 'linux') execSync(`xdg-open \"${url}\"`);",
+		"    else if (plat === 'win32') execSync(`start \"\" \"${url}\"`);",
+		"  } catch {}",
+		"}",
+		"process.stderr.write('Opening browser for alphaXiv login...\\n');",
+	].join("\n");
+
+	const once = patchAlphaHubAuthSource(input);
+	const twice = patchAlphaHubAuthSource(once);
+
+	assert.equal(twice, once);
+});

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,59 @@
+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}`);
+		}
+	}
+});
+
+test("research writing prompts forbid fabricated results and unproven figures", () => {
+	const draftPrompt = readFileSync(join(repoRoot, "prompts", "draft.md"), "utf8");
+	const systemPrompt = readFileSync(join(repoRoot, ".feynman", "SYSTEM.md"), "utf8");
+	const writerPrompt = readFileSync(join(repoRoot, ".feynman", "agents", "writer.md"), "utf8");
+	const verifierPrompt = readFileSync(join(repoRoot, ".feynman", "agents", "verifier.md"), "utf8");
+
+	for (const [label, content] of [
+		["system prompt", systemPrompt],
+	] as const) {
+		assert.match(content, /Never (invent|fabricate)/i, `${label} must explicitly forbid invented or fabricated results`);
+		assert.match(content, /(figure|chart|image|table)/i, `${label} must cover visual/table provenance`);
+		assert.match(content, /(provenance|source|artifact|script|raw)/i, `${label} must require traceable support`);
+	}
+
+	for (const [label, content] of [
+		["writer prompt", writerPrompt],
+		["verifier prompt", verifierPrompt],
+		["draft prompt", draftPrompt],
+	] as const) {
+		assert.match(content, /system prompt.*provenance rule/i, `${label} must point back to the system provenance rule`);
+	}
+
+	assert.match(draftPrompt, /system prompt's provenance rules/i);
+	assert.match(draftPrompt, /placeholder or proposed experimental plan/i);
+	assert.match(draftPrompt, /source-backed quantitative data/i);
+});

tests/model-harness.test.ts

@@ -4,9 +4,10 @@ import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { resolveInitialPrompt } from "../src/cli.js";
+import { resolveInitialPrompt, shouldRunInteractiveSetup } from "../src/cli.js";
 import { buildModelStatusSnapshotFromRecords, chooseRecommendedModel } from "../src/model/catalog.js";
-import { setDefaultModelSpec } from "../src/model/commands.js";
+import { resolveModelProviderForCommand, setDefaultModelSpec } from "../src/model/commands.js";
+import { createModelRegistry } from "../src/model/registry.js";
 
 function createAuthPath(contents: Record<string, unknown>): string {
 	const root = mkdtempSync(join(tmpdir(), "feynman-auth-"));
@@ -26,6 +27,17 @@ test("chooseRecommendedModel prefers the strongest authenticated research model"
 	assert.equal(recommendation?.spec, "anthropic/claude-opus-4-6");
 });
 
+test("createModelRegistry overlays new Anthropic Opus model before upstream Pi updates", () => {
+	const authPath = createAuthPath({
+		anthropic: { type: "api_key", key: "anthropic-test-key" },
+	});
+
+	const registry = createModelRegistry(authPath);
+
+	assert.ok(registry.find("anthropic", "claude-opus-4-7"));
+	assert.equal(registry.getAvailable().some((model) => model.provider === "anthropic" && model.id === "claude-opus-4-7"), true);
+});
+
 test("setDefaultModelSpec accepts a unique bare model id from authenticated models", () => {
 	const authPath = createAuthPath({
 		openai: { type: "api_key", key: "openai-test-key" },
@@ -42,6 +54,56 @@ test("setDefaultModelSpec accepts a unique bare model id from authenticated mode
 	assert.equal(settings.defaultModel, "gpt-5.4");
 });
 
+test("setDefaultModelSpec accepts provider:model syntax for authenticated models", () => {
+	const authPath = createAuthPath({
+		google: { type: "api_key", key: "google-test-key" },
+	});
+	const settingsPath = join(mkdtempSync(join(tmpdir(), "feynman-settings-")), "settings.json");
+
+	setDefaultModelSpec(settingsPath, authPath, "google:gemini-3-pro-preview");
+
+	const settings = JSON.parse(readFileSync(settingsPath, "utf8")) as {
+		defaultProvider?: string;
+		defaultModel?: string;
+	};
+	assert.equal(settings.defaultProvider, "google");
+	assert.equal(settings.defaultModel, "gemini-3-pro-preview");
+});
+
+test("resolveModelProviderForCommand falls back to API-key providers when OAuth is unavailable", () => {
+	const authPath = createAuthPath({});
+
+	const resolved = resolveModelProviderForCommand(authPath, "google");
+
+	assert.equal(resolved?.kind, "api-key");
+	assert.equal(resolved?.id, "google");
+});
+
+test("resolveModelProviderForCommand prefers OAuth when a provider supports both auth modes", () => {
+	const authPath = createAuthPath({});
+
+	const resolved = resolveModelProviderForCommand(authPath, "anthropic");
+
+	assert.equal(resolved?.kind, "oauth");
+	assert.equal(resolved?.id, "anthropic");
+});
+
+test("setDefaultModelSpec prefers the explicitly configured provider when a bare model id is ambiguous", () => {
+	const authPath = createAuthPath({
+		openai: { type: "api_key", key: "openai-test-key" },
+	});
+	const settingsPath = join(mkdtempSync(join(tmpdir(), "feynman-settings-")), "settings.json");
+
+	setDefaultModelSpec(settingsPath, authPath, "gpt-5.4");
+
+	const settings = JSON.parse(readFileSync(settingsPath, "utf8")) as {
+		defaultProvider?: string;
+		defaultModel?: string;
+	};
+	assert.equal(settings.defaultProvider, "openai");
+	assert.equal(settings.defaultModel, "gpt-5.4");
+});
+
 test("buildModelStatusSnapshotFromRecords flags an invalid current model and suggests a replacement", () => {
 	const snapshot = buildModelStatusSnapshotFromRecords(
 		[
@@ -57,12 +119,74 @@ 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"]);
+	const workflows = new Set([
+		"lit",
+		"watch",
+		"jobs",
+		"deepresearch",
+		"review",
+		"audit",
+		"replicate",
+		"compare",
+		"draft",
+		"autoresearch",
+		"summarize",
+		"log",
+	]);
 	assert.equal(resolveInitialPrompt("lit", ["tool-using", "agents"], undefined, workflows), "/lit tool-using agents");
 	assert.equal(resolveInitialPrompt("watch", ["openai"], undefined, workflows), "/watch openai");
 	assert.equal(resolveInitialPrompt("jobs", [], undefined, workflows), "/jobs");
+	assert.equal(resolveInitialPrompt("deepresearch", ["scaling", "laws"], undefined, workflows), "/deepresearch scaling laws");
+	assert.equal(resolveInitialPrompt("review", ["paper.md"], undefined, workflows), "/review paper.md");
+	assert.equal(resolveInitialPrompt("audit", ["2401.12345"], undefined, workflows), "/audit 2401.12345");
+	assert.equal(resolveInitialPrompt("replicate", ["chain-of-thought"], undefined, workflows), "/replicate chain-of-thought");
+	assert.equal(resolveInitialPrompt("compare", ["tool", "use"], undefined, workflows), "/compare tool use");
+	assert.equal(resolveInitialPrompt("draft", ["mechanistic", "interp"], undefined, workflows), "/draft mechanistic interp");
+	assert.equal(resolveInitialPrompt("autoresearch", ["gsm8k"], undefined, workflows), "/autoresearch gsm8k");
+	assert.equal(resolveInitialPrompt("summarize", ["README.md"], undefined, workflows), "/summarize README.md");
+	assert.equal(resolveInitialPrompt("log", [], undefined, workflows), "/log");
 	assert.equal(resolveInitialPrompt("chat", ["hello"], undefined, workflows), "hello");
 	assert.equal(resolveInitialPrompt("unknown", ["topic"], undefined, workflows), "unknown topic");
 });
 
+test("shouldRunInteractiveSetup triggers on first run when no default model is configured", () => {
+	const authPath = createAuthPath({});
+
+	assert.equal(shouldRunInteractiveSetup(undefined, undefined, true, authPath), true);
+});
+
+test("shouldRunInteractiveSetup triggers when the configured default model is unavailable", () => {
+	const authPath = createAuthPath({
+		openai: { type: "api_key", key: "openai-test-key" },
+	});
+
+	assert.equal(shouldRunInteractiveSetup(undefined, "anthropic/claude-opus-4-6", true, authPath), true);
+});
+
+test("shouldRunInteractiveSetup skips onboarding when the configured default model is available", () => {
+	const authPath = createAuthPath({
+		openai: { type: "api_key", key: "openai-test-key" },
+	});
+
+	assert.equal(shouldRunInteractiveSetup(undefined, "openai/gpt-5.4", true, authPath), false);
+});
+
+test("shouldRunInteractiveSetup skips onboarding for explicit model overrides or non-interactive terminals", () => {
+	const authPath = createAuthPath({
+		openai: { type: "api_key", key: "openai-test-key" },
+	});
+
+	assert.equal(shouldRunInteractiveSetup("openai/gpt-5.4", undefined, true, authPath), false);
+	assert.equal(shouldRunInteractiveSetup(undefined, undefined, false, authPath), false);
+});

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,45 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+	MAX_NODE_MAJOR,
+	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(`${MAX_NODE_MAJOR}.9.9`), true);
+	assert.equal(isSupportedNodeVersion(`${MAX_NODE_MAJOR + 1}.0.0`), false);
+	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 22 && nvm use 22") &&
+			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 supports Node.js ${MIN_NODE_VERSION} through ${MAX_NODE_MAJOR}.x (detected 18.17.0).`);
+	assert.ok(lines.some((line) => line.includes("curl -fsSL https://feynman.is/install | bash")));
+});
+
+test("unsupported version guidance explains upper-bound failures", () => {
+	const lines = getUnsupportedNodeVersionLines("25.1.0");
+
+	assert.equal(lines[0], `feynman supports Node.js ${MIN_NODE_VERSION} through ${MAX_NODE_MAJOR}.x (detected 25.1.0).`);
+	assert.ok(lines.some((line) => line.includes("native Pi packages may fail to build")));
+});

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/package-ops.test.ts

@@ -0,0 +1,286 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { appendFileSync, existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { installPackageSources, seedBundledWorkspacePackages, updateConfiguredPackages } from "../src/pi/package-ops.js";
+
+function createBundledWorkspace(
+	appRoot: string,
+	packageNames: string[],
+	dependenciesByPackage: Record<string, Record<string, string>> = {},
+): void {
+	for (const packageName of packageNames) {
+		const packageDir = resolve(appRoot, ".feynman", "npm", "node_modules", packageName);
+		mkdirSync(packageDir, { recursive: true });
+		writeFileSync(
+			join(packageDir, "package.json"),
+			JSON.stringify({ name: packageName, version: "1.0.0", dependencies: dependenciesByPackage[packageName] }, null, 2) + "\n",
+			"utf8",
+		);
+	}
+}
+
+function createInstalledGlobalPackage(homeRoot: string, packageName: string, version = "1.0.0"): void {
+	const packageDir = resolve(homeRoot, "npm-global", "lib", "node_modules", packageName);
+	mkdirSync(packageDir, { recursive: true });
+	writeFileSync(
+		join(packageDir, "package.json"),
+		JSON.stringify({ name: packageName, version }, null, 2) + "\n",
+		"utf8",
+	);
+}
+
+function writeSettings(agentDir: string, settings: Record<string, unknown>): void {
+	mkdirSync(agentDir, { recursive: true });
+	writeFileSync(resolve(agentDir, "settings.json"), JSON.stringify(settings, null, 2) + "\n", "utf8");
+}
+
+function writeFakeNpmScript(root: string, body: string): string {
+	const scriptPath = resolve(root, "fake-npm.mjs");
+	writeFileSync(scriptPath, body, "utf8");
+	return scriptPath;
+}
+
+test("seedBundledWorkspacePackages links bundled packages into the Feynman npm prefix", () => {
+	const appRoot = mkdtempSync(join(tmpdir(), "feynman-bundle-"));
+	const homeRoot = mkdtempSync(join(tmpdir(), "feynman-home-"));
+	const agentDir = resolve(homeRoot, "agent");
+	mkdirSync(agentDir, { recursive: true });
+
+	createBundledWorkspace(appRoot, ["pi-subagents", "@samfp/pi-memory"]);
+
+	const seeded = seedBundledWorkspacePackages(agentDir, appRoot, [
+		"npm:pi-subagents",
+		"npm:@samfp/pi-memory",
+	]);
+
+	assert.deepEqual(seeded.sort(), ["npm:@samfp/pi-memory", "npm:pi-subagents"]);
+	const globalRoot = resolve(homeRoot, "npm-global", "lib", "node_modules");
+	assert.equal(existsSync(resolve(globalRoot, "pi-subagents", "package.json")), true);
+	assert.equal(existsSync(resolve(globalRoot, "@samfp", "pi-memory", "package.json")), true);
+});
+
+test("seedBundledWorkspacePackages preserves existing installed packages", () => {
+	const appRoot = mkdtempSync(join(tmpdir(), "feynman-bundle-"));
+	const homeRoot = mkdtempSync(join(tmpdir(), "feynman-home-"));
+	const agentDir = resolve(homeRoot, "agent");
+	const existingPackageDir = resolve(homeRoot, "npm-global", "lib", "node_modules", "pi-subagents");
+
+	mkdirSync(agentDir, { recursive: true });
+	createBundledWorkspace(appRoot, ["pi-subagents"]);
+	mkdirSync(existingPackageDir, { recursive: true });
+	writeFileSync(resolve(existingPackageDir, "package.json"), '{"name":"pi-subagents","version":"user"}\n', "utf8");
+
+	const seeded = seedBundledWorkspacePackages(agentDir, appRoot, ["npm:pi-subagents"]);
+
+	assert.deepEqual(seeded, []);
+	assert.equal(readFileSync(resolve(existingPackageDir, "package.json"), "utf8"), '{"name":"pi-subagents","version":"user"}\n');
+	assert.equal(lstatSync(existingPackageDir).isSymbolicLink(), false);
+});
+
+test("seedBundledWorkspacePackages repairs broken existing bundled packages", () => {
+	const appRoot = mkdtempSync(join(tmpdir(), "feynman-bundle-"));
+	const homeRoot = mkdtempSync(join(tmpdir(), "feynman-home-"));
+	const agentDir = resolve(homeRoot, "agent");
+	const existingPackageDir = resolve(homeRoot, "npm-global", "lib", "node_modules", "pi-markdown-preview");
+
+	mkdirSync(agentDir, { recursive: true });
+	createBundledWorkspace(appRoot, ["pi-markdown-preview", "puppeteer-core"], {
+		"pi-markdown-preview": { "puppeteer-core": "^24.0.0" },
+	});
+	mkdirSync(existingPackageDir, { recursive: true });
+	writeFileSync(
+		resolve(existingPackageDir, "package.json"),
+		JSON.stringify({ name: "pi-markdown-preview", version: "broken", dependencies: { "puppeteer-core": "^24.0.0" } }) + "\n",
+		"utf8",
+	);
+
+	const seeded = seedBundledWorkspacePackages(agentDir, appRoot, ["npm:pi-markdown-preview"]);
+
+	assert.deepEqual(seeded, ["npm:pi-markdown-preview"]);
+	assert.equal(lstatSync(existingPackageDir).isSymbolicLink(), true);
+	assert.equal(
+		readFileSync(resolve(existingPackageDir, "package.json"), "utf8").includes('"version": "1.0.0"'),
+		true,
+	);
+});
+
+test("installPackageSources filters noisy npm chatter but preserves meaningful output", async () => {
+	const root = mkdtempSync(join(tmpdir(), "feynman-package-ops-"));
+	const workingDir = resolve(root, "project");
+	const agentDir = resolve(root, "agent");
+	mkdirSync(workingDir, { recursive: true });
+
+	const scriptPath = writeFakeNpmScript(root, [
+		`console.log("npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead");`,
+		'console.log("changed 343 packages in 9s");',
+		'console.log("59 packages are looking for funding");',
+		'console.log("run `npm fund` for details");',
+		'console.error("visible stderr line");',
+		'console.log("visible stdout line");',
+		"process.exit(0);",
+	].join("\n"));
+
+	writeSettings(agentDir, {
+		npmCommand: [process.execPath, scriptPath],
+	});
+
+	let stdout = "";
+	let stderr = "";
+	const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+	const originalStderrWrite = process.stderr.write.bind(process.stderr);
+	(process.stdout.write as unknown as (chunk: string | Uint8Array) => boolean) = ((chunk: string | Uint8Array) => {
+		stdout += chunk.toString();
+		return true;
+	}) as typeof process.stdout.write;
+	(process.stderr.write as unknown as (chunk: string | Uint8Array) => boolean) = ((chunk: string | Uint8Array) => {
+		stderr += chunk.toString();
+		return true;
+	}) as typeof process.stderr.write;
+
+	try {
+		const result = await installPackageSources(workingDir, agentDir, ["npm:test-visible-package"]);
+		assert.deepEqual(result.installed, ["npm:test-visible-package"]);
+		assert.deepEqual(result.skipped, []);
+	} finally {
+		process.stdout.write = originalStdoutWrite;
+		process.stderr.write = originalStderrWrite;
+	}
+
+	const combined = `${stdout}\n${stderr}`;
+	assert.match(combined, /visible stdout line/);
+	assert.match(combined, /visible stderr line/);
+	assert.doesNotMatch(combined, /node-domexception/);
+	assert.doesNotMatch(combined, /changed 343 packages/);
+	assert.doesNotMatch(combined, /packages are looking for funding/);
+	assert.doesNotMatch(combined, /npm fund/);
+});
+
+test("installPackageSources skips native packages on unsupported Node majors before invoking npm", async () => {
+	const root = mkdtempSync(join(tmpdir(), "feynman-package-ops-"));
+	const workingDir = resolve(root, "project");
+	const agentDir = resolve(root, "agent");
+	const markerPath = resolve(root, "npm-invoked.txt");
+	mkdirSync(workingDir, { recursive: true });
+
+	const scriptPath = writeFakeNpmScript(root, [
+		`import { writeFileSync } from "node:fs";`,
+		`writeFileSync(${JSON.stringify(markerPath)}, "invoked\\n", "utf8");`,
+		"process.exit(0);",
+	].join("\n"));
+
+	writeSettings(agentDir, {
+		npmCommand: [process.execPath, scriptPath],
+	});
+
+	const originalVersion = process.versions.node;
+	Object.defineProperty(process.versions, "node", { value: "25.0.0", configurable: true });
+	try {
+		const result = await installPackageSources(workingDir, agentDir, ["npm:@kaiserlich-dev/pi-session-search"]);
+		assert.deepEqual(result.installed, []);
+		assert.deepEqual(result.skipped, ["npm:@kaiserlich-dev/pi-session-search"]);
+		assert.equal(existsSync(markerPath), false);
+	} finally {
+		Object.defineProperty(process.versions, "node", { value: originalVersion, configurable: true });
+	}
+});
+
+test("updateConfiguredPackages batches multiple npm updates into a single install per scope", async () => {
+	const root = mkdtempSync(join(tmpdir(), "feynman-package-ops-"));
+	const workingDir = resolve(root, "project");
+	const agentDir = resolve(root, "agent");
+	const logPath = resolve(root, "npm-invocations.jsonl");
+	mkdirSync(workingDir, { recursive: true });
+
+	const scriptPath = writeFakeNpmScript(root, [
+		`import { appendFileSync } from "node:fs";`,
+		`import { resolve } from "node:path";`,
+		`const args = process.argv.slice(2);`,
+		`if (args.length === 2 && args[0] === "root" && args[1] === "-g") {`,
+		`  console.log(resolve(${JSON.stringify(root)}, "npm-global", "lib", "node_modules"));`,
+		`  process.exit(0);`,
+		`}`,
+		`appendFileSync(${JSON.stringify(logPath)}, JSON.stringify(args) + "\\n", "utf8");`,
+		"process.exit(0);",
+	].join("\n"));
+
+	writeSettings(agentDir, {
+		npmCommand: [process.execPath, scriptPath],
+		packages: ["npm:test-one", "npm:test-two"],
+	});
+	createInstalledGlobalPackage(root, "test-one", "1.0.0");
+	createInstalledGlobalPackage(root, "test-two", "1.0.0");
+
+	const originalFetch = globalThis.fetch;
+	globalThis.fetch = (async () => ({
+		ok: true,
+		json: async () => ({ version: "2.0.0" }),
+	})) as typeof fetch;
+
+	try {
+		const result = await updateConfiguredPackages(workingDir, agentDir);
+		assert.deepEqual(result.skipped, []);
+		assert.deepEqual(result.updated.sort(), ["npm:test-one", "npm:test-two"]);
+	} finally {
+		globalThis.fetch = originalFetch;
+	}
+
+	const invocations = readFileSync(logPath, "utf8").trim().split("\n").map((line) => JSON.parse(line) as string[]);
+	assert.equal(invocations.length, 1);
+	assert.ok(invocations[0]?.includes("install"));
+	assert.ok(invocations[0]?.includes("test-one@latest"));
+	assert.ok(invocations[0]?.includes("test-two@latest"));
+});
+
+test("updateConfiguredPackages skips native package updates on unsupported Node majors", async () => {
+	const root = mkdtempSync(join(tmpdir(), "feynman-package-ops-"));
+	const workingDir = resolve(root, "project");
+	const agentDir = resolve(root, "agent");
+	const logPath = resolve(root, "npm-invocations.jsonl");
+	mkdirSync(workingDir, { recursive: true });
+
+	const scriptPath = writeFakeNpmScript(root, [
+		`import { appendFileSync } from "node:fs";`,
+		`import { resolve } from "node:path";`,
+		`const args = process.argv.slice(2);`,
+		`if (args.length === 2 && args[0] === "root" && args[1] === "-g") {`,
+		`  console.log(resolve(${JSON.stringify(root)}, "npm-global", "lib", "node_modules"));`,
+		`  process.exit(0);`,
+		`}`,
+		`appendFileSync(${JSON.stringify(logPath)}, JSON.stringify(args) + "\\n", "utf8");`,
+		"process.exit(0);",
+	].join("\n"));
+
+	writeSettings(agentDir, {
+		npmCommand: [process.execPath, scriptPath],
+		packages: ["npm:@kaiserlich-dev/pi-session-search", "npm:test-regular"],
+	});
+	createInstalledGlobalPackage(root, "@kaiserlich-dev/pi-session-search", "1.0.0");
+	createInstalledGlobalPackage(root, "test-regular", "1.0.0");
+
+	const originalFetch = globalThis.fetch;
+	const originalVersion = process.versions.node;
+	globalThis.fetch = (async () => ({
+		ok: true,
+		json: async () => ({ version: "2.0.0" }),
+	})) as typeof fetch;
+	Object.defineProperty(process.versions, "node", { value: "25.0.0", configurable: true });
+
+	try {
+		const result = await updateConfiguredPackages(workingDir, agentDir);
+		assert.deepEqual(result.updated, ["npm:test-regular"]);
+		assert.deepEqual(result.skipped, ["npm:@kaiserlich-dev/pi-session-search"]);
+	} finally {
+		globalThis.fetch = originalFetch;
+		Object.defineProperty(process.versions, "node", { value: originalVersion, configurable: true });
+	}
+
+	const invocations = existsSync(logPath)
+		? readFileSync(logPath, "utf8").trim().split("\n").filter(Boolean).map((line) => JSON.parse(line) as string[])
+		: [];
+	assert.equal(invocations.length, 1);
+	assert.ok(invocations[0]?.includes("test-regular@latest"));
+	assert.ok(!invocations[0]?.some((entry) => entry.includes("pi-session-search")));
+});

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",
 	});
 
+	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-settings.test.ts

@@ -4,7 +4,13 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 
-import { CORE_PACKAGE_SOURCES, getOptionalPackagePresetSources, shouldPruneLegacyDefaultPackages } from "../src/pi/package-presets.js";
+import {
+	CORE_PACKAGE_SOURCES,
+	getOptionalPackagePresetSources,
+	NATIVE_PACKAGE_SOURCES,
+	shouldPruneLegacyDefaultPackages,
+	supportsNativePackageSources,
+} from "../src/pi/package-presets.js";
 import { normalizeFeynmanSettings, normalizeThinkingLevel } from "../src/pi/settings.js";
 
 test("normalizeThinkingLevel accepts the latest Pi thinking levels", () => {
@@ -71,3 +77,42 @@ test("optional package presets map friendly aliases", () => {
 	assert.deepEqual(getOptionalPackagePresetSources("search"), undefined);
 	assert.equal(shouldPruneLegacyDefaultPackages(["npm:custom"]), false);
 });
+
+test("supportsNativePackageSources disables sqlite-backed packages on Node 25+", () => {
+	assert.equal(supportsNativePackageSources("24.8.0"), true);
+	assert.equal(supportsNativePackageSources("25.0.0"), false);
+});
+
+test("normalizeFeynmanSettings prunes native core packages on unsupported Node majors", () => {
+	const root = mkdtempSync(join(tmpdir(), "feynman-settings-"));
+	const settingsPath = join(root, "settings.json");
+	const bundledSettingsPath = join(root, "bundled-settings.json");
+	const authPath = join(root, "auth.json");
+
+	writeFileSync(
+		settingsPath,
+		JSON.stringify(
+			{
+				packages: [...CORE_PACKAGE_SOURCES],
+			},
+			null,
+			2,
+		) + "\n",
+		"utf8",
+	);
+	writeFileSync(bundledSettingsPath, "{}\n", "utf8");
+	writeFileSync(authPath, "{}\n", "utf8");
+
+	const originalVersion = process.versions.node;
+	Object.defineProperty(process.versions, "node", { value: "25.0.0", configurable: true });
+	try {
+		normalizeFeynmanSettings(settingsPath, bundledSettingsPath, "medium", authPath);
+	} finally {
+		Object.defineProperty(process.versions, "node", { value: originalVersion, configurable: true });
+	}
+
+	const settings = JSON.parse(readFileSync(settingsPath, "utf8")) as { packages?: string[] };
+	for (const source of NATIVE_PACKAGE_SOURCES) {
+		assert.equal(settings.packages?.includes(source), false);
+	}
+});