# Technical Documentation: getcompanion-ai/feynman

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/getcompanion-ai/feynman)

### Overview (`README.md`)

<p align="center">
  <a href="https://feynman.is">
    <img src="assets/hero.png" alt="Feynman CLI" width="800" />
  </a>
</p>
<p align="center">The open source AI research agent.</p>
<p align="center">
  <a href="https://feynman.is/docs"><img alt="Docs" src="https://img.shields.io/badge/docs-feynman.is-0d9668?style=flat-square" /></a>
  <a href="https://github.com/Companion-Inc/feynman/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/Companion-Inc/feynman?style=flat-square" /></a>
  <a href="https://deepwiki.com/Companion-Inc/feynman"><img alt="Ask DeepWiki" src="https://deepwiki.com/badge.svg" /></a>
</p>

## Install

macOS / Linux:

```bash
curl -fsSL https://feynman.is/install | bash
```

Windows (PowerShell):

```powershell
irm https://feynman.is/install.ps1 | iex
```

Or with npm and Node.js 22.22 or newer: `npm install @companion-ai/feynman`.

Then sign in to a model provider:

```bash
feynman setup
```

The [installation guide](https://feynman.is/docs/getting-started/installation) covers pinned versions, uninstalling, and the skills-only bundle for Codex and OpenCode. The [setup guide](https://feynman.is/docs/getting-started/setup) covers local models and editors such as Zed.

## Use

```bash
feynman "what do we know about scaling laws"
feynman lit "RLHF alternatives"
feynman deepresearch "mechanistic interpretability"
```

| Workflow | What it does |
| --- | --- |
| `/deepresearch <topic>` | Planned investigation with parallel researchers and citation checks |
| `/lit <topic or lab>` | Literature review: consensus, disagreements, open questions |
| `/review <paper or draft>` | Critique with severity levels and a revision plan |
| `/audit <paper>` | Paper claims compared with its public code |
| `/replicate <paper>` | Replication plan; runs only after you choose an environment |
| `/recipe <task>` | Ranked ML training recipes with datasets and code |
| `/compare <topic>` | Source comparison matrix |
| `/draft <topic>` | Paper-style draft from research findings |
| `/autoresearch <idea>` | Bounded experiment loop against a benchmark |
| `/summarize <source>` | Summary of a paper, repository, or PDF |

Results are saved to `outputs/` (drafts to `papers/`). `/lit`, `/deepresearch`, and `/recipe` also write a provenance file listing the sources used and what was verified.

## Sources

Feynman searches alphaXiv, Semantic Scholar, OpenAlex, arXiv, PubMed, Europe PMC, bioRxiv, medRxiv, Crossref, the web, and Hugging Face, and reads local PDFs and documents. Free `OPENALEX_API_KEY` and `SEMANTIC_SCHOLAR_API_KEY` keys avoid the shared rate limits. It runs on stock [Pi](https://github.com/earendil-works/pi) with four research agents: researcher, verifier, reviewer, and writer.

## Telemetry

Feynman sends anonymous usage data to PostHog: commands, workflows, tools, models, token counts, and errors with their messages and stack traces (your home folder shown as `~`). It never sends prompts, model output, paper content, or tool arguments. Turn it off with `FEYNMAN_TELEMETRY=off`. [What is sent](https://feynman.is/docs/getting-started/configuration#telemetry)

## Contributing

```bash
git clone https://github.com/Companion-Inc/feynman.git
cd feynman
npm install
npm test
```

See [CONTRIBUTING.md](CONTRIBUTING.md).

[Docs](https://feynman.is/docs) · [Release notes](RELEASES.md) · [MIT License](LICENSE)

---

### Overview (`evals/README.md`)

# Research-quality evals

A small fixed eval for Feynman's research workflows. It runs `/lit` (or `/deepresearch`) on each question in `questions.jsonl`, then scores the artifacts with deterministic checks against arXiv, Crossref and doi.org. No LLM judge.

This directory is not in the npm package (`package.json` `files` does not list it).

## Rule

Run the eval before and after any change to prompts (`prompts/`, `.feynman/agents/`, `.feynman/SYSTEM.md`, `skills/`), tools, extensions, or the Pi version. Use the same model and question ids for both runs, and commit both result files with the change.

## Run

Build first (`npm ci && npm run build`). Each question gets a fresh temp workspace and its own `FEYNMAN_HOME`, so your real `~/.feynman` is never read or written. The model's provider comes from a `models.json` that is copied into each isolated home. Example for an OpenAI-compatible gateway (the key is read from the environment and never written to disk):

```json
{
  "providers": {
    "ferrylane-openai": {
      "baseUrl": "https://gateway.ferrylane.ai/v1",
      "api": "openai-responses",
      "apiKey": "$FERRYLANE_API_KEY",
      "models": [
        { "id": "gpt-5.6-terra", "reasoning": true, "input": ["text"], "contextWindow": 400000, "maxTokens": 64000 }
      ]
    }
  }
}
```

```sh
export FERRYLANE_API_KEY="$(cat ~/.ferrylane/api-key)"
node evals/run.mjs --model ferrylane-openai/gpt-5.6-terra --models-json /path/to/models.json \
  [--ids q01,q04] [--workflow lit|deepresearch] [--concurrency 2] [--timeout-min 45]
```

Built-in providers work the same way; pass their API key env var (for example `OPENAI_API_KEY`) and omit `--models-json`.

`--workflow deepresearch` sends one approval turn (`--continue`) after the plan gate. `--rescore evals/results/<file>.jsonl` re-scores the kept workdirs without rerunning Feynman, which is useful after a scorer change.

Output goes to `evals/results/<date>-<workflow>-<model>.jsonl` (one row per question: git SHA, dirty flag, Feynman version, scores, citation failures, usage, and the `workdir` (under `~/.cache/feynman-evals/` by default, `--work-root` to change) holding the full workspace, session JSONL and `feynman.log`) and a `.md` summary table.

## Scores

| Column | Meaning |
|---|---|
| `done` | A final `outputs/<slug>.md` exists with its `outputs/<slug>.provenance.md` sidecar. |
| `cites` | Distinct arXiv IDs and DOIs in the final output. |
| `valid` | Share of those identifiers that resolve (arXiv API `id_list`; Crossref, falling back to the doi.org handle API for non-Crossref DOIs). Lookups that fail on the network are left out. Unresolvable IDs are listed in `unresolved`. |
| `title` | Among resolved IDs with a known title, the share that match the output: the resolved title is at least 60% present (by word tokens) on a line that carries the ID, or, for author-year citations, the resolved first author's surname is on that line. Low values flag IDs attached to the wrong paper; see `title_mismatch`. Short-name citations ("When2Think, arXiv:…") also miss, so read the listed rows before calling something a hallucination. |
| `recall` | Share of the question's expected key papers that appear in the final output, by any listed identifier or by exact normalized title. 0 when there is no final output. |
| `wall`, `tokens`, `cost` | Wall time for the whole run, and token and cost totals summed over every Pi session file in the isolated home and temp dir (parent and subagent sessions, deduplicated). Cost is 0 when the provider's `models.json` entry has no `cost` block. |

The first baseline, `results/2026-09-23-lit-ferrylane-openai_claude-sonnet-5.*`, ran q01, q04, q07 and q10 on Feynman 0.5.0. It used `claude-sonnet-5` through the Ferrylane gateway because the gateway's GPT quota was exhausted that day.

Treat a single run as noisy. Compare before and after on the same ids, and look at the listed failures rather than only the percentages.

## Questions

`questions.jsonl` has 12 questions, each with expected key papers and a `source`:

- `q01`–`q06`: the six queries from Feynman's paper-discovery search benchmark (test-time compute, speculative decoding, sparse autoencoders, CRISPR base editing, mixture of experts, RAG).
- `q07`–`q09`: verbatim questions from LitQA2 ([futurehouse/lab-bench](https://huggingface.co/datasets/futurehouse/lab-bench), CC-BY-SA-4.0). The key paper is the item's `sources` DOI. These three items are redistributed under CC-BY-SA-4.0 with that attribution.
- `q10`–`q12`: hand-authored topics outside ML and biology (econometrics, weather forecasting, cosmology) whose key papers are unambiguous.

Keep the set fixed. Adding or editing a question breaks comparison with earlier result files; if you must, bump the question id instead of reusing one.

Next lanes, not built yet: ScholarQA-CS2 (AstaBench) citation precision and recall for `/lit`, DeepResearch Bench FACT for `/deepresearch`, and SciCoQA's 92 real paper–code discrepancies for `/audit` recall.

---

### Overview (`website/README.md`)

# Astro + React + TypeScript + shadcn/ui

This is a template for a new Astro project with React, TypeScript, and shadcn/ui.

## Adding components

To add components to your app, run the following command:

```bash
npx shadcn@latest add button
```

This will place the ui components in the `src/components` directory.

## Using components

To use the components in your app, import them in an `.astro` file:

```astro
---
import { Button } from "@/components/ui/button"
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    <title>Astro App</title>
  </head>
  <body>
    <div class="grid h-screen place-items-center content-center">
      <Button>Button</Button>
    </div>
  </body>
</html>
```

---

### Website Src Content Docs Getting Started Quickstart (`website/src/content/docs/getting-started/quickstart.md`)

---
title: Quick Start
description: Start using Feynman for paper search, research workflows, and code-aware review.
section: Getting Started
order: 2
---

This guide assumes you have [installed Feynman](/docs/getting-started/installation) and run `feynman setup`.

## Launch the REPL

```bash
feynman
```

This opens an interactive session in the current directory. An interactive launch continues the most recent session for that directory; pass `--new-session` to start fresh. Type a research question and press Enter.

## Run a one-shot prompt

To get one answer without entering the REPL:

```bash
feynman --prompt "Summarize the key findings of Attention Is All You Need"
```

Feynman prints the response and exits.

## Start a deep research run

```bash
feynman
> /deepresearch What are the current approaches to mechanistic interpretability in LLMs?
```

Feynman first writes a plan to `outputs/.plans/<slug>.md` and asks you to confirm it. After you reply `yes`, it gathers evidence, delegating to researcher agents when the topic is broad enough, then drafts, verifies citations, and writes the final brief to `outputs/<slug>.md` with a `.provenance.md` sidecar.

## Find an ML training recipe

For applied ML work, use `/recipe` when you need a practical starting point rather than a broad literature survey:

```bash
feynman recipe "fine-tune a small model for math reasoning"
```

Feynman ranks candidate recipes by result quality and feasibility, checks datasets and implementation paths when possible, and writes the brief to `outputs/<slug>-recipe.md`.

## Work with files

Feynman reads and writes files in its working directory. Use `--cwd` to point it at a project folder:

```bash
feynman --cwd ~/papers
> /review arxiv:2301.07041
```

You can also reference local files directly in prompts.

## Explore commands

Type `/help` inside the REPL to see Feynman's commands. Every research workflow also runs directly from the shell:

```bash
feynman deepresearch "transformer architectures for protein folding"
```

See the [Slash Commands](/docs/reference/slash-commands) and [CLI Commands](/docs/reference/cli-commands) references.

---

### Website Src Content Docs Agents Researcher (`website/src/content/docs/agents/researcher.md`)

---
title: Researcher
description: The researcher agent gathers primary evidence from papers, web sources, repos, and datasets.
section: Agents
order: 1
---

The researcher is Feynman's evidence-gathering subagent. It searches paper databases and the web, reads the most relevant sources, and writes an evidence file that the lead agent synthesizes. Its definition lives in `.feynman/agents/researcher.md`.

## What it does

The researcher receives a task brief from a workflow, searches broadly, then narrows using the terminology and names it finds. It runs 2–4 reworded queries for each question and merges the results instead of trusting one query's ranking.

For broad deep research and literature review tasks, workflow prompts can run several researchers in parallel through one async workflow script, `outputs/.plans/<slug>-workflow.js`, using `await runs.all([{key, agent, task, output}, ...])` and run with `subagent({ workflow: "./outputs/.plans/<slug>-workflow.js" })`, each covering a different angle. The lead agent consumes the ordered results and verifies the declared output files before synthesis. Narrow tasks skip the researcher and stay lead-owned.

## Tools

The researcher runs with high thinking and these tools: file and shell tools (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`), `web_search`, `fetch_content`, `get_search_content`, `feynman_science_database_search`, and the Hugging Face tools `hf_dataset_info`, `hf_repo_files`, and `hf_repo_read_file`. It does not load the `alpha_*` tools; it uses `feynman alpha search` through the shell when alphaXiv is logged in.

## Source routing

| Need | First choice | Then |
| --- | --- | --- |
| General ML/CS papers | Semantic Scholar (citation-sorted) | `feynman alpha search` when logged in |
| Biomedical papers | PubMed, then Europe PMC for open-access full-text sections | Semantic Scholar for citation counts |
| Citation graph | OpenAlex citations and references | Semantic Scholar citation counts |
| Conceptual or recent work keyword search misses | OpenAlex semantic search | Semantic Scholar by relevance |
| Web, docs, repos, grey literature | `web_search` | `fetch_content` on the best results |
| Known paper ID | arXiv ID or Crossref DOI lookup | `fetch_content` on `arxiv.org/html/<id>` |

## Output

The researcher writes to the output path the workflow assigns. The file contains an evidence table with stable numeric source IDs and at least five entries, findings that cite those IDs inline, a numbered Sources list with direct URLs, and a Coverage Status section listing what was checked, what remains uncertain, and any tasks it could not complete. It returns a one-line summary to the lead agent rather than the full findings.

Every source needs a checkable URL, and the researcher labels inferences separately from claims it read directly.

For ML training, replication, benchmark, or dataset tasks, it organizes findings as ranked recipes: reported result, dataset (size, split, access, schema if checked), method and hyperparameters, compute, implementation code paths, and a verification status of `verified`, `unverified`, `blocked`, or `inferred`. A dataset is not described as usable unless its availability and format were checked.

## Used by

Workflows that can delegate to the researcher: `/deepresearch`, `/lit`, `/review`, `/audit`, `/replicate`, `/recipe`, `/compare`, and `/summarize` (one researcher per chunk for very large sources).

---

### Website Src Content Docs Agents Reviewer (`website/src/content/docs/agents/reviewer.md`)

---
title: Reviewer
description: The reviewer agent critiques research artifacts with severity-graded findings.
section: Agents
order: 2
---

The reviewer applies skeptical but fair internal research scrutiny to papers, drafts, and research artifacts. It does not predict venue acceptance; it produces a critique and a revision plan. Its definition lives in `.feynman/agents/reviewer.md`.

## What it does

The reviewer checks novelty, clarity, empirical rigor, and reproducibility. It looks for missing or weak baselines, missing ablations, evaluation mismatches, benchmark leakage, insufficient statistical evidence, claims that outrun the experiments, sections left over from earlier drafts, notation drift, and "verified" statements that do not show the check behind them. It keeps looking after the first major problem.

When a workflow frames the task as a verification pass, the reviewer acts as an adversarial auditor: a citation attached to a claim is not enough if the source does not support its exact wording.

## Output

The reviewer writes two parts to the output path the workflow assigns:

1. **Structured review** -- summary, strengths, weaknesses graded **FATAL**, **MAJOR**, or **MINOR**, questions for the authors, a verdict with an overall confidence score, and a prioritized revision plan.
2. **Inline annotations** -- exact quotes from the artifact, each tied to a weakness or question ID from the structured review.

Every weakness must point to a specific passage or section. The review ends with a Sources section for anything it inspected.

## Used by

- `/review` -- the main critique pass on larger artifacts
- `/deepresearch` -- reviews the cited brief after the verifier finishes, when researcher subagents were used
- `/lit` -- checks the cited review for unsupported claims, logical gaps, and single-source critical findings

Workflows fix FATAL issues before delivery and record MAJOR issues as open questions.

---

### Website Src Content Docs Agents Verifier (`website/src/content/docs/agents/verifier.md`)

---
title: Verifier
description: The verifier agent adds inline citations and checks every source behind a draft.
section: Agents
order: 4
---

The verifier post-processes a draft: it anchors each factual claim to a source from the research files, checks that every source URL resolves and supports the claim, and removes what cannot be supported. Its definition lives in `.feynman/agents/verifier.md`.

## What it does

1. **Anchor claims** -- insert inline citations such as `[1]` after each factual claim, merging the numbering from multiple research files into one sequence.
2. **Verify URLs** -- fetch each source with `fetch_content`. Dead links and redirects to unrelated content are replaced with an alternative, such as an archived copy, or removed along with claims that depended only on them.
3. **Check meaning** -- a citation counts only if the source supports the specific number, quote, or conclusion attached to it.
4. **Check paper identity** -- look up each cited DOI or arXiv ID in two indexes (arXiv or Crossref, plus OpenAlex or Semantic Scholar) and flag any title, year, or first-author mismatch instead of keeping the citation silently.
5. **Audit results** -- scores, benchmarks, tables, figures, dataset sizes, and claims of improvement must map to a source URL, research note, raw artifact, or script. Anything that does not is removed or turned into a TODO.
6. **Build Sources** -- a numbered list at the end where every entry is cited at least once and every citation has an entry.

It does not use words like `verified` or `confirmed` unless the underlying evidence is present. When it removes material, it adds a short Removed Unsupported Claims section.

## Tools

The verifier runs with medium thinking and these tools: file and shell tools (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`), `web_search`, `fetch_content`, `get_search_content`, and `feynman_science_database_search`.

## Output

The verifier writes the complete cited document to the output path the workflow assigns. It keeps the draft's structure but may delete or soften unsupported claims.

## Used by

- `/deepresearch` -- cites the draft when researcher subagents were used, before the reviewer runs
- `/lit` -- cites the literature review before the reviewer checks it
- `/draft` -- cites the writer's draft
- `/compare` -- cites the final comparison matrix
- `/audit` -- verifies sources and adds citations for non-trivial audits

---

### Website Src Content Docs Agents Writer (`website/src/content/docs/agents/writer.md`)

---
title: Writer
description: The writer agent turns research notes into structured briefs and drafts.
section: Agents
order: 3
---

The writer turns research files into a clear, structured document. It writes only from the evidence it is given and leaves citation to the verifier. Its definition lives in `.feynman/agents/writer.md`.

## What it does

The writer reads the research files a workflow supplies and organizes them into a draft with an executive summary, themed sections, and an Open Questions section for unresolved issues, gaps, and disagreements between sources.

It does not introduce claims, tools, or sources that are not in the input files. Caveats and disagreements stay in the text, and tentative or inferred results are labeled as such. Missing results become gaps or TODOs, never plausible-looking data.

The writer has file and shell tools only (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`); it has no search or fetch tools.

## Citations

The writer does not add inline citations or a Sources section. The [verifier](/docs/agents/verifier) adds both in a separate pass. Before finishing, the writer checks that every strong factual statement has an obvious home in the research files.

## Visuals

The writer uses Markdown tables for quantitative comparisons and Mermaid diagrams for architectures or pipelines, only when the supplied evidence supports them. Plots use source-backed data only, with the plotting script saved next to the draft. Every visual gets a caption that names its data source.

## Used by

The `/draft` workflow uses the writer when the draft should be produced from already-collected notes, then runs the verifier on its output. Other workflows, including `/deepresearch`, have the lead agent write the draft directly.

---

### Website Src Content Docs Getting Started Configuration (`website/src/content/docs/getting-started/configuration.md`)

---
title: Configuration
description: Understand Feynman's configuration files and environment variables.
section: Getting Started
order: 4
---

Feynman stores user-level configuration and state under `~/.feynman/`, created on first run. Set `FEYNMAN_HOME` to use `<FEYNMAN_HOME>/.feynman` instead.

## Directory structure

```
~/.feynman/
├── agent/                  # Pi agent dir (PI_CODING_AGENT_DIR)
│   ├── settings.json       # Default model, thinking level, packages
│   ├── auth.json           # Provider credentials (user-only permissions)
│   ├── models.json         # Custom and local providers
│   ├── web-search.json     # Web search provider and keys
│   ├── web-search-cache/   # Fetched pages, kept for one hour
│   ├── extensions/subagent/config.json  # Subagent runtime config
│   └── npm/                # Optional Pi packages from `feynman packages install`
├── sessions/               # Session transcripts (JSONL)
├── bin/                    # `feynman` shim used by child agents
└── .state/                 # Telemetry install ID and first-run notice state
```

`agent/settings.json` is the main configuration file. Feynman fills in missing defaults on every launch, and you can edit it by hand. The model fields look like:

```json
{
  "defaultProvider": "openai",
  "defaultModel": "gpt-5.6-terra",
  "defaultThinkingLevel": "medium"
}
```

## Model configuration

`defaultProvider` and `defaultModel` set the model used when you launch without `--model`. Only providers you have authenticated appear in `feynman model list`. To add a provider, sign in to it, then switch the default:

```bash
feynman model login anthropic
feynman model list
feynman model set anthropic/claude-opus-5-5
```

`feynman model login` with no provider shows the OAuth and API-key choices. `model set` accepts `provider/model` or `provider:model`. Pro-class model IDs are rejected here and in `--model`. See [Setup](/docs/getting-started/setup) for OAuth on headless machines, Amazon Bedrock, and local models.

## Web search configuration

Web search, page fetching, and PDF extraction come from the bundled `pi-web-access` package, configured in `~/.feynman/agent/web-search.json`. The default `auto` route works without keys through Exa and uses any other provider you have configured. Set a provider and key from the CLI:

```bash
feynman search status
feynman search set brave <api-key>   # or exa, tavily, perplexity, kagi, auto, ... (`feynman search set` lists all)
feynman search clear                      # back to auto, keys kept
```

The [pi-web-access README](https://github.com/nicobailon/pi-web-access#readme) documents every provider and option, including PDF extraction.

## Subagent model overrides

The bundled subagents (`researcher`, `reviewer`, `writer`, `verifier`) inherit the main research model. To pin one to another model, use `/subagents` or set `subagents.agentOverrides.<name>.model` in `~/.feynman/agent/settings.json`; remove it to inherit again. Feynman sets `subagents.agentExcludeDirs` to `["~/.agents"]` so agent files there cannot replace the bundled agents, and `subagents.defaultSubagentOnlyExtensions` to its research tools and pi-web-access so every subagent can search, including foreground runs. It rewrites that list on each launch unless you replace it with your own.

The subagent runtime config at `~/.feynman/agent/extensions/subagent/config.json` defaults to background delegation on and missions and the fleet view off. Feynman fills in only missing values and leaves your changes alone.

## Thinking levels

`defaultThinkingLevel` sets how much the model reasons before responding: `off`, `minimal`, `low`, `medium` (default), `high`, `xhigh`, or `max`, subject to the active model's capabilities. Override it for one run:

```bash
feynman --thinking high
```

## Environment variables

Feynman reads these environment variables. `FEYNMAN_MODEL`, `FEYNMAN_THINKING`, and `FEYNMAN_SERVICE_TIER` override `settings.json` for that run. Feynman also loads a `.env` file from the current directory.

| Variable | Description |
| --- | --- |
| `FEYNMAN_MODEL` | Model to use instead of the default (same as `--model`) |
| `FEYNMAN_HOME` | Override the parent directory used to create `.feynman` (default parent: `~`) |
| `FEYNMAN_THINKING` | Thinking level (same as `--thinking`) |
| `FEYNMAN_SERVICE_TIER` | Request service tier (same as `--service-tier`) |
| `ANTHROPIC_API_KEY` | Anthropic API key |
| `OPENAI_API_KEY` | OpenAI API key |
| `GEMINI_API_KEY` | Google Gemini API key |
| `DATALAB_API_KEY` | Optional Datalab key for layout-aware PDF-to-Markdown extraction |
| `AWS_PROFILE` | Preferred AWS profile for Amazon Bedrock |
| `EXA_API_KEY`, `PERPLEXITY_API_KEY`, `TAVILY_API_KEY`, ... | Web search provider keys read by pi-web-access |
| `OPENALEX_API_KEY` | Free OpenAlex key ([create one](https://openalex.org/settings/api)); without one, requests share a small anonymous daily budget |
| `SEMANTIC_SCHOLAR_API_KEY` | Optional free Semantic Scholar key ([request one](https://www.semanticscholar.org/product/api#api-key-form)) so searches use your own rate limit instead of the shared anonymous pool |
| `CROSSREF_MAILTO` | Your email, sent to Crossref so requests use its faster polite pool (3 per second instead of 1) |
| `NCBI_API_KEY` | Optional NCBI E-utilities key; NCBI allows 10 requests per second with a key instead of 3 |
| `FEYNMAN_TELEMETRY` | Set to `off` to disable all Feynman telemetry (`DO_NOT_TRACK=1` also works) |

## Telemetry

Feynman collects anonymous usage telemetry by default and shows a one-time notice the first time it runs: inside the interactive session (including Pi's fullscreen UI), or on stderr for a one-shot `--prompt` run. Telemetry goes to Feynman's PostHog project under a random install ID stored in `~/.feynman/.state/telemetry.json`. Person profiles and GeoIP lookup are off.

Feynman never sends prompts, model output, paper or document content, or tool arguments. When something fails, it sends the error message and stack trace, the end of Pi's error output, and a failed tool's error text, with your home folder shown as `~`. These can include file paths inside your projects.

To opt out, set either variable in your shell profile:

```bash
export FEYNMAN_TELEMETRY=off
export DO_NOT_TRACK=1
```

`feynman status` shows whether telemetry is on.

What is sent:

| Event | Properties |
|-------|------------|
| `feynman_command_started`, `feynman_command_completed`, `feynman_command_failed` | Command and allow-listed subcommand, output mode, whether a prompt, model, service tier, or new-session flag was given, duration, exit code, error name and message; for a failed run, the last lines of Pi's error output. Errors thrown by Feynman also go to PostHog error tracking with their stack trace |
| `feynman_session_started` | Why the session started (startup, resume, new, fork, reload), mode, model and provider name |
| `feynman_workflow_started` | Workflow name (`deepresearch`, `lit`, `review`, and so on; `chat` for anything else) |
| `feynman_workflow_completed` | Workflow name, status (`completed`, `error`, `aborted`), tool and subagent call counts, whether any file under `outputs/` or `papers/` was written (yes or no), duration |
| `feynman_tool_used` | Tool name, whether it failed and its error text, whether a subagent called it |
| `$ai_generation` | [PostHog LLM analytics](https://posthog.com/docs/llm-analytics/generations) metadata for each model response: model, provider, input, output, and cache token counts, latency, HTTP status, stop reason, error flag and provider error message, and the Pi session ID as the trace ID. No `$ai_input` or `$ai_output_choices`. |

Every event also carries the Feynman version, Node.js version, platform, and CPU architecture.

Each send is tried once. The first network or ingest failure turns telemetry off for the rest of that process without printing anything; set `FEYNMAN_DEBUG=1` to see the single CLI diagnostic.

## Session storage

Sessions are saved as JSONL files in `~/.feynman/sessions/`. An interactive `feynman` launch continues the most recent session for the current directory. Session flags:

```bash
feynman --new-session                 # start a new session
feynman --resume                      # pick a previous session
feynman --session <path|id>           # open a specific session
feynman --fork <path|id>              # fork a session into a new one
feynman --no-session                  # in-memory session, not saved
feynman --export <session.jsonl> [out.html]   # export a session to HTML
feynman --session-dir <path>          # store sessions somewhere else
```

## Diagnostics

`feynman doctor` checks alphaXiv auth, the default model and authenticated providers, `models.json`, pandoc, web search config, and the Pi runtime, and prints next steps. It reports `quietStartup: "header"` as "header only". `feynman status` prints a shorter summary.

---

### Website Src Content Docs Getting Started Installation (`website/src/content/docs/getting-started/installation.md`)

---
title: Installation
description: Install Feynman on macOS, Linux, or Windows with curl, PowerShell, or npm.
section: Getting Started
order: 1
---

Feynman installs either as a standalone bundle or as an npm package. The standalone installer is the simplest path: it downloads a prebuilt bundle with its own Node.js runtime and verifies the release SHA-256 before installing.

## One-line installer (recommended)

On **macOS or Linux**:

```bash
curl -fsSL https://feynman.is/install | bash
```

The installer supports macOS (Apple Silicon and Intel) and Linux (x64 and arm64). It installs the launcher to `~/.local/bin`, unpacks the bundle into `~/.local/share/feynman`, and updates your `PATH` when needed.

If you previously installed Feynman with npm and your shell still runs the old binary, run `which -a feynman`, then `hash -r`, or launch `~/.local/bin/feynman` directly.

On **Windows**, in PowerShell:

```powershell
irm https://feynman.is/install.ps1 | iex
```

This installs the Windows x64 bundle under `%LOCALAPPDATA%\Programs\feynman` and adds its launcher to your user `PATH`. Windows 11 on Arm runs the same bundle through x64 emulation.

Feynman runs shell commands with Bash, so on Windows also install [Git for Windows](https://git-scm.com/download/win), which provides it. Without Bash, research runs fail at the first shell command with `No bash shell found`. To use another Bash (MSYS2, Cygwin), set `shellPath` in `~/.feynman/agent/settings.json`.

## Alternative: npm

To install into an existing Node.js environment instead:

```bash
npm install @companion-ai/feynman
```

This uses your local Node.js, which must satisfy `>=22.22.0`. npm installs Feynman's Pi runtime as a peer dependency, so if your npm config sets `legacy-peer-deps`, add `--legacy-peer-deps=false`.

If you installed the interim `@advaitpaliwal/feynman` package, migrate once:

```bash
npm uninstall -g @advaitpaliwal/feynman
npm install @companion-ai/feynman
```

## Updating

Rerun the installer you originally used to get the latest tagged release. For npm installs:

```bash
npm install @companion-ai/feynman@latest
```

`feynman update` only updates optional Pi packages you installed with `feynman packages install`. The core packages update with Feynman itself.

## Pinned releases

To install an exact version:

```bash
curl -fsSL https://feynman.is/install | bash -s -- 0.5.3
```

On Windows:

```powershell
& ([scriptblock]::Create((irm https://feynman.is/install.ps1))) -Version 0.5.3
```

## Uninstalling

Feynman has no `uninstall` command. Remove the launcher and bundle, and optionally the Feynman home directory (settings, sessions, installed packages) and `~/.ahub` (alphaXiv login).

On macOS or Linux:

```bash
rm -f ~/.local/bin/feynman
rm -rf ~/.local/share/feynman
# optional: settings, sessions, and installed packages
rm -rf ~/.feynman
# optional: alphaXiv login
rm -rf ~/.ahub
```

On Windows PowerShell:

```powershell
Remove-Item "$env:LOCALAPPDATA\Programs\feynman" -Recurse -Force
# optional: settings, sessions, and installed packages
Remove-Item "$HOME\.feynman" -Recurse -Force
# optional: alphaXiv login
Remove-Item "$HOME\.ahub" -Recurse -Force
```

Then remove `%LOCALAPPDATA%\Programs\feynman\bin` from your user `PATH`.

For npm installs:

```bash
npm uninstall -g @companion-ai/feynman
```

## Skills only

To install only Feynman's research skills, without the terminal app, into `~/.codex/skills/feynman` for Codex:

```bash
curl -fsSL https://feynman.is/install-skills | bash
```

To name the target explicitly, use `--codex`. For a repo-local install into `.agents/skills/feynman`, or an OpenCode install into `.opencode/skills/feynman`, pass a scope:

```bash
curl -fsSL https://feynman.is/install-skills | bash -s -- --codex
curl -fsSL https://feynman.is/install-skills | bash -s -- --repo
curl -fsSL https://feynman.is/install-skills | bash -s -- --opencode
```

On Windows:

```powershell
irm https://feynman.is/install-skills.ps1 | iex
& ([scriptblock]::Create((irm https://feynman.is/install-skills.ps1))) -Scope Codex
& ([scriptblock]::Create((irm https://feynman.is/install-skills.ps1))) -Scope Repo
& ([scriptblock]::Create((irm https://feynman.is/install-skills.ps1))) -Scope OpenCode
```

These installers copy the `skills/` and `prompts/` trees plus `AGENTS.md` and `CONTRIBUTING.md`. They do not install the Feynman terminal, its Node.js runtime, or Pi packages.

## After installing

Check the install:

```bash
feynman --version
```

Then run `feynman setup` to connect a model provider (see [Setup](/docs/getting-started/setup)). `feynman doctor` diagnoses configuration, authentication, and runtime problems.

---

### Website Src Content Docs Getting Started Setup (`website/src/content/docs/getting-started/setup.md`)

---
title: Setup
description: Walk through the guided setup wizard to configure Feynman.
section: Getting Started
order: 3
---

`feynman setup` connects a model provider, offers optional packages, signs you in to alphaXiv, and offers to install pandoc for preview. You can rerun it at any time.

When you launch `feynman` without a usable model, it asks only for the model. If you set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` first, it skips the question and opens the chat. If you cancel, Feynman exits and prints how to add a model; nothing you typed is sent.

```bash
feynman setup
```

## Model access

If no authenticated model is available yet, setup asks how to connect one:

```text
Choose how to configure model access:
> OAuth login (recommended: ChatGPT, Claude Max, Copilot, ...)
  API key or custom provider (OpenAI, Anthropic, ZAI, Kimi, MiniMax, ...)
  Cancel
```

OAuth opens a browser to sign in. On a remote or headless machine where the browser callback cannot reach Feynman, paste the final redirect URL or authorization code into the prompt. The API-key flow lists every provider Pi can sign in to with a key (OpenAI, Anthropic, Google, DeepSeek, Fireworks, Together, NVIDIA, Amazon Bedrock, Google Vertex and more), plus LM Studio, LiteLLM and custom OpenAI-compatible servers. Pi asks for what that provider needs. You can also skip the prompt and set the provider's environment variable (for example `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`) instead.

Credentials are stored in `~/.feynman/agent/auth.json` with user-only file permissions. Setting the key in your shell or `.env` keeps it off disk.

Once a provider is connected, setup picks the recommended research model from what you are signed in to, such as `openai/gpt-5.6-terra` or `anthropic/claude-opus-5-5`. If you already have a valid default, setup keeps it. To change it later:

```bash
feynman model list
feynman model set <provider/model>
```

`model set` also accepts `provider:model`. Run `feynman model set` with no model to pick from a list. Pro-class model IDs are rejected.

### Amazon Bedrock

Choose `Amazon Bedrock`. Pi asks how to sign in: a Bedrock bearer token, an AWS profile, or the AWS credentials already on the machine (`AWS_PROFILE`, `~/.aws`, SSO, ECS/IRSA, and EC2 instance roles). Bedrock models then appear in `feynman model list`.

### Local models: LM Studio, LiteLLM, Ollama, vLLM

For LM Studio, start its local server, load a model, and choose `LM Studio (local OpenAI-compatible server)`. The defaults are:

```text
Base URL: http://localhost:1234/v1
API key: lm-studio
```

For LiteLLM, start the proxy and choose `LiteLLM Proxy (OpenAI-compatible gateway)`. The default base URL is `http://localhost:4000/v1`; if the proxy requires a master key, Feynman reads it from `LITELLM_MASTER_KEY`.

For both, Feynman reads the server's `/models` endpoint to prefill model IDs.

For Ollama, vLLM, or another OpenAI-compatible server, choose `Custom provider (local/self-hosted/proxy)`. Typical Ollama settings:

```text
API mode: openai-completions
Base URL: http://localhost:11434/v1
Send Authorization header: No
API key / resolver: local
Model id(s): llama3.1:8b
```

Custom providers are saved to `~/.feynman/agent/models.json`. Pi only lists a provider that has an `apiKey`, so if you edit that file by hand, keep a placeholder such as `"apiKey": "local"` for a local server. To read a key from an environment variable, write it as `"$MY_API_KEY"`; a bare name such as `MY_API_KEY` is sent as the key itself. Then confirm and select the model:

```bash
feynman model list
feynman model set <provider>/<model-id>
```

Small local models often skip the multi-step research workflows and reply in chat without writing files to `outputs/`. A context window that is too small causes the same symptom: Ollama's default is only a few thousand tokens. Serve the model with a larger one (for example `OLLAMA_CONTEXT_LENGTH=65536 ollama serve`) and set the matching `contextWindow` and `maxTokens` on the model's entry in `~/.feynman/agent/models.json`, since custom models otherwise default to 128k and 16k.

## Optional packages

Feynman ships with alphaXiv access, web access, document parsing, subagents, and `/btw` side conversations. Setup can also install optional Pi packages:

- **memory**: preference and correction memory across research sessions
- **hindsight**: Hindsight-backed memory; requires a Hindsight server or Hindsight Cloud account

Skip this step and install later with `feynman packages install <preset>`; remove one with `feynman packages remove <preset>`. `feynman packages list` shows both.

## alphaXiv and preview

Setup then offers to sign you in to alphaXiv (same as `feynman alpha login`) and to install pandoc for Markdown-to-HTML/PDF preview (same as `feynman setup preview`).

## Editor integration (ACP)

Feynman runs in ACP editors through [pi-acp](https://github.com/svkozak/pi-acp). In Zed, add to `settings.json`:

```json
"agent_servers": {
  "Feynman": {
    "command": "npx",
    "args": ["-y", "pi-acp"],
    "env": { "PI_ACP_PI_COMMAND": "feynman" }
  }
}
```

## Rerunning setup

Settings live in `~/.feynman/agent/settings.json`. Rerunning setup keeps a valid default model and your other settings. To change one thing, use a targeted command such as `feynman model set`, `feynman model login <provider>`, or `feynman alpha login`, or edit the file directly.

---

### Website Src Content Docs Reference Cli Commands (`website/src/content/docs/reference/cli-commands.md`)

---
title: CLI Commands
description: Complete reference for all Feynman CLI commands and flags.
section: Reference
order: 1
---

This page covers the Feynman CLI commands and flags. `feynman help` prints the same list. Workflow commands like `feynman deepresearch` map directly to the REPL [slash commands](/docs/reference/slash-commands).

## Core commands

| Command | Description |
| --- | --- |
| `feynman` | Launch the interactive REPL |
| `feynman chat [prompt]` | Start chat explicitly, optionally with an initial prompt |
| `feynman help` | Show CLI help |
| `feynman setup` | Run the guided setup wizard |
| `feynman setup preview` | Install or verify pandoc |
| `feynman doctor` | Diagnose config, auth, Pi runtime, and preview dependencies |
| `feynman status` | Show the current setup summary (model, auth, alphaXiv, web access, service tier, telemetry) |

## Model management

| Command | Description |
| --- | --- |
| `feynman model list` | List available models in Pi auth storage |
| `feynman model login [id]` | Authenticate a model provider with OAuth or API-key setup |
| `feynman model logout [id]` | Clear stored auth for a model provider |
| `feynman model set [provider/model]` | Set the default approved research model for all sessions; without one, pick from a list |
| `feynman model tier [value]` | View or set the request service tier override |

The `model set` command updates `~/.feynman/agent/settings.json` with the new default. It accepts either `provider/model-name` or `provider:model-name`; run `feynman model list` first and choose a model ID from that output, or run `feynman model set` alone to pick from the available models. When a model is not usable, the error says why: no credentials for its provider, a local provider in `models.json` without an `apiKey` placeholder, or close matches for an unknown ID. `feynman model help` lists these commands. `feynman model login <id>` goes straight to API-key setup for API-key providers such as `google`, `amazon-bedrock`, and `openrouter`. For OAuth logins in SSH or other headless sessions, paste the final redirect URL into Feynman when the browser runs on another machine.

## AlphaXiv commands

| Command | Description |
| --- | --- |
| `feynman alpha login` | Sign in to alphaXiv |
| `feynman alpha logout` | Clear alphaXiv auth |
| `feynman alpha status` | Check alphaXiv auth status |
| `feynman alpha search "query"` | Search papers through Feynman's bundled alphaXiv client |
| `feynman alpha get <id-or-url>` | Fetch paper content and local annotations |
| `feynman alpha ask <id-or-url> "question"` | Ask a question about a paper |
| `feynman alpha code <github-url> [path]` | Inspect a paper repository |
| `feynman alpha annotate ...` | Read, write, list, or clear local paper notes |

Use `feynman alpha ...` rather than a global `alpha` binary so the bundled client runs. See [AlphaXiv](/docs/tools/alphaxiv).

## Package management

| Command | Description |
| --- | --- |
| `feynman packages list` | Show core packages and optional package presets |
| `feynman packages install <preset>` | Install an optional package preset |
| `feynman packages remove <preset>` | Remove an installed optional package preset |
| `feynman update [package]` | Update optional Pi packages you installed, or one of them; core packages update with Feynman |

See [Package Stack](/docs/reference/package-stack) for the core packages and optional presets.

## Web search

| Command | Description |
| --- | --- |
| `feynman search status` | Show Pi web-access status and config path |
| `feynman search set <provider> [api-key]` | Set the web search provider (any pi-web-access provider; run with no provider to list them) and optionally save its API key |
| `feynman search clear` | Reset the web search provider to `auto` while keeping API keys |

See [Web Search](/docs/tools/web-search).

## REPL hotkeys

Inside the interactive REPL, use `/hotkeys` to show the live keyboard map. The default reasoning controls are:

| Hotkey | Action |
| --- | --- |
| `Shift+Tab` | Cycle thinking/reasoning level |
| `Ctrl+T` | Collapse or expand thinking blocks |

## Workflow commands

Every workflow prompt can also be run directly from the CLI:

```bash
feynman deepresearch "topic"
feynman lit "topic-or-lab"
feynman review artifact.md
feynman audit 2401.12345
feynman replicate "claim"
feynman recipe "fine-tune a small model for math reasoning"
feynman compare "topic"
feynman draft "topic"
feynman autoresearch "idea"
feynman summarize paper.pdf
feynman log
```

These are equivalent to launching the REPL and typing the corresponding slash command.

## Flags

| Flag | Description |
| --- | --- |
| `--prompt "<text>"`, `-p` | Run one prompt and exit (one-shot mode) |
| `--model <model>` | Force an approved research model for this session: `provider/model`, `provider:model`, a bare ID or short name such as `sonnet`, optionally with a thinking suffix such as `:high` |
| `--service-tier <tier>` | Override the request service tier for this run |
| `--thinking <level>` | Set thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
| `--cwd <path>` | Set the working directory for tools |
| `--session-dir <path>` | Set the session storage directory |
| `--new-session` | Start a new persisted session |
| `--tui-mode <fullscreen\|regular>` | Run the terminal UI fullscreen (Pi 1.0's default) or in the terminal's normal scrollback; set `tuiMode` in `~/.feynman/agent/settings.json` to keep a choice |
| `--continue`, `-c` | Continue the most recent session (the default for an interactive launch) |
| `--resume`, `-r` | Pick a previous session to resume |
| `--session <path\|id>` | Open a specific session |
| `--fork <path\|id>` | Fork a session into a new one |
| `--no-session` | Use an in-memory session that is not persisted |
| `--no-themes` | Skip theme loading (passed by ACP adapters such as pi-acp) |
| `--export <session.jsonl> [out.html]` | Export a session file to HTML and exit |
| `--alpha-login` | Sign in to alphaXiv and exit |
| `--alpha-logout` | Clear alphaXiv auth and exit |
| `--alpha-status` | Show alphaXiv auth status and exit |
| `--doctor` | Alias for `feynman doctor` |
| `--setup-preview` | Alias for `feynman setup preview` |

When stdin is not a terminal, `--prompt` and workflow commands do not read it, so an idle pipe from a parent process cannot stall the run. Pipe text without `--prompt` to send it as the prompt, for example `git diff | feynman --no-session`.

Use the standard `--` delimiter before an interactive prompt that starts with
a dash, so Pi treats it as research text rather than another option:

```bash
feynman -- "- summarize the strongest evidence first"
```

For one-shot mode, attach a dash-leading value directly to `--prompt`:

```bash
feynman --prompt="- summarize the strongest evidence first"
```

---

### Website Src Content Docs Reference Package Stack (`website/src/content/docs/reference/package-stack.md`)

---
title: Package Stack
description: Core and optional Pi packages bundled with Feynman.
section: Reference
order: 3
---

Feynman is built on stock Pi and uses curated Pi packages for its capabilities. Feynman itself is a Pi package: its `package.json` `pi` manifest declares its extension, prompts, skills, theme, and subagent definitions. Feynman launches Pi with `PI_CODING_AGENT_DIR=~/.feynman/agent` and lists itself and its core packages in `~/.feynman/agent/settings.json` as local-path packages, so subagents load the same tools as the main session.

See Pi's upstream docs for [packages](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md), [extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md), and [skills](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md).

## Core packages

These are npm dependencies of Feynman, installed with it and loaded unmodified from its install directory.

| Package | Purpose |
| --- | --- |
| `pi-subagents` | The `subagent` tool, `/subagents`, and `/run`; powers delegated and parallel research runs |
| `pi-web-access` | `web_search`, `source_check`, `fetch_content`, and `get_search_content` for web search and page, PDF, and GitHub retrieval |
| `pi-docparser` | `document_parse`, `document_search`, and `document_screenshot` for local PDFs, Office documents, spreadsheets, and images |
| `pi-btw` | `/btw` side conversations while the main research agent is busy |
| `@companion-ai/alpha-hub` | alphaXiv client library behind Feynman's `alpha_*` tools and `feynman alpha` |

They update when you upgrade Feynman. You do not need to install them individually.

## Bundled research extension

Feynman's own extension registers these tools and commands:

| Group | Contents |
| --- | --- |
| AlphaXiv tools | `alpha_search`, `alpha_get_paper`, `alpha_ask_paper`, `alpha_read_code`, `alpha_annotate_paper`, `alpha_list_annotations` |
| Science database search | `feynman_science_database_search` over Semantic Scholar, OpenAlex, arXiv IDs, PubMed, Europe PMC, bioRxiv/medRxiv, and Crossref |
| Hugging Face Hub tools | `hf_dataset_info`, `hf_repo_files`, `hf_repo_read_file` |
| Commands | `/help`, `/init`, `/outputs`, `/tools`, `/service-tier` |

## Optional packages

Install on demand with `feynman packages install <preset>`.

| Package | Preset | Purpose |
| --- | --- | --- |
| `@samfp/pi-memory` | `memory` | Preference and correction memory across sessions |
| `@luxusai/pi-hindsight` | `hindsight` | Hindsight-backed long-term memory. Requires a Hindsight server or Hindsight Cloud account |

To search past Feynman sessions without a package, search the session files directly:

```bash
rg -n "protein folding" ~/.feynman/sessions
```

## Installing and managing packages

List core packages and optional presets:

```bash
feynman packages list
```

Install a specific optional preset:

```bash
feynman packages install memory
```

## Updating packages

Update the optional packages you installed, through Pi's own `pi update --extensions`:

```bash
feynman update
```

Update one package, by preset name or Pi package source:

```bash
feynman update memory
```

Core packages are not touched by `feynman update` because they ship with Feynman; to update them, upgrade Feynman itself (rerun the installer from the [Installation guide](/docs/getting-started/installation), or `npm install @companion-ai/feynman@latest`).

## Runtime versions

Feynman 0.5.57 runs Pi 1.4.0 with pi-subagents 0.81.0, pi-web-access 0.44.0, pi-docparser 4.0.0, pi-btw 0.8.0, and Alpha Hub 0.1.7 as ordinary npm dependencies, and does not modify any of them on disk. Every release is checked by booting the installed CLI in Pi RPC mode on Linux, macOS, and Windows.

---

### Website Src Content Docs Reference Releases (`website/src/content/docs/reference/releases.md`)

---
title: Release Notes
description: User-facing changelog for Feynman releases.
section: Reference
order: 4
---

This page summarizes what changed in recent Feynman releases. GitHub releases use the same version-specific notes from the repository `RELEASES.md` file.

## Unreleased

## v0.5.57 - 2026-10-24

- **Security updates from advisories published Oct 23.**
  - `undici` 8.12.3, now a direct dependency, so a fresh install no longer gives every package the pinned 8.10.2 below ([GHSA-xjj6-f33q-929c](https://github.com/advisories/GHSA-xjj6-f33q-929c), [GHSA-4qv8-2p9j-2685](https://github.com/advisories/GHSA-4qv8-2p9j-2685), [GHSA-f72v-6w45-q472](https://github.com/advisories/GHSA-f72v-6w45-q472)).
  - `body-parser` 2.4.0, `fast-uri` 3.1.9 and `zod` 4.6.7, through Alpha Hub's MCP SDK.
  - The website's build tools (vite 8.3.5, sharp 0.35.5, hono 4.13.13 and others) are patched too; its full `npm audit` is clean.
- Pi 1.4.0 and pi-subagents 0.81.0 still pin `undici` 8.10.2 for their own HTTP clients. Feynman can't change those copies; they'll move when Pi ([pi#11208](https://github.com/earendil-works/pi/issues/11208)) and pi-subagents ([#3022](https://github.com/nicobailon/pi-subagents/issues/3022)) release patched versions.

## v0.5.56 - 2026-10-23

- **pi-subagents 0.81.0.**
  - A research subagent asked for structured output that forgets to return it gets one more turn to do so, instead of failing and losing its work.
  - The main session can tell subagent completion notices apart from text you typed.
  - In fullscreen, you can click a subagent in the inspector to select it and scroll its output with the mouse or trackpad.
  - Windows: Feynman starts faster, and no longer freezes for about 8 seconds at startup when the subagent temp folder has broken permissions.

## v0.5.55 - 2026-10-22

- **Clearer hints for two more OpenAI errors.**
  - A project without access to a model (`403 ... does not have access to model`) now says the account can't use that model, instead of saying your credentials were rejected.
  - "Request too large ... tokens per min" now says the request is bigger than the account's per-minute token limit, so retrying won't help.

## v0.5.54 - 2026-10-22

- **Two more model errors explain themselves.** When a run ends on an error, Feynman names the cause:
  - A `404 Not Found` from the provider says the model id or endpoint doesn't exist, and to check the model with `/model` and the `baseUrl` in `models.json`.
  - "The model refused to complete the request" says the model declined, and to rephrase or pick another model.
- `ip-address` 10.7.4 (through Alpha Hub's MCP SDK) fixes [GHSA-rxp7-6hxx-x8q5](https://github.com/advisories/GHSA-rxp7-6hxx-x8q5), a slow parse of long IPv6 zone identifiers.

## v0.5.53 - 2026-10-22

- **Pi 1.4.0.**
  - Long research sessions no longer break after a response is cut off at the output limit; before, every later request in that session was rejected.
  - Compaction no longer fails with "generation hit the token cap" when the model reasons at length while summarizing a long session.
  - Parallel research subagents that run in-process wait for a free codemode worker instead of failing when two are already busy (`PI_CODEMODE_MAX_WORKERS` raises the limit).
  - The terminal is restored when Feynman exits without its normal teardown, instead of flooding the shell prompt with escape sequences.
  - More gateway and proxy failures are retried automatically, including "stream disconnected before completion".
  - A tool result that is only whitespace no longer makes OpenAI and Google requests fail with a 400.
  - `mcp.json` files saved with a UTF-8 BOM (Windows) parse again.

## v0.5.52 - 2026-10-21

- **pi-subagents 0.80.0.**
  - A background research subagent that finishes while the main session is busy keeps its completion notice across a restart; the next session that opens it shows the result.
  - Waking the main session after a subagent finishes no longer adds an "Inspect subagent updates above" line to the transcript.
  - Each child of a `parallel` call can set its own `cwd` and `model`.
  - A steer that times out on a busy subagent no longer blocks every later steer on that run.
  - Subagents no longer inherit your `APPEND_SYSTEM.md`.
  - Workflows started from providers with very long tool-call ids (LiteLLM with Gemini) no longer fail at launch.
  - Windows: Feynman no longer exits at startup when security software blocks `git` (`spawn EPERM`).
- **pi-web-access 0.44.0.**
  - `fetch_content` returns short, complete static pages instead of reporting them as incomplete.
  - A default search provider list now falls back to `searchRouting` when every provider in it fails.
  - Linkup is a new search provider: `feynman search set linkup <key>`. Each search uses Linkup credits, so `auto` never picks it.
  - Most search providers can be routed through your own gateway with a `<provider>BaseUrl` setting; API keys are dropped when a provider redirects to another site.
- The native installer bundle ships hono 4.13.13, for GHSA-5r4p-p66f-jhc7.

## v0.5.51 - 2026-10-19

- **A damaged `auth.json` says so.** When `~/.feynman/agent/auth.json` isn't valid JSON, for example after a hand edit, every command used to print only `Expected property name or '}' in JSON`. Feynman now names the file and says to fix it, or move it aside and sign in again with `feynman setup`.
- `feynman --update` points to `feynman update`, and `feynman model setup` points to `feynman model login`.

## v0.5.50 - 2026-10-18

- **pi-subagents 0.79.1.**
  - Sessions that have not delegated yet no longer send the `bg_wait` and `subagent_supervisor` tool definitions with every request, about 1,500 characters saved per request.
  - When a workflow's main process dies, research subagents that had already finished keep their results instead of being marked failed.
  - Workflow lanes in the widget and `status` show each subagent's model.
  - Read-only installs no longer log a "permission denied" error about the upgrade notice on every start.

## v0.5.49 - 2026-10-17

- **pi-subagents 0.79.0.**
  - Forked research subagents reuse the parent's prompt cache, and `/subagent-cost` reports no longer ride along in every later request, so parallel runs cost fewer tokens.
  - When a provider stops a subagent with an error such as a content-filter refusal, the error now includes the provider's reply, so a refusal can be told apart from an outage.
  - `subagent` stays available after an update or `/reload` mid-session.
- **pi-web-access 0.42.0.** DeepSeek's Search API is available as a search provider: `feynman search set deepseek <key>`. It bills each search, so `auto` never picks it.
- `.env.example` lists `OPENALEX_API_KEY`, which raises the OpenAlex rate limit for long literature runs (thanks @fanfyh).

## v0.5.48 - 2026-10-16

- **Pi 1.3.0.**
  - Tool calls whose arguments contain a backslash sequence like `\usepackage` no longer lose fields, which mattered for LaTeX in drafts and papers.
  - Gateway errors such as "Unable to forward upstream stream" and "service is temporarily unavailable" are retried instead of ending the turn.
  - Anthropic requests no longer fail with a 400 when a failed tool result contains images.
  - A tool call with malformed arguments now fails instead of running with partial ones.

## v0.5.47 - 2026-10-15

- **pi-web-access 0.41.0.** Sites that turn away AI fetchers can be read by setting your own User-Agent: add `"fetchContent": { "userAgent": "..." }` to `~/.feynman/agent/web-search.json`. A SearXNG instance on your own machine now works without opening every local service to page fetches.

## v0.5.46 - 2026-10-13

- **Recent arXiv papers resolve by DOI.** OpenAlex adds new arXiv preprints days late, so looking up an arXiv DOI (`10.48550/arXiv.<id>`) it doesn't have yet failed. It is now looked up on arXiv itself, with a note.
- When a topic sent to the arXiv source is written in arXiv's own query syntax (`search_query=all:...`, `submittedDate:[...]`), only the search words are passed on to OpenAlex.

## v0.5.45 - 2026-10-13

- **Paper lookups recover instead of failing.**
  - A topic sent to the arXiv source, which only looks papers up by ID, now gets OpenAlex semantic search results with a note saying so, instead of an error the model had to recover from.
  - When arXiv times out or is overloaded, arXiv ID lookups come from Semantic Scholar, with a note saying so.

## v0.5.44 - 2026-10-13

- **`feynman search set` works with every search provider pi-web-access supports.** It accepted only `auto`, `exa`, `perplexity` and `gemini`; it now takes all 39, including Brave, Tavily, Kagi, Serper, You.com, SearXNG and DuckDuckGo, and saves each key where pi-web-access reads it. `feynman search status` and `feynman doctor` name the provider you chose and list every saved key, and no longer describe an outdated automatic search order.
- **pi-web-access 0.40.0.** Asking about a YouTube or local video works again when a thumbnail comes back with the transcript, excerpts no longer cut an emoji in half, and a new opt-in setting (`fetchContent.redirects: "same-origin"`) refuses redirects to another site.

## v0.5.43 - 2026-10-13

- **Feynman reads and writes Pi's configuration only through Pi.** Settings now go through Pi's settings manager, which locks the file and changes only the keys Feynman sets, so a change Pi or another Feynman window makes at the same moment is no longer overwritten. Model checks, local-model detection and `feynman doctor` read your models through Pi, so comments in `models.json`, a `baseUrl` set on one model, and a key saved with `feynman model login` count the same way they do when Feynman runs.
- `feynman doctor` no longer warns about a custom provider whose key you saved with `feynman model login` rather than writing it into `models.json`.

## v0.5.42 - 2026-10-13

- **Pi 1.2.0 and pi-subagents 0.78.0.**
  - With an OpenRouter key, `/model` lists only the models that key can use, with their real context sizes and prices.
  - "The upstream provider returned an error" is retried instead of ending the turn, and Anthropic requests rejected for too many strict tools are retried once.
  - `feynman -p` warns and exits 1 when the answer was cut off at the model's output limit.
  - On Windows, reading or writing saved logins no longer fails with `EPERM` while an old lock is cleaned up.
  - Pressing `Esc` keeps a research run stopped; a subagent finishing a moment later no longer restarts it.
  - Reports are no longer overwritten when a subagent run is resumed, and a timed-out subagent's partial output reaches the lead agent.
  - The `workflowScript contains dynamic child launches` warning no longer prints on every parallel run.
- **`feynman model login` offers every provider Pi supports with an API key.** That is 41 providers instead of Feynman's own list of 16, adding DeepSeek, Fireworks, Together, NVIDIA, Google Vertex, Cloudflare, Qwen and others. Pi now asks for what each provider needs, so Cloudflare's extra fields and Bedrock's profile or bearer-token options work. Pressing Enter on an empty key no longer saves an empty credential.
- **Turning off Feynman's telemetry also turns off Pi's.** `FEYNMAN_TELEMETRY=off` (or `DO_NOT_TRACK=1`) now sets Pi's own `PI_TELEMETRY=0` for its install reporting.
- Feynman now honors Pi's own `sessionDir` setting and `PI_CODING_AGENT_SESSION_DIR` when you don't pass `--session-dir`.
- `feynman model set` and the default-model check use Pi's settings API, so they match what Pi launches with (including trusted project settings).

## v0.5.41 - 2026-10-12

- **A fresh `npm install` works again.** Pi 1.2.0, released today, made new npm installs of Feynman 0.5.40 fail on every command except `-v` (`does not provide an export named 'MCP_TYPESCRIPT_PREAMBLE'`). Pi 1.1.0 asks for its own sub-packages with open version ranges, so npm pulled Pi 1.2.0's copies. Feynman now pins those sub-packages to the Pi version it ships. The curl and PowerShell installers were not affected.
- **An expired sign-in no longer looks like no model.** Feynman treated a ChatGPT, Claude or Copilot sign-in whose short-lived access token had expired as if no model were set up. `feynman` reopened the setup menu, and since 0.5.36 `feynman -p` refused to run. Pi renews the token on the next request, so Feynman now leaves that to Pi and asks you to sign in again only when renewal really fails.
- **`--model` accepts the names Pi accepts.** Bare model IDs (`claude-opus-5-5`), short names (`sonnet`) and a thinking suffix (`anthropic/claude-opus-5-5:high`) now work, preferring a provider you are signed in to; `provider/model` and `provider:model` still work. Pro-class models stay blocked.
- **After you sign in, the model list matches your account.** `feynman model login` refreshes that provider's model list, so an OpenRouter key gets the models it can actually use before Feynman picks a default.
- A provider error hint now appears once the run has stopped, not in the middle of an automatic retry.
- Launching Feynman no longer erases your terminal's scrollback.
- The llama.cpp provider is recognized as a local model.
- **Preview and PDF export find more browsers.** Chromium, Edge and Brave on Linux, Edge under `Program Files (x86)` and Brave in your user folder on Windows, and apps in `~/Applications` on macOS. Thanks to @A-ryanVAT-S (#343).

## v0.5.40 - 2026-10-12

- **alphaXiv sign-in messages name the right command.** When you weren't signed in, `feynman alpha search`, `get` and the paper tools said to run `alpha login`, a command that isn't installed with Feynman. They now say `feynman alpha login`. (Alpha Hub 0.1.7.)
- Security: Alpha Hub now requires `@modelcontextprotocol/sdk` 1.32.1 or later, so a fresh install can't resolve a version affected by GHSA-6qxp-vccf-f47h.

## v0.5.39 - 2026-10-12

- **Web search and fetching are steadier (pi-web-access 0.39.0).** Search summaries now read each source's snippet, so providers that return only links still produce a summary. `auto` search moves on when a provider returns nothing, a stalled Perplexity request gives up after 30 seconds, and a DuckDuckGo bot check is reported as a block instead of an empty search. `fetch_content` answers end with the `get_search_content` call that reads the stored page, answer mode with several URLs shows every page's answer, and PDFs can go to a document parser you run yourself (`pdf.provider: "endpoint"` in `~/.feynman/agent/web-search.json`).

## v0.5.38 - 2026-10-12

- **`/deepresearch` no longer waits for a "yes" after its plan.** About 1 in 5 people who started it never answered the approval question, so the research never ran. It now writes the plan, summarizes it, and continues, as `/lit` does. To check the plan first, say so in the request, for example `/deepresearch <topic>, show me the plan first`.
- **A failed model call says what went wrong.** When the provider rejects a request, Feynman now names the cause and the fix under the error: a model your account can't use (pick another with `/model`), no credits, a rate limit or used-up quota, rejected credentials (`feynman model login <provider>`), or a temporary outage. Most failed `/lit` and `/audit` runs ended on one of these. Feynman bugs go to github.com/Companion-Inc/feynman/issues; Pi's `/bug` reports to Pi's developers.
- Research runs on macOS and Linux no longer fail on `python: command not found`; Feynman tells the model to run `python3`.

## v0.5.37 - 2026-10-12

- **A sign-in that came back without a code says what to do.** When the browser returned to `feynman model login` or `feynman setup` without an authorization code (seen mostly on Windows), Feynman printed only "Missing authorization code". It now gives the same advice as for `invalid_grant`: sign out of the provider's site or use a private window, then retry, and for ChatGPT it suggests `feynman model login openai-codex`.

## v0.5.36 - 2026-10-12

- **A new user gets to a working model instead of a dead end.** Launching `feynman` with no model opens a menu to set one up.
  - Typing a question there moved the selection onto Cancel: the menu treated `h`, `j`, `k` and `l` as arrow keys. Only the arrow keys move it now.
  - Cancel used to go on to optional packages, an alphaXiv sign-in that defaulted to Yes, and pandoc, then said "Feynman is ready" with no model. It now exits and says how to add a model, and that your question was not sent.
  - The first launch asks only for the model. Packages, alphaXiv and pandoc stay in `feynman setup`, where alphaXiv now defaults to No.
  - Esc in a provider list goes back to the previous menu instead of ending setup.
  - `feynman -p "…"` with no model now says how to add one, instead of pointing at Pi's `/login` and files inside `node_modules`.
- `feynman help` drops the duplicate "Getting Started" list and calls the flag section "Options".

## v0.5.35 - 2026-10-11

- **PubMed group authors keep their affiliations.** Consortium and study-group authors came back with no affiliations; they now keep them, as individual authors do. Thanks to @KennyMcSimpson (#335).
- **pi-subagents 0.77.0.** Subagent tools cost the lead agent far fewer tokens per request (the `subagent` tool's definition shrank from about 18,700 to 3,300 characters), and long subagent reports arrive as a preview plus the file path instead of the full text. Updating Feynman while a session is running no longer breaks every subagent launch in that session. A wrong agent or model name now comes back with suggestions.
- **pi-btw 0.8.0.** The `/btw` side-chat composer completes slash commands, and side threads no longer fail with Anthropic's "references unknown tool" error.
- `feynman -v` prints the version, and `--json`, `--work-dir` and `--path` now point to `--mode json` and `--cwd <dir>`.

## v0.5.34 - 2026-10-09

- **OpenAlex lookups that miss now say why.** Looking up a name or title where OpenAlex expects an ID (for example `openalex_get_work:Attention is all you need` or `author: Geoffrey Hinton`), or an ID that does not exist, returned OpenAlex's raw HTML "404 Not Found" page. The error now says no such work, author or source exists and names the search command to use instead, so the agent recovers on its next call.

## v0.5.33 - 2026-10-09

- **pi-web-access 0.38.0.**
  - Web searches with no API key (Parallel) no longer fail with "free-tier rate limit".
  - On a ChatGPT subscription, OpenAI web search now uses the newer, much cheaper `gpt-6-luna`, so searches take far less of your usage.
  - `fetch_content` answer mode works with models whose provider signs in without an API key.
  - Requests through a proxy keep their method, headers and body.
  - Adds Ceramic, a paid search provider used only when you select it.
- Security: pi-web-access now uses `@modelcontextprotocol/sdk` 1.32.1, so GHSA-6qxp-vccf-f47h no longer appears in `npm audit` for a Feynman install.

## v0.5.32 - 2026-10-09

- **A rejected sign-in now says what to do.** When `feynman model login` or `feynman setup` ended with `invalid_grant`, usually after Sign in with ChatGPT, Feynman printed only the provider's error. It now explains that a stale browser session usually causes it: sign out of the provider's site or use a private window, then run `feynman model login <provider>` again. For ChatGPT it also suggests `feynman model login openai-codex`.

## v0.5.31 - 2026-10-09

- **Feynman starts again if you once installed the old `session-search` package.** Its entry stayed in `~/.feynman/agent/settings.json` after the preset was removed. On Node 24 that made every launch fail installing it, or crash Pi through its SQLite module or its extension. Feynman now drops the entry on launch; Feynman's sessions are searchable with `grep` or `rg` over `~/.feynman/sessions`.

## v0.5.30 - 2026-10-07

- **Pi 1.1.0.** Claude browser login no longer fails with "localhost refused to connect" when port 53692 is reserved or in use (common with Hyper-V/WSL on Windows); it falls back to a free port. "Servers are busy" provider errors and Mistral stream errors are retried instead of ending the turn, fewer requests fail on context limits, and session costs count long prompts correctly. Adds Claude Haiku 5.5; Feynman's default for Anthropic stays Claude Opus.

## v0.5.29 - 2026-10-07

- **PubMed titles and abstracts keep their italic terms.** Text inside inline tags such as `<i>BRCA1</i>` was dropped, so a title read "patient with germline mutation" instead of "germline BRCA1 mutation", and gene names went missing from abstracts. Thanks to @KennyMcSimpson (#328).
- **PubMed authors keep all their affiliations.** An author listed with two or more affiliations came back with none. Thanks to @KennyMcSimpson (#327).
- Security: GHSA-6qxp-vccf-f47h (MCP SDK OAuth client). Feynman's own copies of `@modelcontextprotocol/sdk` move to 1.32.1. pi-web-access still pins 1.27.1 for its separate `npx pi-web-access` MCP server, which Feynman does not run and which does not use the affected OAuth client; it is updated in nicobailon/pi-web-access#522.

## v0.5.28 - 2026-10-07

- **Pi 1.0.4, pi-subagents 0.76.1, pi-web-access 0.37.0.**
  - Pi: syntax highlighting keeps its colors across multiline strings and comments, MCP sign-in works on servers using OpenID Connect registration, and stalled Bedrock streams are retried.
  - pi-subagents: when a subagent's result wakes the main session, that turn keeps its normal system prompt (subagent list, MCP servers, other extensions) and the provider's prompt cache. A per-tool timeout now names the tool instead of a run deadline that never fired.
  - pi-web-access: a `web_search` or `fetch_content` call where nothing succeeded is now reported as a tool error, so the model knows to try something else; Perplexity results include page snippets and cost less.

## v0.5.27 - 2026-10-06

- **Pi 1.0.3.** Sign in with ChatGPT no longer fails with `refresh_token_invalidated` after a request is cancelled during a token refresh, and closing the terminal no longer reports a `read EIO` / `setRawMode EIO` crash. In fullscreen, `Home`/`End` now move within the input line; jump to the top or bottom of the transcript with `Ctrl+Home`/`Ctrl+End`.
- **Azure OpenAI is now `azure`.** Pi renamed the provider from `azure-openai-responses`, and `feynman model login` now offers the new name. If you set up Azure before, run `feynman model login azure` again and rename the provider in `~/.feynman/agent/models.json` and `settings.json`; `AZURE_OPENAI_*` variables are unchanged.

## v0.5.26 - 2026-10-05

- **GitHub Copilot users get a research model by default.** Copilot names Claude models with dots (`claude-opus-5.5`), which Feynman did not recognize, so a new Copilot login fell back to alphabetical order and set `claude-haiku-4.5` as the default; Copilot then rejected it with "The requested model is not supported" for several users. Feynman now picks Copilot's newest Claude Opus, then Sonnet, then GPT. If `feynman status` shows `github-copilot/claude-haiku-4.5` and you did not choose it, run `feynman model set` to pick another.
- `alpha_ask_paper` answers with the arXiv metadata and abstract, marked as a fallback, when alphaXiv does not answer (for example after the login expires), like `alpha_search` and `alpha_get_paper` already did.
- `-p` is short for `--prompt`, as in Pi. `--setup`, `--list-models`, `--new`, `feynman setup model`, and `feynman model <provider/model>` now say which command was meant.
- pi-web-access 0.36.0: `web_search` accepts lists that a model sent as a JSON string (nicobailon/pi-web-access#491), `fetch_content` asks docs sites for markdown first, Brave prepaid keys keep working, and a `fetch_content` call whose only URL failed is reported as an error.

## v0.5.25 - 2026-10-05

- **Pi 1.0.2 and pi-subagents 0.76.0.** Pi now uses the patched brace-expansion 5.0.12 (GHSA-q2hr-2g5m-vwhr, GHSA-qhr7-859c-m2p7, GHSA-6j4f-fj2g-mc7p), so Feynman's npm audit has no exceptions left, and an npm install pulls about 120 fewer packages. Pi also retries "model at capacity" errors instead of ending the turn, and Sign in with ChatGPT reports a busy callback port instead of "OAuth state mismatch". pi-subagents frees async slots held by abandoned workflows.
- **A timed-out paper search no longer ends a research step.** A Semantic Scholar or OpenAlex topic search that hits the 25 s timeout is answered from the other index, and other sources say which one did not respond instead of "This operation was aborted".
- **arXiv batch versions.** Looking up a bare arXiv ID alongside an older version now returns the latest version for the bare ID regardless of feed order. An unavailable explicit version is reported in `not_found` instead of resolving to a different version. Thanks to @Kunyanli230 (#322).

## v0.5.24 - 2026-10-03

- **Pi 1.0.** Feynman now runs on Pi 1.0.0, with pi-subagents 0.75.0 (background subagents start on Pi 1.0) and pi-btw 0.7.1 (allows Pi 1.x). The terminal UI is fullscreen by default and keeps its own scrollback; run `feynman --tui-mode regular`, or set `"tuiMode": "regular"` in `~/.feynman/agent/settings.json`, to use the terminal's normal scrollback. Launch warnings show inside the fullscreen UI. Pi 1.0 also adds MCP OAuth hardening, a copy-code Anthropic login for headless machines, and lower codemode token use.

## v0.5.23 - 2026-10-02

- **arXiv and PubMed rate limits.** arXiv asks for one request every three seconds, and parallel lookups got `429`; arXiv requests now run at that pace and a 429 is retried once. A PubMed `429`, which a subagent in another process or a shared IP can still trigger, is retried once after a pause.
- Running several subagents at once from any workflow no longer fails with "workflow: true requires exactly one ```
/* Detailed source-code truncated for AI context efficiency. */
```` ```js workflow ```` block, failed in testing when Claude put the block in its hidden reasoning, while a script file worked with every model, and the file stays next to the plan as a record of the run. Subagent children also follow the project's trust setting, and `/reload` no longer stops running background workflows.
- Security: Pi 0.99.2 still locks brace-expansion 5.0.9; the exception for it stays until Pi ships 5.0.12.

## v0.5.18 - 2026-09-30

- **A rate-limited paper index no longer ends a research step.** When Semantic Scholar is rate-limited or down, a search is answered from OpenAlex, and an OpenAlex topic search that hits OpenAlex's anonymous rate limit or an outage is answered from Semantic Scholar. The result says first which index answered and why. Lookups by OpenAlex ID, DOI, author, venue, or citation still report the error, since the other index has no equivalent.
- **alphaXiv tools answer when alphaXiv cannot.** If your alphaXiv login expired or alphaXiv does not respond, `alpha_search` returns OpenAlex semantic search results and `alpha_get_paper` returns the arXiv metadata and abstract for an arXiv ID, each marked as a fallback. Run `feynman alpha login` to get alphaXiv's reports back.
- pi-web-access 0.35.0: OpenAI web search works when you signed in with ChatGPT (`feynman model login openai`), and Brave search keeps to its rate limits. The researcher is told to pass a search provider as a plain string, since some models sent `provider: "[\"parallel-mcp\"]"`, which `web_search` rejects; nicobailon/pi-web-access#491 makes `web_search` accept that form too.

## v0.5.17 - 2026-09-30

- **`feynman model login openai` works again.** Since Pi 0.99, Sign in with ChatGPT needs a stable ID for the installation, which Feynman did not pass, so the login failed at once with "requires a device ID (UUID)". Feynman now shares the `deviceId` Pi's own `/login` keeps in `~/.feynman/agent/settings.json`.
- **Windows finds per-user Git Bash.** Pi looks for Git Bash only under Program Files and on PATH, but a per-user Git for Windows install puts only `Git\cmd` on PATH, so shell commands failed with "No bash shell found" (about one in five Windows installs that run tools). Feynman now finds that Git Bash and gives it to Pi. When there is no Bash at all, Feynman says so before the session starts, and `feynman doctor` reports the `bash` it found.
- Pressing Enter at the "paste the authorization code / redirect URL" login prompt no longer ends the login with "Missing authorization code"; Feynman asks again, and finishing in the browser still works.
- API keys are now masked as you paste them during setup, and a key with non-ASCII characters (for example typed with a non-Latin keyboard layout) is rejected with an explanation instead of failing every request with "Cannot convert argument to a ByteString".
- A rejected `SEMANTIC_SCHOLAR_API_KEY` now says so instead of `request failed: 403 Forbidden`.

## v0.5.16 - 2026-09-30

- **Subagent research files land in the workspace.** When a workflow gave a subagent a relative output path such as `outputs/.drafts/<slug>-research-web.md`, pi-subagents saved it under `~/.feynman/sessions/subagent-artifacts/outputs/<run>/` instead, so the lead agent could not find the research notes, citations, or verification it asked for (about one in seven installs running research workflows hit this in the last week). Relative subagent outputs now resolve against the workspace, the researcher, reviewer, verifier, and writer no longer default to generic file names such as `research.md`, and `/deepresearch` and `/lit` name every subagent file under `outputs/.drafts/`. If you set `singleRunOutputBaseDir` in `~/.feynman/agent/extensions/subagent/config.json`, Feynman keeps your value.
- `feynman packages remove <preset>` (also `rm` and `uninstall`) removes an optional package such as `memory`.
- On Windows, Feynman no longer fails to start when another Feynman start is copying `keybindings.json` (`EBUSY: resource busy or locked`).
- pi-web-access 0.34.0: `fetch_content` falls back to your other fetch providers on Cloudflare "Just a moment..." pages, web tools start available on models such as DeepSeek without costing a prompt-cache miss, and its undici moves to 8.11.2.
- Security: three brace-expansion advisories published on 2026-09-29 affect the 5.0.9 that Pi 0.99.1's shrinkwrap locks, which Feynman cannot override. Pi uses it only for package filters and model patterns from your own settings and flags; the next Pi release that ships 5.0.12 replaces it. pi-subagents has still not released its undici fix.

## v0.5.15 - 2026-09-29

- **Pi 0.99.1, pinned.** Feynman accepted any Pi version, so npm installs picked up Pi 0.99.1 the day it was released, untested, and Pi 0.99 warns on every launch about how Feynman declared it. Feynman now runs on Pi 0.99.1, which adds MCP server support (`/mcp`), declared the way Pi asks, and pinned so new Pi releases arrive only after they pass Feynman's checks. If npm has `legacy-peer-deps` on, it skips Pi; `feynman` now says to reinstall with `--legacy-peer-deps=false` instead of failing on a missing package.
- **npm installs use a patched undici.** pi-subagents pins undici 8.10.0, which ten advisories published on 2026-09-29 affect (plus GHSA-3wwx-pv8p-q78v), and npm hoisted that copy for every package in an npm install. Feynman now depends on a patched undici directly, so only pi-subagents keeps 8.10.0 until it releases its bump (nicobailon/pi-subagents#2548); the standalone installers were already patched. Correction to the 0.5.14 notes: pi-subagents' background runner installs its undici as the process-wide fetch and WebSocket, so the advisories do apply to background subagent runs.
- **`feynman model set` explains a model it cannot use.** "Model not available in Pi auth storage" gave no reason. It now says which applies: the provider has no credentials (with the `feynman model login` command to run), a local provider in `models.json` has no `apiKey` (Pi hides providers without one; a placeholder such as `"local"` is enough), or the ID is unknown (with close matches, for example `gpt-5.6` suggests `openai/gpt-5.6-terra`).
- **Parallel OpenAlex semantic searches no longer fail.** OpenAlex allows one semantic search per second, and parallel searches got `429 Too Many Requests`: in a live test of six at once, five failed. They now run one after another at that pace, and a 429 that asks for a short wait is retried once. Six parallel searches now all succeed.
- `feynman model set` with no model opens a picker of the available models instead of failing. `feynman model help` lists the model commands, an unknown model subcommand points to it, and `-h` works like `--help`.

## v0.5.14 - 2026-09-28

- **The Windows installer no longer fails on slow networks (#309).** When usage telemetry could not reach PostHog quickly, the PostHog library printed a timeout to stderr, and Windows PowerShell treats stderr from the installer's `feynman --help` check as a failure. Each telemetry send now has a 1.5 s budget and ends quietly, so no command waits on telemetry (on a stalled network `feynman --help` took 11 s and printed two errors; it now takes about 2 s and prints nothing). The installers also run their checks with telemetry off and judge them by exit code.
- pi-subagents 0.73.1 (no longer discards the prompt cache when subagents turn on; caps very large workflow output) and pi-web-access 0.33.0 (resumed sessions keep their tools; no false Pi version warnings). undici is overridden to a patched version for GHSA-3wwx-pv8p-q78v in the standalone installers; npm installs get the fix when pi-subagents releases its bump (nicobailon/pi-subagents#2548); pi-subagents only uses undici's HTTP proxy agent, not the affected WebSocket client.

## v0.5.13 - 2026-09-28

- **OpenCode no longer recommends a retired Kimi model.** OpenCode Go and OpenCode Zen retired `kimi-k2.6` ("Use kimi-k2.7-code instead"), but Feynman still picked it as the default for new OpenCode users. It now recommends `kimi-k2.7-code`. If `feynman status` shows `kimi-k2.6`, switch with `feynman model set opencode-go/kimi-k2.7-code`. Three model preferences that no longer exist in the catalog were removed.
- A failed literature database request now names the service, for example `www.ebi.ac.uk request failed: 503`, instead of "Science database request failed".

## v0.5.12 - 2026-09-28

- Crossref pacing leaves a margin over the pool's limit and retries a rate-limited request once after the server's `Retry-After`. A stress test of three bursts of 10 parallel searches on the public pool now succeeds on all 30; 0.5.11 still lost about one in six to network jitter.

## v0.5.11 - 2026-09-27

- **Crossref lookups no longer fail in bursts.** Crossref's public pool allows one request at a time, one per second, and parallel DOI checks (the verifier cross-checks every citation) got `429 Too Many Requests` on most calls. Crossref requests now run one after another at the pool's pace. Set `CROSSREF_MAILTO` to your email for Crossref's faster polite pool; a 429 now says so instead of a generic "Science database request failed".
- Telemetry's "wrote output" flag no longer misses a report written in the first second of a run on filesystems that round file times (HFS+, FAT, ext3).

## v0.5.10 - 2026-09-27

- **Semantic Scholar understands the documented query syntax.** A `semantic:` prefix and `year_from=`/`year_to=` flags, which the model reuses from the OpenAlex examples, were sent to Semantic Scholar as search text and returned unrelated papers or nothing. They now become Semantic Scholar's own year filter.
- **The startup header lists only Feynman's workflows.** It also listed prompt commands that pi-subagents ships, such as `/parallel-review` and `/review-loop`.
- **Cleaner README and landing page** with a current screenshot, and a shorter configuration page.

## v0.5.9 - 2026-09-27

- **Subagents keep their search tools in the foreground.** A `researcher` or `verifier` launched in the foreground failed at once because foreground children never load the parent's extensions, so `web_search`, `fetch_content`, and `feynman_science_database_search` were missing. Feynman now points pi-subagents' `defaultSubagentOnlyExtensions` setting at its research tools and pi-web-access, so every child has them, in the foreground or background.
- **No alphaXiv account, no alphaXiv search tools.** Without an account, every `alpha_search`, `alpha_get_paper`, `alpha_ask_paper`, and `alpha_read_code` call failed, and research runs retried them. They are now registered only when you are signed in; otherwise papers come from Semantic Scholar, OpenAlex, and the other literature databases. Start a new session after `feynman alpha login`.
- The Windows install docs now say Feynman needs Bash from Git for Windows for shell commands.

## v0.5.8 - 2026-09-26

- `FEYNMAN_HOME=~` or `~/path` now means your home folder. Unexpanded `~` (common in `.env` files, Docker `ENV`, and Windows shells) created a literal `~` folder in the current directory.
- Starting two Feynman sessions at the same moment no longer crashes one of them with "Subagent config changed during settings normalization". The second start keeps the subagent config the first one wrote.

## v0.5.7 - 2026-09-26

- When Feynman runs as a package inside another Pi setup, an extension error no longer appears on every turn ("Cannot set properties of undefined (setting 'current_date')") if another extension or the host leaves the system-prompt sections unset (#298, thanks @Oscar-Williams in #300).

## v0.5.6 - 2026-09-26

### Failures report what went wrong

- Usage telemetry now carries readable error text instead of a hash: the error message and stack trace (also sent to PostHog error tracking), the last lines of Pi's error output when a run exits with an error, a failed tool's error text, and the provider's error message on a failed model call. Your home folder is shown as `~`. Paths inside your projects can appear in this text. Prompts, model output, paper content, and tool arguments are still never sent. Opt out with `FEYNMAN_TELEMETRY=off` as before.
- CI runs and the test suite no longer report telemetry, so usage numbers count real installs only.

### Fixes

- A dead network connection now fails in about 15 seconds with `Connection error.` instead of retrying silently for over five minutes. Feynman had set a 6-retry, 5-second backoff that also applied to connection errors; it now uses Pi's default, and the old value is removed from existing settings. Rate limits are still retried with the provider's `Retry-After`.
- `feynman setup` and `feynman model login` in a window Node cannot prompt in (Git Bash's default window, a script, or an AI coding agent) now explain how to proceed: `winpty`, PowerShell, or setting the provider's API key variable and running `feynman model set`.

## v0.5.5 - 2026-09-24

### Node.js 26

- Feynman now runs on Node.js 26, the current release. The upper version limit is gone: Feynman needs Node.js 22.22.0 or newer, like Pi itself. Tests run on Node 22, 24, and 26.
- The standalone installers bundle Node.js 24.21.0, the latest LTS release.

### alphaXiv

- When an alphaXiv call fails, the tool error now points the agent to `feynman_science_database_search` (arXiv or Semantic Scholar) or `fetch_content`, so a research run continues on another source instead of retrying a broken tool. A "not logged in" error names `feynman alpha login`.
- The alphaXiv docs explain signing in from a machine without a browser (SSH, Docker, WSL): open the printed URL anywhere and paste the final `127.0.0.1:9876/callback` URL back into the terminal.

### Other

- The setup docs explain the most common reason local models write no files: a small context window. They show how to raise Ollama's context and set `contextWindow` and `maxTokens` in `models.json`.
- feynman.is/privacy and feynman.is/telemetry go to the telemetry section, which lists what is collected and how to opt out.
- Updated dependencies: pi-btw 0.6.1, posthog-node 5.53, @clack/prompts 1.8.1, and the website toolchain (Astro 7.3, @astrojs/react 7). CI uses actions/checkout and actions/setup-node v7 and wrangler 4.139.

## v0.5.4 - 2026-09-24

### Use Feynman from ACP editors

- `feynman --mode rpc` now accepts `--no-themes`, the Pi flag the [pi-acp](https://github.com/svkozak/pi-acp) adapter passes, so Feynman runs in ACP editors such as Zed. Point pi-acp at Feynman with `PI_ACP_PI_COMMAND=feynman`; the setup guide has the Zed settings.

### Removed what did not work

- The optional `session-search` package preset is gone. It indexes `~/.pi/agent/sessions` and never saw Feynman's sessions in `~/.feynman/sessions`, and its `/search` collided with pi-web-access's. Search past sessions with `grep` or `rg` over `~/.feynman/sessions`; the session-search skill now shows how.
- `/preview` is no longer listed in `/help`: no bundled or optional package provides it. `feynman setup preview` still installs pandoc, and the preview docs show how to render artifacts to HTML or PDF.
- `/help` lists pi-web-access's real `/websearch` and `/curator` commands instead of `/web-results`, which pi-web-access 0.31 no longer registers.
- The autoresearch and alpha skills no longer mention tools and patches that do not exist.

### Docs match the code

- Every docs page, the landing page, and the README were checked against the CLI, prompts, agents, and package code. Corrections include the setup flow (model access, optional packages, alphaXiv login, pandoc), where keys are stored (plain text in `~/.feynman/agent/auth.json` with user-only permissions, not encrypted), the verifier, reviewer, and writer roles and which workflows use them, workflow steps and output files, the web-search tools and commands, and dead Pi links (now `earendil-works/pi`).
- The landing page adds a PowerShell install command and drops cards for features that do not ship.

## v0.5.3 - 2026-09-24

### Leaner prompts, same research quality

- The system prompt and the 11 workflow prompts lost about 200 lines. A block of tool-name rules was copied into every workflow and repeated in the system prompt, and the prompts referred to memory, process, chart, and experiment tools Feynman does not ship, `FEYNMAN_SUMMARIZE_*` environment variables that nothing reads, and a PDF crash that no longer exists.
- Workflows now wait for their background subagents before the final answer. In one-shot `feynman --prompt` runs, a `/lit` run could end while its reviewer was still working and never write the provenance file.
- On the `/lit` eval with GPT-5.6 Terra, 4 of 4 questions finished, all 44 citations resolved with matching titles, and each question ran the researcher, verifier, and reviewer in under 11 minutes (0.5.2: 9-14 minutes, 43 of 43 citations).

### Smaller install

- CLI telemetry sends its command events through posthog-node, like the rest of Feynman. It no longer also sends each command as an OpenTelemetry span and two log records, which removes nine `@opentelemetry` packages (about 28 MB). The events and what they contain are unchanged.

### Known issue

- Claude Opus 5.5 refuses some biology literature reviews (for example `/lit CRISPR base editing`) with "The model refused to complete the request". The same topics run on GPT-5.6 Terra.

## v0.5.2 - 2026-09-23

### Faster, cheaper research runs

- OpenAlex exact searches (`openalex_search_works`, citations, references, authors, venues) now return at most the tool's `limit` (default 5, max 20) instead of 50-100 full records; an explicit `max_records` is capped at 50. In live `/lit` runs these results were 100-240 KB per call and drove most of the multi-million-token usage.
- The `researcher` and `verifier` subagents run in the background by default, where they get Feynman's web and literature tools. Foreground launches of these agents failed and had to be retried.
- `alpha_ask_paper` now states it takes arXiv and alphaXiv papers only, and points DOI-only papers to `fetch_content` or Europe PMC full text.

## v0.5.1 - 2026-09-23

### Telemetry

- **Research runs are now visible in telemetry, without content.** The research extension inside Pi sends `feynman_session_started`, `feynman_workflow_started` and `feynman_workflow_completed` (workflow name such as `deepresearch` or `chat`, status, tool and subagent call counts, whether anything under `outputs/` or `papers/` was written, duration), `feynman_tool_used` (tool name and error flag), and one PostHog LLM analytics `$ai_generation` event per model response (model, provider, token counts, latency, HTTP status, stop reason; the trace ID is the Pi session ID). Prompts, model output, paper content, file paths, and tool arguments are never sent.
- **First-run notice.** The first interactive run prints a one-time notice on stderr (never in scripts or CI) saying telemetry is on, what it collects, and how to turn it off with `FEYNMAN_TELEMETRY=off`. `feynman status` shows whether telemetry is on.
- Telemetry stays on by default and follows the existing opt-outs: `FEYNMAN_TELEMETRY=off` or `DO_NOT_TRACK=1` disables the CLI and the Pi runtime events alike.

## v0.5.0 - 2026-09-23

### Stock Pi runtime

- **Pi 0.87.1, unmodified.** Feynman now runs Pi's own CLI and no longer patches Pi or its packages on disk, renames Pi, or wraps its CLI. It also drops the sealed runtime workspace (the `.feynman/runtime-workspace.tgz` archive, its hashes, and its lock), which was re-verified on every launch. `feynman --help` and `feynman doctor` start in about a second instead of several.
- **Newer Pi packages.** pi-subagents 0.71, pi-web-access 0.31, pi-btw 0.6, and pi-docparser 4.0 are now ordinary npm dependencies of Feynman, with their own dependency pins. They load as Pi packages from Feynman's install directory, so subagents see the same tools as the main session. pi-docparser's LiteParse pin (2.10.1) is used as shipped.
- **Newest standard models recommended.** With Pi 0.87.1's catalog, setup and `feynman model` recommend Claude Opus 5.5 and, for OpenAI-only setups, GPT-5.6 Terra (OpenAI's standard tier, the same one pi-web-access picks). Premium tiers such as Claude Fable and Pro models are never picked automatically but stay available through `--model` and `/model`.
- **Pi session flags pass through.** `--continue`/`-c`, `--resume`/`-r`, `--session <path|id>`, `--fork <path|id>`, `--no-session`, and `--export <session.jsonl> [out.html]` now reach Pi instead of being rejected.
- **Settings are written once.** Feynman writes its defaults on first run and afterwards only adds missing keys. Package entries from older releases are replaced with the bundled packages, and other packages you added are kept.
- **`feynman update` and `feynman packages install`** now go through Pi's own `pi update --extensions` and `pi install`. Optional packages install into `~/.feynman/agent/npm`. Pi and the core packages update when you upgrade Feynman.
- **One-shot runs exit when they finish.** The alphaXiv connection now closes when the session ends, so `feynman --prompt` and JSON runs no longer stay open after answering.
- **Explicit prompts never wait on stdin.** `feynman --prompt` and workflow commands started from a non-interactive parent no longer hang on an idle stdin pipe. Pipe text without `--prompt` to use it as the prompt.
- **`/feynman-model` is gone.** Use Pi's `/model` for the main model and pi-subagents' `/subagents` or `subagents.agentOverrides.<name>.model` for one subagent. Feynman now sets `subagents.agentExcludeDirs` to `["~/.agents"]`, so agent files there no longer silently replace Feynman's bundled agents.
- **Gemini Web cookie access** uses pi-web-access's own `allowBrowserCookies` and `browserCookies.profile` keys in `web-search.json`. The Feynman-only `geminiBrowser`, `allowBrowserAuth`, `browserAuth`, and `chromeProfile` keys are no longer read. Set `allowBrowserCookies` if you had enabled one of them.
- **Web search config moved** to `~/.feynman/agent/web-search.json`, where pi-web-access reads it. An existing `~/.feynman/web-search.json` is moved there on first launch.
- **Bundled agents, skills, and the theme** now load from the Feynman package instead of being copied into `~/.feynman/agent`. Copies left by older releases are deleted on first launch unless you edited them; edited copies keep overriding the bundled ones.
- **Telemetry:** pi-otel is no longer bundled, so the Pi runtime is not traced. Feynman still sends its own opt-out CLI command events, logs, and spans to PostHog.

## v0.4.0 - 2026-09-23

### Focused on the research loop

Feynman now ships only what serves finding papers, reading them, synthesizing with verified citations, auditing papers against code, and planning replications. Removed:

- **Science workbench:** `feynman serve` and its `--port`, `--no-open`, `--no-auth` and `--host` flags, the local web app, its demo seed data, and the workbench-only Pi tools `feynman_connector_tools`, `feynman_connector_call`, `feynman_workbench_context`, and `feynman_open_chemistry_sketcher`. The molecule, genome, alignment, and structure viewer libraries are no longer installed with Feynman.
- **Non-literature databases:** `feynman_science_database_search` now covers OpenAlex, arXiv ID lookup, PubMed, Europe PMC (including open-access full-text sections), bioRxiv/medRxiv, and Crossref. Biomedical, chemistry, genomics, variant, omics, regulatory, clinical-trial, grants, protein and structure sources were removed, along with DataCite. The tool's prompt text went from about 17 KB to about 2 KB per session.
- **Model endpoints:** the NVIDIA BioNeMo `feynman_model_endpoint_call` tool.
- **Skills:** protein and bio model templates (AlphaFold2, OpenFold3, Boltz, Chai-1, ESMFold, ESM2, Evo 2, Borzoi, DiffDock, ProteinMPNN, LigandMPNN, SolubleMPNN, scGPT, scvi-tools, indication dossier), Modal/RunPod/SSH/model-endpoint compute templates, and the `customize`, `self-awareness`, `product-self-knowledge`, `contributing`, `skill-creator`, `figure-composer`, `figure-style`, and `paper-narrative` skills. `/replicate` and `/autoresearch` still offer Docker, Modal, and RunPod as execution choices.
- **Commands:** `/commands` and `/capabilities`. Use `/help` for the grouped command list and `/tools` for the tool list.
- **Workflows:** `/watch` and `/jobs` (and `feynman watch` / `feynman jobs`). Both depended on a `schedule_prompt` scheduler tool that Feynman does not ship, so they could only report scheduling as blocked.
- **PaperRank and paper access:** `feynman rank` (with `--limit`, `--expand-citations`, `--full-text-top`, `--critique-top`, `--synthesize`, `--synthesis-top`, `--synthesis-model`, `--preference-file`, `--reproduction-notes`, `--source-fixture`, `--output-dir`, `--json`) and `feynman paper` (`--fetch-full-text`). PaperRank seeded from an OpenAlex keyword search without an API key and missed seminal papers that a citation-sorted search finds; use `/lit` or `/deepresearch`, which search, rank, and read papers through the literature tools. For one paper's full text, ask the agent, which uses Europe PMC, PubMed, and `fetch_content`.
- **arXiv topic search:** the `arxiv` source of `feynman_science_database_search` now only looks up papers by arXiv ID (bare IDs, URLs, or `arxiv_get_papers:`). `arxiv_search:` and free-text queries were removed because arXiv's lexical API ranked concept queries poorly (0 of 9 seminal papers in the search benchmark); search topics with `semanticscholar` or `openalex` instead.
- **Removed commands exit with a pointer:** `feynman serve`, `watch`, `jobs`, `rank`, and `paper` now print that the command was removed after 0.3.49 and exit with status 1 instead of starting a chat with that word as the prompt.
- **Local state:** Feynman no longer creates `~/.feynman/active-org.json` or `~/.feynman/orgs/`. Existing workbench data in those folders is left in place; delete it if you no longer need it.

Everything removed is preserved in the repository at the `archive/pre-deslop-0.3.49` git tag. To recover a piece, check it out from that tag, for example `git checkout archive/pre-deslop-0.3.49 -- src/workbench workbench-web`, or install `@companion-ai/feynman@0.3.49` to keep using the workbench.

### Paper search

- **Semantic Scholar source:** `feynman_science_database_search` gains `source: "semanticscholar"`. By default it runs a bulk search sorted by citation count and keeps the top results (up to 20), which found 7 of 9 seminal papers in the search benchmark versus 2 for OpenAlex keyword search. `sort: "relevance"` uses relevance search and `sort: "pub_date"` returns newest first. Set `SEMANTIC_SCHOLAR_API_KEY` (free on request) to use your own rate limit; without it, a 429 from the shared anonymous pool is retried once and then reported with instructions.
- **OpenAlex semantic search and key guidance:** prefix an `openalex` query with `semantic:` to use OpenAlex's embedding search (`search.semantic`), which found the test-time-compute paper at rank 1 where keyword search missed it. `OPENALEX_API_KEY` is still sent as the `api_key` parameter when set; when it is missing, results and 401/403/429 errors now say how to get a free key.
- **Researcher and verifier guidance:** the researcher now routes by need (Semantic Scholar for general ML/CS papers, PubMed and Europe PMC for biomedicine, OpenAlex for citation graphs and semantic search, `web_search` for web sources with keyless Parallel MCP as a fallback, direct ID lookup for known papers) and runs 2–4 reworded queries per question instead of trusting one. The verifier cross-checks each cited paper's DOI or arXiv ID against two indexes and flags title/ID mismatches. Both agents can now call `feynman_science_database_search`. If you customized `~/.feynman/agent/agents/researcher.md` or `verifier.md`, Feynman keeps your copy, so merge these changes by hand.

### alphaXiv

- Updated the bundled alphaXiv client to `@companion-ai/alpha-hub@0.1.5`, which now ships the fixes Feynman used to patch in at install time: opening the login browser from WSL, printing the login URL when no browser opens, and falling back to REST search when `discover_papers` is unavailable. It also adds a paste-the-URL login for headless sessions, fixes a hang in parallel searches, and writes the token file with `0600` permissions. Feynman no longer patches alpha-hub.
- Updated `@companion-ai/alpha-hub` to 0.1.6. Expired alphaXiv tokens are now refreshed before paper tool calls instead of failing with "Invalid Authorization", concurrent calls share one refresh, logging out can no longer be undone by an in-flight refresh, the auth file is written atomically with `0600` permissions, and `feynman alpha status` checks the login with the alphaXiv server.

## v0.3.49 - 2026-09-23

### Repository and package home

- Feynman is back at `Companion-Inc/feynman` on GitHub and `@companion-ai/feynman` on npm. Installers, skills downloads, self-update checks, package metadata, research-source request identities, and docs use the Companion locations directly.
- `@companion-ai/feynman` 0.3.47 installs now see this update through `feynman`'s normal update notice. If you installed the interim `@advaitpaliwal/feynman` 0.3.48 package, migrate once with `npm uninstall -g @advaitpaliwal/feynman`, then `npm install @companion-ai/feynman`. The command remains `feynman`, and native install commands are unchanged.

### Telemetry privacy

- Research-runtime traces no longer include OpenTelemetry's automatic process and host attributes, which carried the command line (including the system prompt and any prompt passed as an argument), host name, and user name. Telemetry now goes to the new Feynman PostHog project; `FEYNMAN_TELEMETRY=off` or `DO_NOT_TRACK=1` still disables it.

### Startup and Windows reliability

- `feynman --version` answers immediately instead of first verifying the whole bundled research runtime, and healthy launches skip one redundant full runtime validation pass.
- Fixed macOS and Linux standalone bundles whose `node_modules/.bin` command links pointed at the build machine, which also blocked this release.
- Windows: patching the bundled Undici proxy runtime copies real files instead of recreating symlinks, so commands no longer fail with EPERM on non-elevated accounts; transient antivirus locks on freshly written esbuild binaries are retried.
- Removed Feynman's own `/thinking` command; Pi's built-in `/thinking` now handles thinking levels without a startup conflict warning.

### Research runtime refresh

- Updated the coordinated Pi runtime to 0.85.1, retaining Feynman's provider identity checks, research-session continuity, bounded compaction, private state files, and tool/telemetry safeguards.
- Updated native bundles to Node 24.20.0 and the research runtime compiler to esbuild 0.28.2. Kept portable npm installs within the existing package budget by removing redundant compiler binaries and dependency source maps, not platform support.
- Updated web research to pi-web-access 0.28.0 with bounded batch searches, retrievable response IDs, citation preservation, and session-scoped page-answer models. Browser cookies and new paid providers remain opt-in.
- Updated pi-subagents to 0.65.1. Research delegation now uses async workflow scripts with `runs.run` / `runs.all`; obsolete top-level `tasks` / `chain` parameters and `/chain` / `/parallel` commands are replaced by the documented workflow interface. Existing user settings are preserved; fresh installs disable automatic missions and Fleet UI.
- Moved the bundled paper tools to `@companion-ai/alpha-hub@0.1.4`, including the current alphaXiv OAuth/MCP API and result parser. Updated LiteParse to 2.14.3 while retaining document integrity checks.
- Refreshed the CLI, scientific viewers, telemetry, and website dependencies. The CLI builds with TypeScript 7; the website retains TypeScript 6 because its current Astro/ESLint integrations require the older compiler API. Preserved supported dependency majors and upstream-required pins rather than forcing incompatible upgrades.

## v0.3.48 - 2026-09-06

### Installation and source reliability

- Moved the canonical GitHub repository to `advaitpaliwal/feynman`. Native installers, skills downloads, package source/issue metadata, and public documentation now use the new owner directly.
- The canonical npm package is now `@advaitpaliwal/feynman`. Migrate old npm installs with `npm uninstall -g @companion-ai/feynman`, then `npm install @advaitpaliwal/feynman`. Future npm updates use `npm install @advaitpaliwal/feynman@latest`. The command remains `feynman`, and native install commands are unchanged.
- Historical release attestations retain their original source identity; new releases are verified against the new repository owner without relaxing provenance checks.
- Updated affected URL/query parsing dependencies in the CLI and bundled research runtime, plus the website's browser-target resolver, to patched versions.

## v0.3.47 - 2026-08-26

### Research continuity

- Resuming a valid Pi session whose JSONL file lacks a trailing newline now repairs the append boundary before new research messages are persisted, preventing the next record from being fused into the previous one.
- `/btw` and `/btw:summarize` now copy extension-registered providers, native providers, and temporary runtime API keys into their isolated child `ModelRuntime`. Side research can use the same custom provider that is already active in the main session.

### Web research

- Updated `pi-web-access` to `0.25.0`. Researchers can route search and fetch calls through an explicit HTTP(S) proxy, retrieve bounded GitHub issue and pull-request documents with comments and review threads, use Defuddle when ordinary HTML extraction is insufficient, and select Chromium browser/profile cookies explicitly.
- Gemini generate-content paths can use Google Application Default Credentials for Vertex AI, and Kimi Code Plan accounts can be selected explicitly for web search. Stored-content passage lookup also tolerates bridge defaults when `findText` is supplied.

### Observability

- Generic HTTP OTLP collectors configured through one shared endpoint now receive traces, metrics, and logs at their signal-specific `/v1/*` paths, including collectors on default HTTP and HTTPS ports. Explicit per-signal endpoints remain exact and retain their own headers and protocols; Feynman's PostHog AI trace endpoint is unchanged.
- Existing `0.3.45` pi-otel package roots migrate through the reviewed legacy digest. Embedded package setup and runtime-workspace preparation preflight every discovered pi-btw and pi-otel root before applying their combined patch plan, so an unsupported later root cannot leave earlier research packages partially updated.
- Session shutdown now flushes the telemetry SDK in its own handler, while `/otel` dashboard and collector overrides clear stale per-signal routing before rewiring exporters.

### Proxy and credential safety

- Explicit proxy credentials, target URLs, and provider request headers are delivered to curl over stdin instead of appearing in process arguments. GitHub repository clones now follow the same scoped proxy, `NO_PROXY`, and forced-direct decision as GitHub API requests.
- Vertex ADC setup documentation no longer combines `geminiAuth: "adc"` with an API key that would select API-key mode.

### Validation

- Added exact source, published-upgrade, patch-plan transaction, package-tree, runtime-archive, executable OTLP handler, stdin-only proxy credential, GitHub clone proxy, installed-runtime OTLP behavior, GitHub document, Gemini ADC, Kimi credential, BTW provider, and unterminated-session regressions.
- Runtime archives omit npm's pre-patch hidden lock metadata and verify its absence, so `npm ls` reads the committed exact lock instead of a stale nested Undici version.

## v0.3.46 - 2026-08-26

### Superseded release

- Do not install `0.3.46`. Its canceled workflow was retried and published the superseded `6bbb6e8` tree with a pi-otel shutdown failure, explicit proxy/provider credentials in process arguments, and stale npm runtime metadata. Upgrade to `0.3.47` or later.

## v0.3.45 - 2026-08-26

### Release reliability

- Windows publication smoke tests now use the supported .NET ZIP extractor instead of the pathologically slow PowerShell `Expand-Archive` cmdlet, so large native research bundles complete within the release job budget.
- Source-checkout runtime archive rebuilds now use the same fifteen-minute process budget as exact locked runtime restores, avoiding premature timeouts on slow clean environments while retaining the existing transactional exact-lock checks.

### Validation

- Added workflow and runtime regressions that bind Windows native extraction and source-archive rebuilding to their supported timeout contracts.

## v0.3.44 - 2026-08-26

### Research continuity

- Stopping a tool run now ends the active Pi loop before queued steering or follow-up research input can be drained into an already-aborted model call. The queued input remains available for the next turn instead of producing a second spurious cancellation.

### Compaction integrity

- Small-context local and proxy models now bound compaction reserve and retained-history budgets to the model's actual context window, preventing empty or short sessions from compacting continuously.
- Empty or structurally unusable summaries no longer replace research history. OpenAI Responses providers such as Grok also omit `tool_choice` when a compaction request has no tools.

### Model reliability

- OpenAI-compatible structured reasoning deltas are accumulated without reparsing and reserializing the complete history for every streamed detail, preventing long reasoning streams from blocking the event loop while preserving same-model replay.
- OpenAI models reached through Amazon Bedrock now receive images returned by research tools as sibling user-image blocks instead of unsupported images nested inside `toolResult.content`. Text stays attached to its tool result, image-only results retain an explicit placeholder, and Anthropic Bedrock models keep their native nested-image shape.

### Runtime reliability

- Non-interactive Pi extension handler work now has a cumulative 30-second budget. A handler that never settles reports its extension and event, expires its local context, safely absorbs late settlement, and lets later handlers and the research session continue.
- Timed-out model-tool and user-shell policy handlers still allow later policy handlers to run, then fail closed. User-shell interception returns an explicit non-executing result, so both TUI and RPC paths do not run the command after a policy timeout.
- Project trust, OAuth, and interactive dialogs preserve their supported behavior: documented UI prompts pause the remaining handler budget instead of resetting it, parent cancellation settles even a non-cooperative dialog, and OAuth callbacks remain outside the bounded event runner.

### Document research

- Updated the bundled LiteParse runtime to `2.14.0`. OCR rasterization now runs in bounded worker-sized rounds, and dense PDF layout deduplication avoids quadratic work. Existing parse, search, and screenshot interfaces are unchanged.

### Validation

- Added executable abort-queue, Responses payload, structured-reasoning scale, small-context compaction, and summary-usability regressions across the maintained Pi runtime.
- Added executable extension-handler deadline coverage for downstream progress, timeout reporting, expired contexts, late rejection handling, fail-closed TUI/RPC user-shell interception, cumulative dialog timing, parent cancellation, project trust, and tool permission dialogs.
- Added exact source, root/nested runtime, package-tree, and runtime-archive verifier coverage for Bedrock tool-result images across bare, regional, and global OpenAI model IDs, with an Anthropic control.
- Re-ran installed document parsing, page-count, search, screenshot, package-artifact, runtime, and clean-consumer verification against LiteParse `2.14.0`.

## v0.3.43 - 2026-08-25

### Installation reliability

- Upgrading from an older Feynman installation no longer crashes while migrating a legacy `pi-subagents` package's agent diagnostics source. Fresh native-bundle installs and updates now tolerate the older management-source layout while preserving malformed-agent diagnostics.

### Validation

- Added an executable source regression for the `pi-subagents@0.37.2` management layout that previously raised `missing management list diagnostics` during `--version`.

## v0.3.42 - 2026-08-25

### Reasoning integrity

- Same-model research turns now preserve structured reasoning metadata through session persistence and model replay instead of flattening or dropping it.
- When research history crosses a provider boundary, Feynman strips provider-private reasoning fields before forwarding it, preventing incompatible metadata from leaking into the next model's context.

### Runtime reliability

- Runtime preparation now repairs stale Pi AgentCore copies to the current maintained patch before verification, so restored and installed research runtimes cannot retain an older patch shape.

### Validation

- Reasoning and AgentCore patch validators now fail closed on missing, mixed, or stale transformations across source, bundled, restored, installed, and package-artifact copies.

## v0.3.41 - 2026-08-25

### Research continuity

- Custom research messages queued while a Pi turn is active now wait until the turn settles before they are persisted and emitted. Tool results remain adjacent to their calls, and `triggerTurn: false` notifications no longer corrupt resumable session history.
- Extension-supplied research prompts now preserve interleaved text and image order through idle, steering, and follow-up delivery, so captions and questions stay attached to the intended figure.
- Large rendered tool diffs no longer hit V8's argument-count limit. Feynman's Pi runtime also resolves `fd` and `rg` releases through GitHub's public redirect without spending anonymous API quota.

### Research images

- JPEG conversion and provider-bound resizing now continue past XMP APP1 metadata to apply a later EXIF orientation block. Figures, scans, photographs, and microscopy images no longer remain sideways when XMP precedes EXIF.

### Model reliability

- OpenAI-compatible Gemini 3 streams now preserve the first Google thought signature and encrypted reasoning details together across persisted tool-call replay.
- Foreign OpenAI-compatible tool-call IDs now retain the full hash when they must be sanitized and bounded, reducing cross-provider replay collisions.
- OpenRouter's structured `in_flight_budget_exhausted` 402 responses can use their `Retry-After` budget without replacing ordinary 429 and server-error retries or overriding an explicit provider no-retry response.
- OpenAI-compatible compaction no longer sends `tool_choice: "none"` when no tools are present, avoiding requests that strict gateways reject before summary generation.

### Runtime reliability


### Validation

- Ported the focused Pi fixes from commits `240eb29c` (following contributor precursor `7b1dcfd`), `8c16a558`, `6d05adb`, `94f6e7c`, `d8def812`, `fe37e9f9`, `27115254`, and `86c42324`, plus the structured OpenRouter retry correction, across source, bundled, restored, installed, and package-artifact copies. Added fail-closed source-map checks, restored-runtime coverage, provider and image regressions, and clean installed-package verification.

## v0.3.40 - 2026-08-24

### Research continuity

- Image-only steering and follow-up messages are now removed from Pi's pending queue state when they are delivered. Research sessions that add screenshots, paper figures, or other image context no longer remain falsely marked as waiting on input after the model receives the image.

### Validation

- Reproduced the defect on the bundled Pi `0.84.2`: the agent queue was empty after image delivery while `pendingMessageCount` remained `1` and no clearing `queue_update` event was emitted. Ported the focused fix from commit `b67b3db` across source, bundled, restored, installed, and package-artifact copies, with executable steering and follow-up regressions plus fail-closed patch verification.

## v0.3.39 - 2026-08-24

### Research continuity

- Pi no longer persists a partial compaction, split-turn, or branch summary when summary generation reaches its output-token limit. The incomplete checkpoint now fails explicitly so long research sessions retain the last complete context instead of silently replacing it with truncated history.

### Reliability

- Updated `posthog-node` to `5.51.1`. On Node 24.16 and later, each telemetry flush now sends gzip bytes directly instead of retaining a native `BlobReader` for the life of the process.

### Validation

- Backported Pi commit `97fa14e` across source, bundled, restored, installed, and package-artifact copies, with executable history, split-turn, and branch-summary regressions. Disabled stale upstream source-map directives in the forward-patched files so diagnostics cannot resolve the new guards to unrelated pre-patch TypeScript lines. Matched the PostHog fix to upstream commit `3593c43` and added a transport regression that requires a `Uint8Array` gzip body instead of a `Blob`.

## v0.3.38 - 2026-08-24

### Research artifacts

- Congress.gov and GovInfo bill parsing now excludes paired white-on-white GPO operator and print-tracking stamps from parsed text, JSON text items, and document search. Removal requires matching metadata, geometry, and exact rendered-white regions, so visible bill text and visible text that merely resembles a stamp remain available.

### Research runtime

- Pi's edit tool now preserves the original CRLF, LF, and CR terminators outside each replacement. Exact and fuzzy edits no longer create unrelated full-file diffs in mixed-line-ending research code or data.

### Validation

- Reproduced the hidden-stamp path with official 2008 and 2026 GPO bill PDFs and verified consistent parsed artifacts and searches with visible body-text, same-geometry black, white-on-dark, and white-on-RGB-245 controls.
- Added exact, fuzzy, multiline, bare-CR, restored-runtime, package-artifact, and clean installed-package regressions for the maintained Pi and pi-docparser patches.

## v0.3.37 - 2026-08-23

### Research visualization

- Updated IGV to `3.8.5`. Embedded VCF, BED, and GFF genome previews now load IGV's legacy URL-mapping catalog from `igv.org` instead of raw GitHub, avoiding unnecessary blocked-origin warnings under restrictive content-security policies.

### Validation

- Matched the installed package to the published `3.8.5` npm artifact and upstream commit `1ff36cd`, with an executable regression for the supported mapping origin.

## v0.3.36 - 2026-08-23

### Research runtime

- Cross-platform runtime repair now allows up to fifteen minutes for the exact locked npm restore. This keeps slow Windows and Node 25 clean installs from terminating a valid research-runtime rebuild at the previous five-minute process limit.

### Validation

- Reproduced the published `0.3.35` failure on Windows with Node 25 after npm exhausted the five-minute child-process budget, while the same package passed the other five Node/OS consumers and all three native installers.
- Added an exact timeout regression and retained fail-closed lock, package-graph, and post-install verification.

## v0.3.35 - 2026-08-22

### Research runtime

- Installed packages no longer accept a partial bundled-runtime extraction merely because the top-level research extensions happened to arrive first. Feynman verifies the complete staged tree before publishing it, retains only known Windows npm links whose targets exist, and runs fallback from the archive's exact npm lock with maintained runtime patches applied before publication.
- Windows runtime restoration now recreates legacy Pi package aliases as traversable directory links before launch, with a copy fallback when links are unavailable.
- Configured provider-qualified research subagents now fail explicitly if the child reports that it actually launched on a different active model, instead of silently completing with misleading model metadata.
- Research prompts beginning with `-` now pass safely through Pi's standard `--` end-of-options delimiter instead of being mistaken for runtime options.
- Updated `pi-web-access` to `0.24.2`. Automatic search prefers Codex-backed OpenAI search when the active model is `openai-codex`, keeps Exa first for other models, and reads Windows Chromium cookie expiries without overflowing JavaScript numbers.

### Workbench security

- Updated Ketcher to `3.17.2`, which renders monomer labels from opened chemistry artifacts as text instead of interpolating them as HTML.

### Validation

- Added atomic restore, completion-marker, package-lock-graph, missing-transitive-file, exact-lock fallback, pre-publication patch, crash-backup, stale-lock, stale-stage cleanup, Windows npm-link and Pi-alias repair, terminated-process, child-model verification, dash-leading prompt, exact `pi-web-access@0.24.2` source, model-routing, Windows-cookie, and Ketcher monomer-label regressions.

## v0.3.34 - 2026-08-22

### Research runtime

- Existing Pi `auth.json` and dynamic `models-store.json` files now retain administrator-managed modes and ACLs when Feynman updates them. On POSIX systems, newly created state files still use owner-only `0600` permissions.
- Research subagent guidance now directs explicit model selection through `feynman model list` and tells the parent to use an exact approved `provider/model`. Raw unscoped registry output is not added to the tool.
- Bundled and restored alphaXiv research runtimes now retain structured search-result parsing after Feynman rebuilds their runtime archive.
- Clean package builds now publish the bundled runtime archive only after compression closes, preventing intermittent partial-archive reads on Node 25.

### Validation

- Backported Pi's focused managed-state permission fix from commit `c49906e` and the Feynman-safe guidance portion of pi-subagents commit `62e0934`.
- Added exact transformation, fail-closed, fresh-file, existing-mode, launch-root, restored-runtime, installed-package, registered-tool, runtime-archive parser, and atomic archive-publication regressions.

## v0.3.33 - 2026-08-22

### Research evidence

- arXiv metadata now accepts only the requested paper's Atom entry plus exact HTTPS arXiv paper and PDF links instead of trusting labels or URL substrings from untrusted responses.
- Europe PMC full text decodes XML entities exactly once, preserving nested encodings instead of changing their research meaning.
- UCSC track descriptions now remove nested provider markup while preserving scientific comparisons in research results.
- Updated `fast-xml-parser` to `5.11.0` for unsafe entity validation, multiple-DOCTYPE rejection, and malformed XML handling.

### Workbench security

- OAuth access tokens, refresh tokens, and pending PKCE state now use atomic writes. On POSIX systems, current and migrated destination stores use `0600` files inside `0700` workspace-state directories; workspace-controlled symlinks are rejected, and legacy workspace sources are never permission-mutated during migration.
- Unexpected workbench request and OAuth callback failures now return generic responses. Local diagnostics retain only a standard error class and a bounded message fingerprint, not private paths or provider details.
- Malformed launch cookies stay unauthorized without disrupting the workbench, invalid streaming requests fail before HTTP success, and interrupted streams end with an explicit terminal error instead of silent success.
- End-to-end release workflows now declare read-only repository permissions explicitly.

### Reliability

- Updated `posthog-node` to `5.50.0`, including fixes for queue flushing, response-body timeouts, compression memory growth, shutdown, and telemetry value serialization.
- Added executable regressions for XML entities, arXiv link origins, OAuth store permissions, generic server errors, UCSC markup, and workflow permissions.

## v0.3.32 - 2026-08-21

### Web research

- Updated `pi-web-access` to `0.24.1`. Direct page retrieval now uses the upstream compatibility identity so more public sources return readable content.
- GitHub source retrieval now validates repository identities and isolates clone-cache destinations by digest before cleanup.
- `pdf.maxPages` can bound Datalab, Gemini, and local PDF extraction. It defaults to `100`.
- `openaiSearchProviders` can choose the ordered Pi provider list used for OpenAI-compatible `web_search` calls.
- Automatic search now prefers Codex-backed OpenAI retrieval when the active model is `openai-codex`; other models try Exa before OpenAI.
- Opt-in Chrome and Edge research on Windows now reads modern large cookie-expiry values safely in addition to using the corrected PowerShell 5.1 DPAPI path.

### Validation

- Matched every patched source fixture to the published `pi-web-access@0.24.1` package and GitHub tag `v0.24.1`.
- Preserved Feynman's exact config path, private cache, session model scope, Firecrawl loopback redirect confinement, browser-cookie opt-in, request deadlines, and Windows PowerShell 5.1 DPAPI correction.
- Added executable retrieval-header, GitHub identity, PDF page-limit, model-aware provider-priority, large Windows cookie-expiry, restored-runtime, and installed-package regressions.

## v0.3.31 - 2026-08-21

### Research agents

- Research subagents now stop after a context-window overflow instead of retrying the same oversized input on fallback models.
- Completed subagent tools no longer remain marked active when Pi backfills a result without a separate execution-end event.
- Logical subagent failures now reach the model as failed tool results. The model no longer treats an invalid or failed research-agent action as success.

### Web research

- Opt-in Gemini Web research on Windows can now read Chrome and Edge `v10` cookies through current-user DPAPI.
- Chromium `v20` app-bound cookies remain blocked and now return a clear diagnostic instead of a false authentication success.

### Validation

- Ported only the focused upstream `pi-subagents` context-overflow, tool-result backfill, and logical-failure corrections into the bundled research-agent runtime.
- Added exact-source, restored-runtime, installed-package, model-loop, tool-result backfill, logical-failure, and native Windows DPAPI regressions.

## v0.3.30 - 2026-08-21

### Web research

- Readable page extraction now replaces inline `data:` URI payloads with bounded omission markers before content reaches model context, the fetched-content cache, or session persistence. Raw mode still returns the exact textual response body.
- Self-hosted Firecrawl API endpoints may use `localhost`, `127.0.0.0/8`, or `::1`. The exception stays limited to the configured API origin, including redirects, and does not permit loopback research targets.
- Linux curator launches now detach `xdg-open`, so the browser process cannot hold a completed web search open.

### Validation

- Ported three focused post-`0.24.0` fixes from `pi-web-access` while preserving Feynman's exact config path, private cache, session model scope, and existing provider controls.
- Added executable readable/raw extraction, Firecrawl loopback and redirect isolation, Linux launch-failure, restored-runtime, and installed-package regressions.

## v0.3.29 - 2026-08-21

### Biomedical literature

- Concurrent PubMed, ClinVar, GEO, and other NCBI requests now share one paced queue. Literature-review turns no longer drop NCBI evidence after a burst of `429 Too Many Requests` responses.
- `NCBI_API_KEY` now reaches E-utilities while remaining redacted from reported provenance. Keyed requests use the higher NCBI budget, and `NCBI_MIN_REQUEST_GAP_MS` can set a wider delay for shared IP addresses.
- PubMed request timeouts now cover the response body as well as the initial headers.

### Research runtime

- Summary-only compaction and branch requests now disable tool calls across Pi providers. Feynman also rejects unexpected tool-call responses before they can enter a research summary.
- Provider-neutral tool choice now reaches Anthropic, Azure OpenAI, Bedrock, Google, Mistral, OpenAI, and Codex requests.
- Updated `pi-web-access` to `0.24.0` for current provider routing, provider base URLs, redirect credential stripping, and summary-model thinking suffixes. Feynman's private cache, exact config path, model scope, browser-cookie opt-in, and request deadlines remain intact.

### Validation

- Reproduced the anonymous 12-search NCBI burst on `0.3.28` at `0/12`, then verified `12/12` successful calls with pacing.
- Added executable history, split-turn, and branch-summary guards across source, package archives, and installed runtimes.
- Matched every patched `pi-web-access@0.24.0` fixture to the published npm package before applying Feynman's maintained patch set.

## v0.3.28 - 2026-08-18

### Research agents

- Delegated research now treats provider subscription usage-limit errors as retryable. Configured fallback models continue instead of ending the run.

### Model inputs

- Baseten GLM 5.2 and GLM 5.2 Fast now accept image inputs. Paper figures and other attached research images reach these models.
- Pi's model-data manifest now matches every backported catalog shard and its final model structure.

### Validation

- Backported the two focused upstream corrections across local, packaged, restored, and installed runtime copies.
- Added executable fallback behavior plus complete catalog hash and structure checks across source, package archives, and installed runtimes.

## v0.3.27 - 2026-08-17

### Provider reliability

- Google and Vertex models now honor model-specific thinking-level maps. Extended or remapped levels produce the supported provider level and use its matching token budget.
- Bedrock gateway response callbacks now receive the raw Smithy response headers. Provider routing and request headers no longer disappear before Feynman can record them.

### Model catalogs

- Removed deprecated Xiaomi MiMo model IDs while keeping the current MiMo 2.5 models across direct and token-plan providers.
- Added the current China Z.AI Coding Plan models, including GLM-4.6V, GLM-5.1, and GLM-5V-Turbo. Matching API-priced models now report their reference costs.

### Validation

- Backported four focused fixes from Pi after `0.84.2` and applied them to root, nested, packaged, and restored runtime copies.
- Added direct Google, Vertex, Bedrock, Xiaomi, and Z.AI regressions plus installed-package and archive checks.

## v0.3.26 - 2026-08-17

### Document research

- Updated the bundled LiteParse runtime to `2.13.1`. Multi-line table headers now keep in-table cells between established columns instead of silently dropping them. The existing parse, search, and screenshot tools keep their current interface.

### Validation

- Added an installed-runtime regression that reproduces the lost table-header cell and checks the corrected Markdown table.
- Re-ran the installed document parse, search, and screenshot flow against the bundled runtime.
- Fixed cross-Node runtime repair to preserve the bundled exact package manifest and overrides. Node 22 consumers now keep LiteParse `2.13.1` instead of reinstalling pi-docparser's older transitive default.

## v0.3.25 - 2026-08-16

### Research agents

- A malformed custom agent definition no longer blocks unrelated valid research agents from loading or running.
- Direct requests for a malformed agent now report its invalid configuration instead of using a lower-priority definition.
- Agent listings and doctor diagnostics now identify malformed definitions without stopping discovery.
- The default subagent tool now uses concise split prompt metadata, reducing always-loaded instructions while keeping explicit full, compact, and custom modes.

### Package reliability

- Existing `pi-web-access@0.22.0` core pins now upgrade to the bundled `0.23.0` release before launch.

### Validation

- Backported the focused upstream `pi-subagents` malformed-agent isolation fix and added installed-runtime and stale-settings regressions.

## v0.3.24 - 2026-08-15

### Document research

- Updated the bundled LiteParse runtime to `2.13.0`. Document parsing now improves garbled-text detection for mixed-font papers and uses layout-aware block classification for richer structured extraction. The existing parse, search, and screenshot tools keep their current interface.

### Validation

- Re-ran the installed document parse, search, and screenshot flow against the bundled runtime.

## v0.3.23 - 2026-08-15

### Provider login reliability

- GitHub Copilot sign-in now enables model policies sequentially instead of sending a burst of parallel requests.
- If Copilot rate-limits model discovery, Feynman honors `Retry-After` and retries once instead of ending sign-in.

### Validation

- Added exact source, packaged-runtime, and login regressions for the Copilot rate-limit path.

## v0.3.22 - 2026-08-14

### Web research

- Updated `pi-web-access` to `0.23.0`. Researchers can use Firecrawl search and opt-in authenticated browser fetch profiles.
- Preserved Feynman's exact web-search config path, private fetched-content cache, resolved Pi model scope, browser-cookie opt-in, raw-result default, and bounded primary-search deadline.

### Research runtime

- Updated the bundled Pi runtime to `0.84.2`. Fullscreen transcript search now supports match navigation and configurable match colors.
- Managed tool downloads now report progress after the TUI mounts, and model catalog refreshes no longer restart when a selector opens during startup.
- Optional non-nullable tool arguments that arrive as `null` are now omitted before execution, while other malformed arguments remain rejected.

### Validation

- Added exact-source gates for the `pi-web-access@0.23.0` contract and refreshed the packaged runtime lock and archive.

## v0.3.21 - 2026-08-13

### Document research

- Updated the bundled LiteParse runtime to `2.12.0`. Document parsing now handles large documents more reliably and fixes rotated-page edge clipping and Markdown inline-code escaping. The existing parse, search, and screenshot tools keep their current interface.

### Validation

- Re-ran the installed document parse, search, and screenshot flow against the bundled runtime.

## v0.3.20 - 2026-08-12

### Current research

- Added the local current date to parent research turns and `researcher` child sessions.
- Required current-source checks for recent claims and stopped models from rejecting valid post-training data by date alone.

### Package reliability

- Reconciled Feynman-managed package sources to the exact bundled versions before launch.
- Removed stale managed shadow installs while preserving custom package selectors, package filters, and optional packages.

### Validation

- Added clean stale-settings, stale-install, broken-symlink, custom-package, and installed model-context regressions.

## v0.3.19 - 2026-08-11

### Web research

- Updated `pi-web-access` to `0.22.0`. Researchers can use Bocha as a configured search route.
- Added `maxInlineContentChars` for larger fetched-page and stored-content slices. The default remains 30,000 characters, with a 200,000-character cap.

### Reliability

- Adopted upstream fetched-content cache hardening and removed Feynman's temporary storage replacement.
- Preserved Feynman's exact config path, private cache location, model scope, browser-cookie opt-in, raw-result default, and 90-second primary-search deadline.

### Validation

- Added exact-source gates for Bocha routing, configurable content limits, cache hardening, and the full Feynman patch set.

## v0.3.18 - 2026-08-11

### Research agents

- Loaded Feynman's research-tool extension explicitly in every bundled `researcher` child session.
- Kept Hugging Face dataset and repository tools in the strict researcher allowlist without relying on ambient child discovery.

### Reliability

- Preserved custom researcher extension overrides while adding the bundled provider to default settings.
- Made the published subagent smoke reject unavailable child-tool diagnostics even when the parent model repeats a child result.

## v0.3.17 - 2026-08-11

### Web research

- Exposed the stored response ID in every single-URL `fetch_content` result, including short pages and failures. Researchers can now pass the exact ID to `get_search_content` instead of guessing from hidden tool details.
- Bounded the fetched-page cache to 128 entries and 128 MiB. Feynman removes expired entries first, then evicts the oldest entries until both limits hold.

### Security and reliability

- Normalized fetched-content cache permissions to `0700` directories and `0600` files on macOS and Linux.
- Rejected cache-directory and cache-entry symlinks, removed stale extension-owned temporary files, and moved writes to exclusive random temporary files with durable atomic replacement.
- Made concurrent pruning tolerate entries that another Feynman process already removed.

### Validation

- Ported the focused storage repair from upstream `pi-web-access` PR `#241` at commit `b3e784f`, while retaining Feynman's exact custom configuration path.
- Added regressions for model-visible response IDs, quota eviction, temporary-file cleanup, permissions, symlink rejection, and concurrent deletion.

## v0.3.16 - 2026-08-10

### Web research

- Updated `pi-web-access` to `0.21.0`. Full fetched pages now live in a private external cache instead of session JSONL, so search-heavy sessions stay bounded and restore without loading page bodies into the transcript.
- Added per-tool and per-command registration gates, direct-image and PDF extraction gates, and a configurable summary-generation deadline.
- Documented the exact `get_search_content` argument constraints and added `/web-results` for browsing stored web results without conflicting with session search.

### Reliability

- Kept the fetched-content cache beside Feynman's exact web-search configuration, including custom `FEYNMAN_WEB_SEARCH_CONFIG` paths.
- Preserved Feynman's project-local PDF scratch files, session model scope, browser-cookie opt-in, raw-result default, and bounded primary search deadline.
- Restored automatic package reconciliation for workspaces that retained the `0.3.15` core package pins.

### Validation

- Verified the exact upstream `0.21.0` source through all `437` tests, typecheck, production audit, and package inspection.
- Added regressions for external cache persistence, bounded session metadata, the `/web-results` gate translation, current feature markers, and installed tool and command registration gates.

## v0.3.15 - 2026-08-10

### Model selection

- Fixed the Pro-class cost guard so exact DeepSeek V4 Pro model IDs remain selectable across Pi providers. These open-weight models use ordinary provider pricing even though their product name contains `Pro`.
- Kept premium service tiers such as Gemini Pro and `o1-pro` blocked. Feynman does not provide a broad environment-variable bypass for future Pro-class models.
- Preserved an existing DeepSeek V4 Pro default during settings repair, included it in model lists and recommendations, and allowed explicit CLI and PaperRank synthesis selection.

### Validation

- Added regressions for Pi's direct, vendor-prefixed, and Fireworks DeepSeek V4 Pro IDs across catalog, recommendation, explicit-model, default-setting, and settings-normalization paths.

## v0.3.14 - 2026-08-10

### Web and document research

- Updated `pi-web-access` to `0.20.0`. Researchers can use keyless DuckDuckGo HTML search as an explicit provider or fallback route.
- Added optional Datalab PDF-to-Markdown extraction before Gemini and local PDF.js. Datalab retains tables, multi-column order, headings, links, and math, while the local parser remains the no-key fallback.
- Fixed Gemini Web requests that failed when Google response headers exceeded the host agent's default HTTP/1.1 header limit.

### Reliability

- Preserved Feynman's project-local fetch cache, exact web configuration path, session model scope, browser-cookie opt-in, and bounded search deadline across the upstream upgrade.
- Updated root and packaged runtime IP parsing to `10.5.0`, so IPv6 URL parsing fails gracefully for non-IPv6 hosts instead of throwing.
- Restored automatic package reconciliation for workspaces that retained the `0.3.13` core package pins.

### Validation

- Verified the exact upstream `0.20.0` source through all `425` tests, typecheck, production audit, and package inspection. Added installed-runtime checks for DuckDuckGo and Datalab.

## v0.3.13 - 2026-08-09

### Reliability

- Kept Pi agent-managed `brace-expansion` versions at or above the current secure `5.0.9` floor intact. A newer registry release can no longer stop Feynman during launch, while stale `5.0.6` through `5.0.8` trees still upgrade to the verified `5.0.9` package.
- Kept malformed and older unsupported versions fail-closed instead of weakening the launch-time security repair.

### Validation

- Added source, package-lock, installed-tree, and exact agent-managed runtime regressions for future `brace-expansion` versions.

## v0.3.12 - 2026-08-08

### Research runtime

- Updated the bundled Pi runtime to `0.84.1`. Provider authentication preflights, bounded blocked-tool termination, provider refresh transactions, and active-run reset protection now use Pi's current contracts.
- Updated Workbench chat for Pi's delta-only RPC stream. Live assistant text now accumulates correctly while the final `message_end` remains authoritative.

### Document research

- Updated `pi-docparser` to `4.0.0`. Native PDFium and OCR work now runs in isolated, cancellable child processes, so parser crashes and memory failures become bounded tool errors instead of terminating the research session.
- Added strict page, worker, DPI, search, screenshot, and output limits. Parse publication is atomic, JSON output has a stable `{ pages, text }` shape, screenshots default to page 1, and each call accepts at most four explicit pages.
- Removed the ImageMagick requirement for supported image inputs and updated LiteParse to `2.11.1`. The document runtime now includes stronger table extraction, RTL/LTR text ordering, and source-provenance metadata support. Document parsing requires Node.js `22.19.0` or newer; Feynman's supported Node floor already satisfies it.
- Added LiteParse's platform-native packages as optional npm dependencies, so one published Feynman tarball can parse documents on supported macOS, Linux, and Windows consumers.

### Web research

- Updated `pi-web-access` to `0.19.0`. `fetch_content` can now return raw textual HTTP responses, answer a question against one page while retaining its source text, retrieve direct PNG/JPEG/WebP/GIF images, and paginate long content on cleaner boundaries.
- Added exact, case-insensitive, and fuzzy passage lookup over stored page content through `findText` and `findMode`, plus current Jina Search, Kagi, Ollama Cloud, xAI, Bright Data, SerpBase, and authenticated SearXNG routes.
- Adopted current Kagi Search and Extract contracts, Gemini relay routing for local video requests, xAI quota fallback classification, and `:max` scoped summary-model matching.
- Preserved routed-provider model selection and hardened Git clone cancellation from upstream, including non-interactive credential handling and process-tree termination.

### Reliability

- Fixed `feynman alpha ask` sending obsolete `urls`/`url` arguments to alphaXiv. Paper Q&A now sends the current `paper` plus `queries` schema.
- Kept PDF scratch Markdown in the active project's `.feynman/cache/fetch-content`, kept browser-cookie access opt-in, retained the bounded primary search deadline, and adopted upstream's per-call curator isolation and no-browser timeout rather than carrying superseded local patches.
- Bound page-answer, search-rewrite, and curator summary model selection to Pi's resolved session model scope, including `--models` overrides, instead of rereading an adjacent settings file.
- Bound web-search configuration reads and writes to the same Feynman-managed path, including custom `FEYNMAN_WEB_SEARCH_CONFIG` locations, and create that file's parent before saving.
- Updated Feynman's direct, nested Pi, and packaged runtime copies of Undici to `8.10.0` for current idle-connection, readable-body, retry, HTTP/2, proxy IPv6, and DNS-origin fixes.
- Updated PDF.js to `6.2.108` and the website's audited JS-YAML and Nano ID trees to close current malicious-document and denial-of-service advisories.
- Removed macOS ACL, file-flag, Apple metadata, and extended-attribute records from bundled runtime archives so those host records no longer change package bytes.
- Updated audited Hono, `fast-uri`, `ip-address`, `express-rate-limit`, and website `brace-expansion` overrides after new registry advisories, and removed a streamed checksum-file handle from the Windows installer verifier.
- Restored automatic package reconciliation for workspaces retaining the `0.3.11`, `0.3.10`, or older `0.3.6` bundled package defaults.

### Validation

- Added an installed document-tool gate that loads the shipped TypeScript extension through Pi's bundled Jiti, then executes `document_parse`, `document_search`, and `document_screenshot` against a generated PDF.

## v0.3.11 - 2026-08-01

### Research agents

- Updated `pi-subagents` to `0.40.0` so delegated research runs have stable child identities, explicit signal-termination status, separate process and output-availability state, and clearer model and thinking-level visibility.
- Added session-scoped agent capability ceilings, chain approval checkpoints, reported token and cost budgets, and child-runtime extension acknowledgements for safer, more auditable multi-agent research workflows.
- Restored automatic package reconciliation for workspaces that retained either the `0.3.10` or older `0.3.6` bundled package defaults.

## v0.3.10 - 2026-08-01

### Runtime

- Updated the bundled Pi runtime train from `0.82.1` to `0.83.0`, including Pi's provider, session, package-install, headless OpenRouter sign-in, and extension model-scope improvements.
- Migrated Feynman's bundled extension runtime to Pi's TypeBox `1.3.7` contract. Extension authors must replace removed `Type.Base`, `Type.Awaited`, `Type.Promise`, `Type.AsyncIterator`, `Type.Iterator`, `Type.Options`, and `Value.Mutate` APIs before upgrading.
- Updated `pi-web-access` to `0.17.1` for bounded streamed fetches, Gemini-compatible provider schemas, and current search/extraction fixes, and updated `pi-subagents` to `0.38.0` for startup retries and bounded progress snapshots.

### Reliability

- Retained Feynman's fail-closed manual-compaction and eager parallel-result durability repairs because the owning upstream Pi issues remain open, and bound every Pi package plus artifact verification to the coordinated `0.83.0` train.
- Adopted Pi's native llama.cpp streaming-usage fix while preserving Feynman's automatic repair of older cached model metadata, so upgrades retain token accounting without deleting `models-store.json`.
- Reapplied the narrow Pi shrinkwrap repairs for `brace-expansion` `5.0.9` and Undici `8.9.0`; upstream Pi `0.83.0` still ships the affected `5.0.7` and `8.5.0` copies.
- Fixed `feynman update` writing user-package upgrades to a shadow npm prefix while Pi continued loading an older managed copy. Updates now target the resolved package root, reconcile stale exact-pinned core packages against Feynman's configured versions, preserve range and registry-tag selectors as unpinned sources, verify that attempted updates actually completed, and accept names such as `feynman update pi-subagents`; the in-app notice now points to that supported command.
- Fixed the Windows one-line installer failing on valid long archive entries. Extraction and rollback cleanup now run through a unique short temporary drive on the install volume while preserving the transactional replacement boundary.
- CLI analytics, log, and trace sends now make one attempt before opening a silent per-process circuit breaker, rather than printing PostHog transport errors into research output. The bundled Pi tracer also performs a silent status-checked HTTP preflight and skips exporter startup when Feynman's collector is blocked or returns an error. Set `FEYNMAN_DEBUG=1` for the single CLI diagnostic notice or `FEYNMAN_TELEMETRY=off` to disable telemetry explicitly.
- PaperRank model synthesis now rejects terminal provider errors and output-token truncation even when a failed stream contains partial text, so incomplete output cannot be labeled or written as a generated synthesis.
- Restored Feynman's 15 built-in research tools to `/tools` and `/capabilities` when Pi reports their source as the top-level `research-tools.ts` extension, including on Windows paths.

### Validation

- Added mixed-version and older/newer Pi rejection coverage, installed-package checks for all 15 Feynman tools and 9 extension commands, compilation of every installed tool schema, optional-array and malformed-null rejection through Pi's TypeBox 1.3 runtime path, managed/global package-update checks, long-path Windows installer fixtures, cached llama.cpp migration and streaming accounting checks, and exact runtime-lock and package-artifact verification.

## v0.3.9 - 2026-07-29

### Reliability

- Prevented Workbench and other RPC prompts submitted during manual compaction from being acknowledged and then lost. Pi now rejects the prompt before a success acknowledgment with a retryable error.
- Persisted each completed parallel tool result before slower siblings finish, so successful research evidence survives an abort or restart. Restored sessions and provider requests continue to present results in the assistant's original tool-call order.
- Replaced eagerly persisted tool results in place when an extension modifies the finalized message, preventing duplicate session entries and duplicate tool-usage accounting.
- Restored token accounting for the built-in llama.cpp provider by requesting streaming usage from compatible llama-server releases. Existing cached llama.cpp model metadata is repaired in place, so users do not need to delete `models-store.json` or repeat provider setup.
- Fixed plain HTTP API and MCP traffic behind `HTTP_PROXY` using a `CONNECT` tunnel that compatible proxies reject. HTTP targets now use absolute-form forwarding while HTTPS targets continue to tunnel.
- Replaced deprecated Windows shell-with-arguments launches in native builds and stale-upgrade verification with explicitly escaped `ComSpec` invocations.

### Package Stack

- Updated Feynman's direct and nested Pi Undici runtime from `8.5.0` to `8.9.0`. The narrow Pi manifest, shrinkwrap, and installed-tree repair can be removed after a supported Pi release requires Undici `8.7.0` or newer.

### Validation

- Strengthened the installed-package and native-bundle stale-Pi gate with representative shrinkwrap metadata and its vulnerable nested dependency, a complete persistent-fixture mutation allowlist, exact security-tree checks, and byte-idempotent second-launch verification.
- Added real RPC and proxy-server regressions, reopened-session checks while parallel work remains pending, real file-store and concurrent-refresh llama.cpp migration coverage, a mock SSE token-accounting check, and package-artifact mechanism checks for every temporary Pi correctness patch plus exact Pi shrinkwrap dependency, resolved URL, and integrity metadata.

## v0.3.8 - 2026-07-29

### Reliability

- Fixed standalone upgrades failing at launch with `Unsupported Pi editor layout` when an older Pi core dependency remained in the user's package directory. Startup now leaves stale Pi core entrypoints untouched while applying the narrow nested dependency security repair and continuing to patch installed extensions, which Pi loads against Feynman's current bundled runtime.

### Validation

- Added an installed-package and native-bundle upgrade smoke that stages representative Pi `0.80.6` core entrypoints, proves those entrypoints remain unchanged, verifies extension patching stays idempotent, and launches Feynman through RPC twice before a release can publish.

## v0.3.7 - 2026-07-28

### Reliability

- Fixed `npm install @companion-ai/feynman` producing an unusable CLI when npm left the direct OpenTelemetry API hoist target empty beside Feynman's bundled Pi packages. The package now bundles its exact direct telemetry API so global installs can start reliably.

### Validation

- Added clean global-install version and help smokes to every supported Linux, macOS, Windows, and Node `22`/`24`/`25` package-consumer gate, plus post-publication verification of the registry package.

## v0.3.6 - 2026-07-28

- Raised the npm-install Node 22 floor to `22.22.0`, matching the direct telemetry runtime's actual engine contract; standalone installers continue to bundle Node `24.18.0`.

### Reliability

- Fixed alphaXiv login after its OAuth migration by shipping the current OAuth2 endpoints and validating the loopback callback state before exchanging authorization codes. `feynman alpha status` now refreshes expired credentials and verifies them against the live user-info endpoint instead of treating any cached token as logged in.
- Fixed Windows one-line installs by extracting release archives into temporary staging before replacing the installed bundle.
- Fixed workbench state switching between newly minted local organizations when concurrent processes read `active-org.json` during a rewrite. Valid manifests are no longer rewritten, and required writes are atomic.
- Option+Enter now inserts a newline in Feynman's REPL input. Shift+Enter preserves Pi's follow-up action in terminals that report modified Enter keys, Ctrl+J remains a portable newline alternative, and existing user-modified keybindings remain untouched.
- Added `/thinking [level]` so reasoning effort is discoverable and directly adjustable inside the REPL while Shift+Tab remains available. The picker follows the active model's supported levels, including `max` where Pi exposes it.
- `fetch_content` now writes extracted PDF scratch Markdown under the active project's `.feynman/cache/fetch-content` instead of `~/Downloads`. Set `FEYNMAN_FETCH_CACHE_DIR` to override the location.
- Unknown CLI flags now point to `feynman help`, and `feynman update` help clarifies that extensions update with their packages rather than through a separate `--extensions` flag.

### Package Stack

- Added `pi-btw` to Feynman's default Pi package stack so `/btw` side conversations are available during long-running research turns without requiring a separate package install.
- Updated `pi-subagents` to `0.37.2` so child runs that disable inherited project context follow Pi's current context-file contract, while reducing repeated TUI and skill-file scans.
- Updated `pi-web-access` to `0.15.0`, adding simultaneous all-provider search with partial-failure diagnostics, TinyFish search and extraction, and configurable OpenAI Responses-compatible search gateways.
- Refreshed the bundled Pi runtime packages from `0.80.3` to `0.82.1`, migrated Feynman's model/auth integration to Pi's asynchronous `ModelRuntime`, and kept the runtime fallback pins aligned with the installed package set.
- Repaired the current Pi and MCP production dependency advisories in the packaged runtime by replacing Pi's vulnerable nested `brace-expansion` copy with `5.0.8`, updating MCP SDK to `1.30.0`, and pinning its compatible Hono server dependency to `2.0.12`. The Pi repair can be removed after upstream updates its shrinkwrap; the Hono pin can be removed after MCP no longer permits the vulnerable v1 range.
- Pinned the bundled runtime's complete dependency graph in a committed lockfile, upgraded its coordinated OpenTelemetry train to `2.10.0`/`0.221.0`, and made pruning changes and archive digests invalidate stale runtime artifacts. Startup now verifies every package named by the bundled runtime manifest, so a stale Pi copy is restored even when it is not itself a user-configured extension.
- Runtime and standalone archives now bind relative build inputs and the complete patched tree, reject stale or transplanted manifests, normalize archive metadata, and omit macOS AppleDouble metadata that previously doubled package size.
- Added pre-merge Linux package/consumer plus Windows PowerShell installer replacement gates. Release publication now promotes the exact verified tarball only after native bundles pass.
- Added explicit release-package budgets of 125 MiB compressed, 360 MiB unpacked, and 42,000 files around the current bundled research runtime so accidental package growth fails before publication.
- Pinned release executors and the bundled Node `24.18.0` archives, added Linux arm64 release builds, and made every standalone installer verify the published `SHA256SUMS` entry before replacing a working installation.

### Science Workbench

- Expanded `feynman serve` into a standalone open-science workbench surface with Feynman-owned project/session/frame state, project metadata, Pi chat, frame message rows, frame backfill health records, Feynman Bio Tools, notebooks, compute inventory, artifacts, lineage, provenance, settings, memory categories, onboarding intent context, and redacted credential availability ledgers.
- Added a Feynman-owned `~/.feynman/active-org.json` and `~/.feynman/orgs/<org_uuid>/` app spine so the local workbench has an org-scoped home structure instead of a flat scratch directory.
- Added a Feynman-owned org database at `~/.feynman/orgs/<org_uuid>/feynman-workbench.db`, refreshed from the local workbench state with reference-shaped project, frame, message, artifact, artifact-version, execution, verification, memory, note, annotation, read-cursor, artifact-folder, compute-provider, MCP-grant, memory-category, routine-schedule, managed-endpoint, and capability-setting tables.
- Added compact table envelopes in that database for the remaining reference-shaped workbench ledgers Feynman already owns in state, including agents, skills, credentials, OAuth tokens, events, notifications, session activity, claims, host logs, marketplace rows, and archive rows.
- Compute-provider rows in the org database now persist egress policy and Modal environment fields, including in-place upgrades for existing local databases. Split science connector attachments, split MCP grants, and custom MCP resource identifiers are mirrored through Feynman's owned ledger rows.
- Added a Feynman-owned chemistry sketcher tool that creates editable KET, Molfile, RXN, or SMILES artifacts under `outputs/chemistry-sketches/` for the local Ketcher editor, instead of requiring a reference-app MCP runtime.
- KET, RXN, CDXML, and CXSMILES chemistry artifacts now open as first-class molecule previews in the workbench. Feynman marks these scanner formats as previewable text artifacts, shows lightweight chemistry metadata, routes sketch files into the local Ketcher editor, and avoids trying to render Ketcher-only formats through RDKit.
- Moved app-owned workbench state into `~/.feynman/orgs/<org_uuid>/workbench/workspaces/<workspace-id>/`, including workbench settings, chat sessions, uploads, memory, annotations, OAuth token references, notebook logs, Modal job scripts, managed Python/R environments, artifact snapshots, and cloud-export audit logs. Existing home-level `~/.feynman/workbench` records and checkout-local `.feynman/workbench` records are copied forward on first access.
- Added Feynman-owned credential and setup-intent state so the workbench can show which research capabilities are available without exposing raw secrets or requiring another local app at runtime.
- Added Feynman-owned skill source and license-assent ledgers so the workbench can audit its bundled science skill pack without depending on an external marketplace service.
- Added Feynman-owned watch routine ledgers so `/watch` plans and baselines appear as honest scheduled or blocked routine state in the workbench.
- Added Feynman-owned contact-email and credential-ask decision ledgers so public database contact consent and provider credential readiness are auditable without exposing raw credential values.
- Added Feynman-owned compute poller lease rows so active compute jobs and pending terminations expose the same single-writer polling guard shape as the science workbench control plane.
- Added Feynman-owned review feedback rows so user-requested reviewer passes are auditable by frame, type, model, response id, and bounded context snapshot.
- Added Feynman-owned frame rows so projects, chat sessions, artifact runs, and upload areas expose a first-class control-plane frame spine through local state.
- Added Feynman-owned project metadata rows with local owner, created/updated timestamps, context, memory state, and upload-frame linkage.
- Added Feynman-owned frame message rows so persisted chat turns are auditable by frame id, message index, UUID, role, status, and structured message JSON.
- Added Feynman-owned frame backfill health records so failed historical frame imports can be tracked without inventing failures in clean workspaces.
- Chat-produced artifacts now attach to the producing session and project by snapshot/output provenance, so Run and Project file scopes, header metrics, artifact folders, versions, and verification evidence agree even when the file slug differs from the chat frame id.
- Files now show a host selector for local workspace artifacts, SSH/BYOC compute hosts, and cloud buckets derived from Feynman's owned compute and credential state.
- HTML report previews now support element-level annotation inside the sandboxed iframe, including selector/text capture, saved badges, and the same artifact annotation/refinement path used by text, image, and PDF anchors.
- Artifact Notes now open in workbench modals with target context, existing note count, add/edit/delete controls, Cmd/Ctrl+Enter save, note preview, and Open artifact navigation, backed by Feynman's owned target-note ledger.
- Cloud storage now opens a workbench modal from Customize > Storage, showing credential-backed S3/GCS/Azure/local targets, configured or missing status, target details, connection-reference feedback, delete, and a Credentials navigation action.
- Artifact Cloud export now opens a workbench modal that shows configured and missing storage targets, lets users choose the destination path, and records exports through Feynman's owned cloud-export audit log.
- Expanded Feynman Bio Tools with no-login KEGG `link:` and `conv:` modes for batched pathway/reaction/database cross-links and outside ID conversions, including missing-ID reporting and endpoint provenance.
- Expanded Feynman Bio Tools with no-login PanglaoDB support for curated single-cell marker genes by cell type or gene symbol, including canonical-marker filters, organ/species context, nicknames, and sensitivity/specificity scores.
- Expanded Feynman Bio Tools with no-login public sources for AlphaFold DB predicted structures, ArrayExpress/BioStudies functional-genomics studies, MGnify metagenomics studies, JASPAR transcription-factor matrices, and MyGene.info gene annotations.
- Expanded Feynman Bio Tools with richer no-login PubMed support for article metadata, PMID/PMCID/DOI conversion, related-article and PMC links, citation matching, copyright/license checks, and PMC full-text routing with bounded section snippets.
- Expanded Feynman Bio Tools with richer no-login ClinicalTrials.gov support for NCT detail records, sponsor-specific trial programs, eligibility filters, investigator/contact discovery, and endpoint summaries.
- Expanded Feynman Bio Tools with richer no-login bioRxiv and medRxiv support for preprint DOI lookup, date/category windows, published-preprint links, funder/ROR lookup, bioRxiv content statistics, and server-specific usage statistics.
- Expanded Feynman Bio Tools with no-login EBI structural and interaction sources for ChEBI compounds and ontology records, Complex Portal macromolecular complexes, IntAct molecular interactions, and EMDB cryo-EM map metadata.
- Expanded Feynman Bio Tools with no-login public atlas and regulatory sources for openFDA drug labels, adverse events, recalls, Drugs@FDA applications, application count aggregations, pharmacologic classes, generic-equivalent active-ingredient sets, Human Protein Atlas gene/protein expression rows, and eQTL Catalogue variant-gene association rows.
- Expanded Feynman Bio Tools with richer no-login ChEMBL support for compound name/SMILES similarity and substructure search, drug indications and warnings, calculated ADMET properties, ligand-target bioactivity filters, mechanism records, and target/gene search.
- Expanded Feynman Bio Tools with no-login GWAS Catalog support for curated SNP-trait associations, EFO trait search, study accessions, PMIDs, p-values, mapped genes, and ancestry/sample metadata.
- Expanded Feynman Bio Tools with exact human-genetics modes for GWAS Catalog association, trait, study, and SNP detail queries; eQTL Catalogue dataset and dataset-scoped association queries; and PheWeb/FinnGen variant, gene, phenotype-listing, and phenotype-search PheWAS workflows.
- Expanded Feynman Bio Tools with exact literature modes for OpenAlex work search/detail, citations, references, author search/detail, venue metadata, and arXiv search plus batch paper retrieval.
- Expanded Feynman Bio Tools with exact protein-annotation modes for InterPro/Pfam domain architecture, entry search/detail, Pfam clan and family member lookups, Human Protein Atlas gene/search records, and STRING mapping/network/similarity workflows.
- Expanded Feynman Bio Tools with exact research-resource modes for Antibody Registry search/detail/catalog/stat workflows and Grants.gov Search2 opportunity lookup by keyword, opportunity number, ALN, agency, status, eligibility, funding category, and funding instrument.
- Expanded Feynman Bio Tools with exact Rfam RNA modes for family metadata, accession/id conversion, seed alignments, covariance models, phylogenetic trees, sequence regions, PDB structure mappings, and batch sequence search.
- Expanded Feynman Bio Tools with exact omics-archive modes for ArrayExpress experiments/files/samples, GEO series search/detail, MetaboLights studies/files/data files, MGnify studies/analyses, and PRIDE project/protein-evidence workflows.
- Expanded Feynman Bio Tools with exact regulation modes for ENCODE experiment/biosample/file search and detail records, JASPAR matrix/version/catalog workflows, and UniBind dataset plus regional TFBS workflows through UCSC hub data.
- Expanded Feynman Bio Tools with exact variant modes for gnomAD short variant search/detail, gene variants, constraint, region variants, liftover, ClinVar mirror variants, structural variants, mitochondrial variants, CADD variant/position/range scores, direct ClinVar search/accession/rsID records, and dbSNP rsID/region lookup.
- Expanded Feynman Bio Tools with no-login BioMart support for Ensembl mart discovery, dataset listings, common attributes, filters, and constrained gene table retrieval through Feynman's built-in database search tool.
- Expanded Feynman Bio Tools with no-login MetaboLights support for public metabolomics study metadata, MTBLS accessions, assay context, study-folder files, and public data-file listings.
- Expanded Feynman Bio Tools with no-login UCSC Genome Browser support for assembly discovery, track search, chromosome sizes, bounded genomic region track rows, conservation score summaries, and ENCODE TFBS clusters.
- Expanded Feynman Bio Tools with exact genome modes for Ensembl lookup, xrefs, VEP variant consequence summaries, homology, sequence, and overlap-region retrieval plus UCSC `ucsc_list_tracks`, `ucsc_chrom_sizes`, `ucsc_track_data`, `ucsc_conservation`, and `ucsc_tfbs_clusters` query names.
- Expanded Feynman Bio Tools with no-login UniBind support for direct TF-DNA interaction dataset search, exact dataset model metadata, BED/FASTA/plot model links, and UCSC hub-backed TFBS region rows.
- Expanded Feynman Bio Tools with Europe PMC open-access full-text section lookup for PMCID/PMID inputs, returning section inventories, bounded snippets, figure/table/reference counts, and explicit not-open-access or missing-full-text statuses without exposing raw XML.
- Expanded Feynman Bio Tools with no-login ZINC support for purchasable compound lookup by ZINC ID, SMILES exact or analog search, supplier catalog-code resolution, random screening-set sampling, and 3D tranche repository locations.
- Expanded Feynman Bio Tools with PubChem compound search/detail, SMILES similarity, bioassay summary, and GHS safety modes; ChEBI search/entity/ontology modes; BindingDB target-ligand and compound-target modes; and Rhea reaction search/detail modes.
- Expanded Feynman Bio Tools with CIViC gene/variant/evidence/assertion/molecular-profile/disease/therapy modes, ClinGen validity/dosage/actionability/variant-classification modes, and Open Targets bounded GraphQL-compatible search plus disease-drug, disease-target, and drug wrapper modes.
- Expanded Feynman Bio Tools with GTEx dataset, tissue-site, sample, gene-resolution, expression, top-expressed-gene, and eQTL modes plus exact PanglaoDB marker-gene, gene-to-cell-type, and options modes.
- Expanded Feynman Bio Tools with exact genes/ontologies modes for MyGene query-many lookup, OLS ontology catalogue/search/term lookup, QuickGO GO annotations, UniProt TSV/FASTA/TXT entry retrieval, Reactome pathway mapping, and KEGG entry/search/link/ID-conversion workflows.
- Expanded Feynman Bio Tools with no-login CellGuide support for Cell Ontology cell-type lookup, marker genes, tissue occurrence, and CELLxGENE source collections.
- Expanded Feynman Bio Tools with no-login Antibody Registry support for antibody RRID search, catalog-number lookup, vendor filtering, registry stats, and per-antibody detail records.
- Expanded Feynman Bio Tools with credential-aware OpenAlex support for scholarly work search, work detail, DOI claimant resolution, incoming citations, outgoing references, authors, sources/venues, OA status, and rate-limit diagnostics.
- Expanded Feynman Bio Tools with cBioPortal cancer-model parity modes for study search/detail, clinical attributes, per-gene mutation rows, cross-study mutation frequency, and discrete CNA events, plus DepMap reference-name modes for model listing/detail/search, gene search, and CRISPR dependency rows.
- Added native workbench previews for audio, video, XLSX spreadsheets, Jupyter notebooks, and LaTeX/TeX artifacts alongside the existing report, JSON, PDF, genome, alignment, molecule, structure, tree, and tensor viewers.

### Website and Docs

- Added the Science Workbench guide, homepage workbench section, command-reference entry, setup notes, and README wording for the standalone workbench path.
- Corrected the npm install Node.js range in the website docs to match the package engine range.

## v0.3.5 - 2026-06-28

### Pi Runtime

- Refreshed the bundled Pi runtime packages to `0.80.2`, restoring the `@earendil-works/pi-ai/compat` entrypoint and extension-loader aliases used by optional packages such as `pi-web-access` (#183).
- Feynman's package installer now derives legacy `@mariozechner/*` alias versions from the current canonical `@earendil-works/*` runtime packages first, so stale legacy package roots cannot seed old Pi peer versions during `feynman update`.
- Updated the Pi TUI patcher for the current upstream overflow-check layout so overwide rendered lines are clipped instead of crashing the session renderer.

### Validation

- Added regressions for the current Pi TUI overflow block, release-note compat coverage, and legacy Pi alias derivation from current runtime metadata.

## v0.3.4 - 2026-06-12

### Research

- Added `feynman paper <id-or-title>` for single-paper access resolution across OpenAlex, DOI, arXiv/alphaXiv, and Europe PMC, with optional source-specific text fetching and bounded artifacts that omit raw full-text bodies.
- Added `feynman rank <topic>` with PaperRank scoring for read-first triage, transparent citation/method/reproducibility evidence, graph context, optional critique or model synthesis, bounded JSONL outputs, and provenance.
- Added `--reproduction-notes` so completed reproduction outcomes are recorded separately from planned replication checks. When reproduction notes are supplied, PaperRank writes the reproduction ledger, notes template, and replication plan; ordinary read-first runs keep those extra artifacts out of the default output.

### Model Catalog

- Fixed research model selection so recommended/default model paths, stale settings, model lists, and explicit CLI overrides reject Pro-class model IDs and keep OpenAI-only installs on the newest available non-Pro GPT model exposed by Pi.
- Added PaperRank model-selection provenance so CLI output, JSON output, generated synthesis Markdown, and rank provenance name the actual synthesis model and whether it came from the recommendation path or an explicit override.
- Updated setup/configuration examples and the LiteLLM fallback prompt to avoid GPT-4-era and premium-tier defaults.

### Pi Runtime

- Refreshed the bundled Pi runtime packages to `0.79.10` and updated production dependency overrides so `npm audit --omit=dev` is clean after the refresh. This inherits Pi's compaction-event context, exact-version update flow, nested-repo `find` fix, and OpenAI-compatible `reasoning_details` streaming fix.
- Fixed session rename crashes when long slash-workflow names overflowed the custom header. Header workflow names are now clipped to their column in both wide and narrow layouts before descriptions are rendered.
- Removed the old `generative-ui`, `ui`, and `all-extras` optional package/update targets. Optional packages now stay one-by-one and research-continuity focused.

## v0.2.58 - 2026-05-16

### Optional Packages

- Added a `hindsight` optional preset that installs `@luxusai/pi-hindsight`, giving users a first-class path to Hindsight-backed research-continuity memory without adding it to the default install.
- Added `hindsight` and `pi-hindsight` update aliases so `feynman update hindsight` resolves to the same package source.
- Updated the package-stack and setup docs to show Hindsight as an optional memory surface and note that it requires a Hindsight server or Hindsight Cloud account.

### Validation

- Added regression coverage for the new optional preset, research-continuity package copy, removed bulk/UI presets, and update aliases.

## v0.2.57 - 2026-05-15

### Runtime Reliability

- Fixed the interactive prompt input color on macOS/iTerm profiles where typed text inherited a black terminal foreground against Feynman's dark editor background.
- Applied the editor foreground/background patch through the shared Pi patch module so package-local installs and the vendored runtime archive stay in sync.

### Validation

- Added regression coverage for the patched Pi editor/theme source transformations, including idempotency.

## v0.2.56 - 2026-05-13

### Security

- Updated the `protobufjs` dependency override from `7.5.5` to `7.5.8`, which pulls in the patched `@protobufjs/utf8` release and clears the current production audit advisory set.

### Validation

- Re-ran the root production audit after the override refresh and confirmed it reports zero vulnerabilities.

## v0.2.55 - 2026-05-13

### Model Catalog

- Updated Feynman's research model preference order so the newest available non-Pro OpenAI GPT model can be recommended, auto-selected, and surfaced ahead of older OpenAI GPT models.
- Applied the same newest-available non-Pro GPT preference to OpenAI Codex when Pi exposes Codex directly.
- Updated first-run/default setup preferences so OpenAI-only installs choose the newest available non-Pro OpenAI GPT model when available.

### Validation

- Added regression coverage for newest-available non-Pro OpenAI recommendation, model sorting, and default setup seeding.

## v0.2.54 - 2026-05-11

### Runtime Reliability

- Fixed packed npm installs that hoist package dependencies outside Feynman's package root. Feynman now falls back to its vendored `.feynman/npm` runtime workspace when resolving Pi, so `feynman doctor` and prompt launches work from a clean packed install.
- Applied runtime node-module patches to both package-local dependencies and the vendored runtime workspace.

### Validation

- Added regression coverage for packed-install Pi path resolution and vendored runtime patching.
- Added an isolated packed-install E2E that installs the generated tarball into a clean prefix/home and launches Feynman from that install.

## v0.2.53 - 2026-05-11

### Runtime Reliability

- Hardened alphaXiv search fallback again: if both the removed MCP search tools and `discover_papers` are unavailable, `alpha search` now falls back to the public alphaXiv fast REST search endpoint.
- Patched the Pi extension loader to alias both `@mariozechner/*` and `@earendil-works/*` Pi runtime imports to Feynman's already initialized bundled runtime, preventing mixed-namespace TUI/theme crashes when expanding tool output.
- Applied the extension-loader patch to the vendored runtime archive path, not only the local development `node_modules` path.

### Validation

- Added regression coverage for upgrading the old `discover_papers`-only alphaXiv patch and for dual-namespace Pi runtime aliasing.

## v0.2.52 - 2026-05-09

### Runtime Reliability

- Seed bundled runtime packages before package updates so missing undeclared extension dependencies such as `typebox` are repaired before extension load.
- Include Pi's `typebox` runtime package beside installed Pi packages when Feynman has to run npm directly.
- Include the new `@earendil-works/*` Pi runtime package namespace beside the legacy `@mariozechner/*` namespace so updated Pi extensions such as `pi-btw` and `pi-markdown-preview` can load.
- Patched alphaXiv search in the bundled alpha-hub runtime to fall back to the newer `discover_papers` MCP tool when alphaXiv no longer exposes the older search tool names.
- Hardened model tool-call handling for common alias mistakes: `search_web` now maps to `web_search`, and bare `fetch` / `WebFetch` / `read_url_content` map to `fetch_content` with array URLs normalized.
- Fixed the Windows docker probe in the research header so `cmd.exe` no longer emits localized mojibake from Unix-only `/dev/null` redirection.

### Workflow Prompts

- Added a shared tool-discipline block to every workflow prompt so lead agents see canonical tool names before workflow-specific instructions.

### Validation

- Added regression coverage for alphaXiv search fallback, Pi tool alias normalization, bundled runtime dependency installs, and prompt tool discipline.

## v0.2.51 - 2026-05-09

### Package Manager

- Hardened Pi package installs and updates so peer-only Pi runtime packages are materialized into Feynman's npm prefix beside installed Pi packages.
- This prevents optional or legacy Pi packages from failing at extension load time when they import Pi runtime modules that npm did not install because Feynman uses legacy peer dependency mode.

### Validation

- Added package-manager coverage for installing Pi runtime peers beside Pi npm packages.

## v0.2.50 - 2026-05-09

### Skills Installer

- Added an explicit Codex skills target for standalone skill installs: `--codex` on macOS/Linux and `-Scope Codex` on Windows.
- Kept the existing default/user install behavior compatible while documenting the Codex, repo-local Claude/agent, and OpenCode target paths.

### Validation

- Added installer coverage for the Codex target and target-specific docs.

## v0.2.49 - 2026-05-07

### Website

- Updated the website build stack to patched Astro 6/Vite 7.
- Migrated docs content collections to Astro's current content-layer config.

### Validation

- Website build, typecheck, lint, and production audit passed.
- Root build, typecheck, full tests, package dry-run, native bundle build, and production audit passed after the website upgrade.

## v0.2.48 - 2026-05-07

### Fixes

- Restored Node.js 24 support for the Feynman CLI and npm package.
- Slimmed the default Pi package set to the core AI research essentials: alphaXiv access, subagents, document parsing, and web access.
- Moved memory and session search out of the default install path so optional package failures cannot block first launch.
- Kept session search gated to Node.js 22.x because its upstream sqlite dependency still depends on native prebuild coverage.
- Upgraded the TypeScript toolchain to 6.0 and updated the build config for its explicit `rootDir` requirement.

### Documentation

- Updated package-stack, setup, install, and session-search docs to distinguish core researcher packages from optional extras.

### Validation

- Full local tests passed: 157/157.
- Typecheck, root build, website build, native bundle build, production `npm audit --omit=dev`, and package dry-run passed.
- Package dry-run verified the bundled runtime workspace excludes memory and session search by default.

## v0.2.47 - 2026-05-07

### Documentation

- Clarified that Feynman's package, extension, and skill wiring follows Pi's upstream package model.
- Linked the Hugging Face Hub API and environment-variable docs from the README and website docs.
- Clarified that Hugging Face file reads refuse obvious model weights, archives, and dataset shards before download.

### Validation

- Tightened the Hugging Face binary-file refusal regression test.
- Full local tests passed: 157/157.
- Typecheck, root build, website build, and production `npm audit --omit=dev` passed.

## v0.2.46 - 2026-05-07

### Updates

- Added the `/recipe` workflow for ranked ML training recipes backed by papers, datasets, docs, implementation paths, and verification status.
- Added read-only Hugging Face Hub inspection tools for dataset metadata, repo file listing, and small text file reads. These support recipe and replication grounding without requiring Hub write access, and refuse obvious weight/archive/shard reads before download.
- Updated `/replicate` so ML-heavy targets perform a recipe extraction pass before execution planning.

### Documentation

- Added website docs for the `/recipe` workflow and Hugging Face Hub tools.
- Updated README, quickstart, command references, agent docs, replication docs, and package-stack docs for the new workflow and tools.

### Validation

- Added unit coverage for Hugging Face tool registration, endpoint formatting, auth headers, file listing limits, truncation, and binary-file refusal.
- Full local tests passed: 157/157.
- Typecheck, root build, website build, CLI help, and live Hugging Face endpoint smoke checks passed.

## v0.2.45 - 2026-05-07

### Updates

- Updated the bundled Pi runtime packages to `@mariozechner/pi-ai@0.73.0` and `@mariozechner/pi-coding-agent@0.73.0`.
- Updated `@clack/prompts` to `1.3.0` for the setup/onboarding prompt surface.

### Validation

- Full local tests passed: 154/154.
- Typecheck, root build, website build, `feynman doctor`, and production `npm audit --omit=dev` passed.
- JSONL RPC smoke passed with `get_state` and a `bash` command returning `FEYNMAN_RPC_OK`.
- Release CI published npm `0.2.45`, built all native bundles, and created the GitHub release.

## v0.2.44 - 2026-05-06

### Fixes

- Updated transitive dependency override pins to patched versions so production `npm audit` reports zero vulnerabilities.
- This removes advisories in `basic-ftp`, `fast-xml-parser`, `hono`, and `ip-address` while keeping the dependency changes scoped to existing transitive packages.

### Validation

- Production `npm audit --omit=dev` passed with zero vulnerabilities.
- Full local tests passed: 154/154.
- Typecheck, root build, website build, and `feynman doctor` passed.

## v0.2.43 - 2026-05-06

### Fixes

- Restricted `.feynman/web-search.json` permissions to user-only (`0600`) after Feynman writes web-search provider configuration.
- This protects stored web-search API keys such as Exa, Perplexity, and Gemini keys from permissive local umasks.

### Validation

- Added POSIX regression coverage for saved web-search config permissions.
- Full local tests passed: 154/154.
- Typecheck and build passed.

## v0.2.42 - 2026-05-06

### Fixes

- Fixed runtime RPC startup in projects with `.feynman/settings.json` package entries by patching Pi's project npm install path to use peer-dependency-compatible installs.
- This prevents project-scoped package sync from failing on packages such as `@aliou/pi-processes` before the RPC session can start.

### Validation

- Added regression coverage for the embedded Pi package-manager patch.
- Real `v0.2.41` release RPC testing reproduced the missing project-package install failure that this release fixes.

## v0.2.41 - 2026-05-06

### Fixes

- Fixed startup package seeding so copied bundled packages are treated as satisfied instead of falling through to repeated global npm installs.
- Seeded bundled packages before interactive setup reports missing packages, avoiding unnecessary first-run package prompts when the standalone bundle already has the runtime workspace.
- Restricted supported Node.js runtimes to Node 20.19.x through Node 22.x because sqlite-backed Pi packages such as session search are not reliable under Node 24.
- Updated release CI to build, test, publish, and package native bundles with Node 22.

### Documentation

- Added research-only biomedical literature review guidance with PICO/PICOS framing, evidence-type separation, privacy boundaries, and non-clinical-advice wording.
- Updated npm install docs to show the new supported Node engine range.

### Validation

- Full local tests passed: 151/151.
- Typecheck and root build passed.

## v0.2.40 - 2026-04-19

### Fixes

- Fixed local-model web-search failures where a model calls non-existent search aliases such as `google:search`; Feynman now maps those aliases to Pi's real `web_search` tool when it is available.
- Granted the bundled researcher and verifier agents access to Pi web-access tools (`web_search`, `fetch_content`, and `get_search_content`) so their prompts and allowed tools match.
- Made `feynman doctor` and `feynman search status` explicitly show when `web-search.json` has not been created and how to initialize it.
- Stopped treating expired OAuth credentials as authenticated model availability, so `doctor`, `model list`, and onboarding guide users to re-login instead of failing later in chat.
- Added a package-workspace setup lock so concurrent Feynman invocations do not race while restoring `.feynman/npm`.

### Validation

- Full local tests passed: 137/137.
- Typecheck, build, vendored runtime regeneration, runtime archive inspection, sequential CLI smoke, and parallel CLI smoke passed.

## v0.2.39 - 2026-04-19

### Fixes

- Fixed TUI-selected thinking/reasoning effort persistence. Feynman no longer passes an implicit `--thinking medium` on every launch, so thinking levels saved by Pi after `Shift+Tab` survive restarts.
- Explicit `--thinking <level>` and `FEYNMAN_THINKING=<level>` still override the saved default for that launch.

### Validation

- Added regression coverage that Feynman only passes a launch thinking override when it was explicitly configured.
- Full local tests passed: 126/126.
- Typecheck and build passed.

## v0.2.38 - 2026-04-19

### Fixes

- Fixed `feynman update memory` and `feynman update session-search` so friendly core-package aliases resolve to the correct npm package sources and use Feynman's npm install path with peer-dependency compatibility flags.
- Fixed `feynman summarize ... --window-size ...` and related summarize tuning flags when the flags appear after the source positional.
- Fixed `feynman setup preview` so it actually runs the preview dependency check, matching the legacy `--setup-preview` alias.
- Made optional `generative-ui` install/update failures degrade cleanly on macOS toolchains where upstream `glimpseui` cannot compile, without dumping thousands of Swift compiler lines.
- Reduced deepresearch TUI redraw churn by freezing the Feynman header's Last Activity snapshot during live streaming work instead of recomputing it every render.
- Fixed bundled skills that referenced prompt templates through broken installed relative paths.
- Fixed the embedded Pi patcher so repeated runtime preparation does not duplicate the TUI stdin error handler.

### Documentation

- Documented `feynman setup preview`.
- Documented the existing `Shift+Tab` thinking-level hotkey and `/hotkeys` discovery path.

### Validation

- Full local tests passed: 124/124.
- Typecheck, build, and clean website build passed.
- Local CLI matrix passed for help, doctor, status, model list/tier, search status/set, alpha status, setup preview, packages list/install, and package update aliases.
- End-to-end workflow runs completed for chat, summarize, review, compare, audit, draft, lit, deepresearch with confirmation, replicate, watch/jobs, log, and a bounded autoresearch loop.

## v0.2.37 - 2026-04-19

### Fixes

- Hardened `/deepresearch` reviewer/audit fix handling so Feynman may only claim a patch landed after the edit/write tool succeeds and an explicit on-disk check proves the old unsupported content is gone and the corrected content exists.
- Added provenance requirements for failed edit recovery so verification notes cannot mark an issue fixed before the final candidate actually reflects the fix.
- Corrected MiniMax model preference casing to match Pi's exposed model IDs.

### Performance

- Resolved preview/runtime executables in parallel before launching Pi, reducing synchronous startup work while preserving Windows, macOS, and Linux fallback behavior.

### Fork Review

- Scanned all public forks and selectively adopted the low-risk startup/model-test improvements. Rejected product-specific or bloated fork changes such as Claude CLI bypass mode, ValiChord, Overleaf export, and an external `parallel-cli` dependency.

### Validation

- Full local tests passed: 121/121.
- Typecheck, build, local CLI doctor, and real one-shot launch smoke test passed.
- Fork scan compared 676 accessible forks: 666 behind, 2 identical, 8 with unique commits inspected.

## v0.2.36 - 2026-04-18

### Fixes

- Hardened `/review` so it writes a durable plan, evidence notes, and `outputs/<slug>-review.md` instead of stopping after a planning/narration response.
- Added blocked-review fallback behavior for PDFs or external sources that cannot be parsed, so failed extraction still produces an explicit review artifact with `Verification: BLOCKED`.
- Fixed subagent child-process spawning under Feynman's Pi wrapper so writer/reviewer subagents no longer treat `--mode` as a module path.
- Made optional package presets platform-aware so Linux users do not see or attempt to install the macOS-only `generative-ui` package.
- Added the Release Notes entry to the website docs sidebar.

### Documentation

- Updated research review docs to describe the concrete output files and blocked-extraction behavior.
- Updated package docs to clarify that memory and session search are core packages and `generative-ui` is macOS-only upstream.

### Validation

- Added regression coverage for the `/review` durable-artifact contract.
- Added regression coverage for platform-aware optional presets and Feynman-aware subagent spawning.
- Real installed-global review, package-list/install, subagent, and extension-load checks were run before release.

## v0.2.35 - 2026-04-18

### Fixes

- Restored the `/deepresearch` confirmation gate: the workflow now writes `outputs/.plans/<slug>.md`, summarizes the plan, and waits for explicit user approval before searching, drafting, citing, or delivering final artifacts.
- Changed top-level workflow invocation so `feynman deepresearch ...` behaves like the REPL workflow in a real terminal instead of forcing one-shot execution.
- Added a Feynman wrapper around Pi's CLI entrypoint so completed print-mode runs exit cleanly after Pi finishes.
- Tightened direct-mode `/deepresearch` artifact paths so research notes and verification files are written under `outputs/.drafts/`.

### Features

- Added section-focused `alpha_get_paper` extraction with `section` / `sections` filters for abstract, introduction, methodology, experiments, results, discussion, limitations, and conclusion.
- Added configurable `/summarize` context-window controls via flags and `FEYNMAN_SUMMARIZE_*` environment variables.

### Documentation

- Added public `RELEASES.md` and website release notes so each release has visible fix and feature history.
- Updated deep research docs to describe the plan-confirmation workflow and current PDF-safety behavior.

### Validation

- Real installed-global REPL test: typed `/deepresearch what is BM25`, verified that only the plan existed before approval, then replied `yes` and verified final report, provenance, draft, cited draft, research notes, and verification artifacts.
- Full local tests passed: 117/117.
- Typecheck, build, website build, local pack, and local global install checks passed.

## v0.2.34 - 2026-04-18

### Fixes

- Tightened `/deepresearch` so direct-mode research must use at least three distinct search terms or angles before drafting.
- Required direct-mode `/deepresearch` to record the exact search terms in the direct research artifact.
- Added regression coverage for the multi-query deep research contract.

### Validation

- Real RPC smoke test for `/deepresearch what is BM25` completed and wrote the required plan, draft, cited draft, final report, and provenance artifacts.
- Release CI published npm and native bundles for macOS arm64/x64, Linux x64, and Windows x64.

## v0.2.33 - 2026-04-18

### Fixes

- Rewrote `/deepresearch` from a long protocol-style prompt into a shorter execution checklist so local models are less likely to echo instructions instead of doing work.
- Made narrow direct-mode research complete without spawning verifier or reviewer subagents.
- Avoided the crash-prone PDF parser path in `/deepresearch` unless PDF extraction is explicitly requested.

### Validation

- Real RPC `/deepresearch what is BM25` completed with required artifacts and `agent_end`.
- Full local tests, typecheck, build, audits, website build, and pack dry-run passed before release.

## v0.2.32 - 2026-04-18

### Fixes

- Fixed Pi subagent parallel output propagation so top-level task `output` paths are honored.
- Added foreground and async regression coverage for subagent output handoff behavior.
- Hardened deep research prompts around durable artifacts and provenance.

## v0.2.31 - 2026-04-17

### Fixes

- Fixed Feynman runtime auth environment propagation so launched Pi sessions can see the expected model provider credentials.
- Revalidated setup and runtime startup paths after the auth fix.

## v0.2.30 - 2026-04-17

### Fixes

- Fixed Pi subagent task output handling in the runtime patch layer.
- Preserved bundled research-agent file handoffs for multi-agent workflows.

## v0.2.29 - 2026-04-17

### Maintenance

- Updated bundled Pi runtime packages.
- Rebuilt native release artifacts against the refreshed runtime package set.

## v0.2.28 - 2026-04-17

### Maintenance

- Removed runtime hygiene extension bloat and kept the bundled runtime closer to upstream Pi behavior.
- Reduced custom extension surface area to keep the research agent simpler.

## v0.2.27 - 2026-04-17

### Fixes

- Added Pi event guards for workflow state transitions.
- Improved workflow state tracking around long-running research operations.

## v0.2.26 - 2026-04-17

### Fixes

- Switched research context hygiene onto Pi runtime hooks instead of extra custom runtime logic.
- Improved compatibility with upstream Pi runtime behavior.

## v0.2.25 - 2026-04-17

### Fixes

- Fixed workflow continuation and provider setup gaps.
- Improved setup flow behavior for model-provider configuration.

## v0.2.24 - 2026-04-16

### Fixes

- Linked bundled runtime dependencies for core Pi packages.
- Addressed missing dependency errors for installed core packages.

## v0.2.23 - 2026-04-16

### Features

- Added LM Studio setup support for local model workflows.
- Added blocked-research artifact handling so interrupted runs keep useful state.

## v0.2.22 - 2026-04-16

### Features

- Added first-class LM Studio setup.
- Improved local model onboarding defaults.

## v0.2.21 - 2026-04-16

### Fixes

- Fixed extension repair behavior.
- Added the Opus 4.7 model overlay.

## v0.2.20 - 2026-04-16

### Release

- Restored publish workflow behavior after a duplicate npm version blocked release.
- Native bundles remained available through GitHub releases.

## v0.2.19 - 2026-04-16

### Fixes

- Skipped release publication when the npm version already exists.
- Prevented repeat publish attempts from failing the pipeline after npm publication succeeds.

## v0.2.18 - 2026-04-16

### Release

- Prepared the release automation baseline used by the current npm and native-bundle pipeline.

---

### Website Src Content Docs Reference Slash Commands (`website/src/content/docs/reference/slash-commands.md`)

---
title: Slash Commands
description: Complete reference for REPL slash commands.
section: Reference
order: 2
---

Slash commands are available inside the Feynman REPL. They map to research workflows, project utilities, and commands from the bundled Pi packages. Type `/help` inside the REPL for Feynman's grouped command list.

## Research workflows

| Command | Description |
| --- | --- |
| `/deepresearch <topic>` | Run a thorough, source-heavy investigation and produce a research brief with inline citations |
| `/lit <topic-or-lab-or-author>` | Run a literature review on a topic, lab, PI, or author |
| `/review <artifact>` | Run an internal research critique with likely objections, severity, and a concrete revision plan |
| `/audit <item>` | Compare a paper's claims against its public codebase for mismatches, omissions, and reproducibility risks |
| `/replicate <paper>` | Plan a replication workflow for a paper, claim, or benchmark; execute only after an explicit environment choice |
| `/recipe <task-or-paper>` | Find ranked, implementable ML training recipes backed by papers, datasets, docs, and code |
| `/compare <topic>` | Compare multiple sources and produce a matrix of agreements, disagreements, and confidence |
| `/draft <topic>` | Turn research findings into a paper-style draft |
| `/autoresearch <idea>` | Run a bounded experiment loop against a benchmark, keeping what works |
| `/summarize <source>` | Summarize a paper, report, README, local artifact, or PDF with the source kept on disk instead of in context |

Workflow prompts can call the bundled agents (researcher, reviewer, writer, verifier) through Pi's `subagent` tool when delegation helps; narrow tasks stay lead-owned.

## Project and session

| Command | Description |
| --- | --- |
| `/log` | Write a durable session log with completed work, findings, open questions, and next steps |
| `/help` | Show grouped Feynman commands and prefill the editor with a selected command |
| `/init` | Bootstrap `AGENTS.md` and session-log folders for a research project |
| `/outputs` | Browse all research artifacts (papers, outputs, experiments, notes) |
| `/tools` | Browse public research tools with their source and parameter summary |
| `/service-tier` | View or set the provider service tier override for supported models |

## Package commands

| Command | Package | Description |
| --- | --- | --- |
| `/btw <question>` | `pi-btw` | Ask a side question while the main research agent is busy |
| `/search` | `pi-web-access` | Browse stored web search results from the current session |
| `/websearch [queries]` | `pi-web-access` | Open the search curator to run and review searches yourself |
| `/curator [on\|off]` | `pi-web-access` | Toggle the search curator workflow |
| `/subagents` | `pi-subagents` | Inspect configured agents |
| `/run <agent> [task] [--bg] [--fork]` | `pi-subagents` | Run one agent |
| `/hotkeys`, `/new`, `/quit` | Pi | Show keyboard shortcuts, start a new session, quit |

## Research delegation

The current runtime does not provide `/chain` or `/parallel` commands. Research workflows call `subagent` directly for one child, or write a workflow script for parallel or sequential work to `outputs/.plans/<slug>-workflow.js` and run it by calling `subagent` with that path. A file works with every model; an inline ```` ```js workflow ```` block with `workflow: true` fails when a model puts the block in its hidden reasoning instead of the reply.

```js
return await runs.all([
  { key: "papers", agent: "researcher", task: "Read outputs/.plans/<slug>-papers.md.", output: "outputs/.drafts/<slug>-research-papers.md" },
  { key: "web", agent: "researcher", task: "Read outputs/.plans/<slug>-web.md.", output: "outputs/.drafts/<slug>-research-web.md" },
]);
```

```json
{ "workflow": "./outputs/.plans/<slug>-workflow.js", "async": true, "globalConcurrencyLimit": 4 }
```

For sequential work, await `runs.run(key, {agent, task, output})` before starting the next step. Legacy top-level `tasks`, `chain`, and `parallel` inputs are rejected. `runs.all` returns an ordered array, including ordinary child failures; inspect each result's `ok` and returned output references.

An async launch receipt is not completion: consume the result and verify child output paths before synthesis or dependent review. Ordinary background subagents notify their parent; `bg_wait` is for background work without a native completion notification.

## Running workflows from the CLI

Every research workflow can also be run from the command line, for example `feynman deepresearch "topic"`. See [CLI Commands](/docs/reference/cli-commands#workflow-commands).

---

### Website Src Content Docs Tools Alphaxiv (`website/src/content/docs/tools/alphaxiv.md`)

---
title: AlphaXiv
description: Search and read arXiv papers through Feynman's alphaXiv integration.
section: Tools
order: 1
---

Feynman bundles an alphaXiv client (`@companion-ai/alpha-hub`) for searching arXiv papers, reading AI-generated paper reports or full text, asking questions about a paper, and reading a paper's linked code. alphaXiv covers arXiv papers; DOI-only papers are read through web fetch or Europe PMC instead.

## Authentication

Sign in during `feynman setup` or at any time:

```bash
feynman alpha login
```

On a machine without a browser (SSH, Docker, WSL without a display), `feynman alpha login` prints the sign-in URL. Open it in a browser on any machine and finish signing in. The browser then lands on a `http://127.0.0.1:9876/callback?code=...` page that fails to load; copy that full URL, paste it into the waiting terminal, and press Enter.

Check your authentication status:

```bash
feynman alpha status
```

## Agent tools

`alpha_search`, `alpha_get_paper`, `alpha_ask_paper`, and `alpha_read_code` are available only when you are signed in; without an account, Feynman searches papers through Semantic Scholar, OpenAlex, and the other literature databases instead. Start a new Feynman session after `feynman alpha login` to get them.

| Tool | Purpose |
| --- | --- |
| `alpha_search` | Search papers. Modes: `semantic` (default), `keyword`, `agentic`, `both`, `all` |
| `alpha_get_paper` | Fetch a paper's AI-generated report, or raw full text with `fullText`, plus any local annotation. `section` or `sections` return only abstract, introduction, methodology, experiments, results, discussion, limitations, or conclusion when detectable |
| `alpha_ask_paper` | Ask a targeted question about a paper's PDF |
| `alpha_read_code` | Read files from a paper's GitHub repository; `/` gives an overview |
| `alpha_annotate_paper` | Write or clear a local note on a paper |
| `alpha_list_annotations` | List local paper notes |

The lead agent calls these tools directly. The bundled researcher agent does not load them; it runs `feynman alpha ...` through its shell instead, after checking `feynman alpha status`.

## CLI

The same client is available from the terminal:

```bash
feynman alpha search "scaling laws"
feynman alpha get 2401.12345
feynman alpha ask 2401.12345 "What optimizer did they use?"
feynman alpha code https://github.com/org/repo src/model.py
```

## Storage

The alphaXiv client keeps its login state and local paper annotations under `~/.ahub`, separate from Feynman's `~/.feynman` directory. Remove `~/.ahub` to clear them during uninstall.

## Without AlphaXiv

Feynman works without an alphaXiv login. Paper discovery then goes through `feynman_science_database_search` (Semantic Scholar, OpenAlex, arXiv ID lookup, PubMed, Europe PMC, bioRxiv/medRxiv, Crossref) and web search, and full text comes from `fetch_content` on arXiv or open-access pages.

---

### Website Src Content Docs Tools Hugging Face (`website/src/content/docs/tools/hugging-face.md`)

---
title: Hugging Face Hub
description: Inspect Hugging Face datasets and repository files during research workflows.
section: Tools
order: 3
---

Feynman includes read-only Hugging Face Hub tools for grounding ML recipes and replication plans. They help the researcher verify whether a dataset or repo actually exposes the files, splits, schema, and card metadata needed for implementation.

These tools are grounded in Hugging Face's public [Hub API endpoint docs](https://huggingface.co/docs/hub/api). Authentication follows the `HF_TOKEN` environment variable documented by [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/environment_variables).

## Authentication

Public Hub resources work without configuration. For private or gated resources, set an access token in your shell before launching Feynman:

```bash
export HF_TOKEN=hf_...
```

If `HF_TOKEN` is unset, Feynman uses `HUGGINGFACE_HUB_TOKEN`. The token is sent with every Hub request.

## Tools

The lead agent and the researcher agent can call these tools:

| Tool | Purpose |
| --- | --- |
| `hf_dataset_info` | Inspect dataset metadata, tags, access status (private, gated, disabled), card data, `dataset_info` features and splits, downloads, likes, and sibling files |
| `hf_repo_files` | List files in a model, dataset, or Space repository (default 200 entries, max 1000) before reading anything large |
| `hf_repo_read_file` | Read small text files from Hub repos, such as `README.md`, configs, examples, and scripts |

`hf_repo_files` and `hf_repo_read_file` default to dataset repos; pass `repoType: "model"` or `"space"` for others. The file reader returns 20,000 characters by default (max 60,000) and is intended for text files only. It is not a weight downloader or dataset bulk reader. It refuses model weight files, archives, and dataset shards such as `.safetensors`, `.bin`, `.gguf`, `.parquet`, `.zip`, and `.tar` before download.

## Where it is used

The `/recipe` workflow uses `hf_dataset_info` to validate dataset availability and schema, and `hf_repo_files` and `hf_repo_read_file` to ground implementation details, before recommending a training recipe. The researcher agent can use the same tools in any workflow that delegates ML evidence gathering to it, such as `/replicate`.

For example, a recipe using a chat SFT dataset should verify that the dataset has a `messages`, `text`, or prompt/completion-style schema before calling it usable. If Feynman cannot check that schema, the final artifact should mark the dataset as `unverified` or `blocked`.

## Boundaries

These tools are read-only. They do not create repos, upload files, start jobs, or manage private data. If an experiment needs execution on Hugging Face infrastructure, Feynman records that as a follow-up implementation decision.

---

### Website Src Content Docs Tools Preview (`website/src/content/docs/tools/preview.md`)

---
title: Preview
description: Render research artifacts to HTML or PDF with pandoc.
section: Tools
order: 4
---

Feynman writes research artifacts as Markdown. To read one as a rendered document, convert it with [pandoc](https://pandoc.org/) from the shell. Feynman has no in-REPL preview command.

## Setup

Check for pandoc, or install it:

```bash
feynman setup preview
```

If pandoc is missing, this installs it with Homebrew on macOS, `winget` on Windows, or `apt-get` on Linux. If none of those is available or the install fails, install pandoc manually from [pandoc.org](https://pandoc.org/installing.html). `feynman doctor` and `feynman status` report whether pandoc is found.

## Rendering

```bash
pandoc outputs/scaling-laws.md -s -o outputs/scaling-laws.html
pandoc outputs/scaling-laws.md -o outputs/scaling-laws.pdf
```

Open the result in your browser or PDF viewer. PDF output needs a LaTeX engine such as TeX Live or MiKTeX in addition to pandoc.

Inside the REPL you can ask Feynman to run these commands for you.

---

### Website Src Content Docs Tools Web Search (`website/src/content/docs/tools/web-search.md`)

---
title: Web Search
description: Web search and page retrieval in Feynman through pi-web-access.
section: Tools
order: 2
---

Feynman's web research tools come from the bundled [`pi-web-access`](https://github.com/nicobailon/pi-web-access) package. The lead agent, the researcher, and the verifier use them to find and read documentation, blog posts, news, repositories, and open-access papers alongside Feynman's paper databases.

## Tools

| Tool | Purpose |
| --- | --- |
| `web_search` | Search with one query or a `queries` batch. Supports `numResults`, `recencyFilter` (`day`, `week`, `month`, `year`), `domainFilter` (prefix a domain with `-` to exclude it), `provider`, and `includeContent` to fetch page text for the results |
| `fetch_content` | Fetch one or more URLs as readable Markdown. Handles web pages, PDFs, GitHub repos, issues, and pull requests, images, and videos. `mode: "raw"` returns the exact text body; `mode: "answer"` with a `prompt` answers a question from the page |
| `get_search_content` | Read stored results from an earlier search or fetch by `responseId`, paged with `offset` and `limit`, or search them with `findText` |
| `source_check` | Gather passages for a claim into an evidence artifact for manual review; it does not decide support on its own |

Fetched page bodies are stored for one hour in `~/.feynman/agent/web-search-cache/` so `get_search_content` can page through them without re-fetching.

## Default behavior

With no key and no configuration, `web_search` works through Exa's hosted MCP endpoint. In `auto` mode it tries a configured SearXNG endpoint first; when the active model uses `openai-codex`, it then tries Codex-backed OpenAI search; otherwise it tries Exa before OpenAI, then any other provider you have configured. Browser-cookie access for Gemini Web is off unless you opt in with `allowBrowserCookies`.

## Configuration

Check the current search configuration:

```bash
feynman search status
```

Set a provider, optionally saving its API key:

```bash
feynman search set exa <api-key>
feynman search set perplexity <api-key>
feynman search set gemini <api-key>
feynman search set auto
```

`feynman search set` accepts every search provider pi-web-access supports, including `brave`, `tavily`, `kagi`, `serper`, `you`, `searxng` (pass its base URL instead of a key) and `duckduckgo` (no key); run `feynman search set` with no provider to list them all. It also sets the search `workflow` to `none` (raw results, no curator window) and turns browser-cookie access off. `feynman search clear` resets the provider to `auto` and keeps saved API keys.

For fallback routes, proxies, PDF extraction and other advanced settings, edit `~/.feynman/agent/web-search.json` directly. The [pi-web-access README](https://github.com/nicobailon/pi-web-access#configuration) documents every field.

## Commands

| Command | Description |
| --- | --- |
| `/search` | Browse stored web search results from the current session |
| `/websearch [queries]` | Open the search curator and run searches yourself |
| `/curator [on\|off]` | Toggle the search curator workflow |
| `/google-account` | Show the Google account used for Gemini Web |

To turn one of these commands off, set `commands.<name>.enabled` to `false` in `web-search.json` (keys: `websearch`, `curator`, `search`, `google-account`).

---

### Website Src Content Docs Workflows Audit (`website/src/content/docs/workflows/audit.md`)

---
title: Code Audit
description: Compare a paper's claims against its public codebase for reproducibility.
section: Workflows
order: 5
---

The code audit workflow compares a paper's claims against its public codebase and reports mismatches, omissions, and reproducibility risks.

## Usage

From the REPL:

```
/audit arxiv:2401.12345
```

```
/audit arxiv:2401.12345 https://github.com/org/repo
```

From the CLI:

```bash
feynman audit 2401.12345
```

Pass the paper, and the repository URL if you already know it.

## How it works

Feynman writes an audit plan (which paper, which repo, which claims to check) to `outputs/.plans/<slug>.md`, summarizes it, and continues without waiting for confirmation unless you asked to review the plan.

It then compares the paper's claimed methods, defaults, metrics, and data handling against the actual code. For non-trivial audits, the `researcher` agent gathers evidence and the `verifier` agent checks sources and adds inline citations.

## Output

One report at `outputs/<slug>-audit.md` that calls out:

- **Mismatches** -- where the code differs from what the paper describes
- **Missing code** -- described components with no implementation in the repo
- **Ambiguous defaults** -- settings the paper leaves unclear
- **Reproduction risks** -- anything likely to stop a faithful rerun

The report ends with a `Sources` section listing the paper and repository URLs.

## When to use it

Use `/audit` before building on a paper's results, before a replication, or to check your own paper against its code before release.

---

### Website Src Content Docs Workflows Autoresearch (`website/src/content/docs/workflows/autoresearch.md`)

---
title: Autoresearch
description: Start a bounded research experiment loop that iteratively optimizes against a benchmark.
section: Workflows
order: 10
---

The autoresearch workflow runs a bounded experiment loop: change something, run a benchmark, record the result, and keep or revert the change. It is for model, retrieval, prompt, architecture, or dataset experiments where the feedback signal is an explicit metric.

## Usage

From the REPL:

```
/autoresearch Optimize prompt engineering strategies for math reasoning on GSM8K
```

From the CLI:

```bash
feynman autoresearch "Optimize prompt engineering strategies for math reasoning on GSM8K"
```

Subcommands:

- `/autoresearch <text>` -- start or resume the loop
- `/autoresearch off` -- stop the loop and keep its data
- `/autoresearch clear` -- delete all loop state and start fresh

## How it works

1. **Gather** -- If `autoresearch.md` and `autoresearch.jsonl` already exist, Feynman asks whether to resume or start fresh. Otherwise it asks for what to optimize, the benchmark command, the metric name, unit, and direction, the files in scope, and a maximum iteration count (default 20).
2. **Environment** -- Feynman asks where to run: local, a new git branch, a virtual environment, Docker, Modal (if the `modal` CLI is set up), or RunPod (if `runpodctl` is installed and `RUNPOD_API_KEY` is set).
3. **Confirm** -- Feynman shows the target, benchmark, files, environment, and iteration limit, and does not start until you approve.
4. **Run** -- Feynman creates `autoresearch.md`, `autoresearch.jsonl`, and `autoresearch.sh`, runs the baseline, then loops: edit, run the benchmark, log the result and decision, compare against the baseline, and keep, revert, or record the failed hypothesis. The loop continues until you interrupt it or the iteration limit is reached.

After the baseline and at meaningful milestones, Feynman appends a short entry to `CHANGELOG.md` with what changed, the observed metric, what failed, and the next step.

## Output

The loop state lives in `autoresearch.md`, `autoresearch.jsonl`, and `autoresearch.sh` in the workspace. When reporting results, Feynman lists every configuration tried (kept, reverted, and failed) with its metric and describes how the result varies across settings and seeds, rather than claiming an effect from the single best run.

## When to use it

Use `/autoresearch` for hyperparameter searches, prompt-strategy evaluation, architecture or retrieval tuning, and dataset or benchmark ablations. To answer a specific question from sources, use `/deepresearch` instead.

---

### Website Src Content Docs Workflows Biomedical Literature Review (`website/src/content/docs/workflows/biomedical-literature-review.md`)

---
title: Biomedical Literature Review
description: Use Feynman for research-only biomedical literature reviews with evidence grading and privacy boundaries.
section: Workflows
order: 3
---

Biomedical literature reviews need stricter source handling than general technical surveys. Use this workflow for research synthesis, manuscript preparation, journal club preparation, protocol scoping, or background reading. Do not use it for patient-specific diagnosis, treatment selection, triage, or medical advice.

## Usage

From the REPL:

```
/lit PICO: adults with type 2 diabetes; intervention continuous glucose monitoring; comparator standard self-monitoring; outcomes HbA1c and hypoglycemia
```

From the CLI:

```bash
feynman lit "PICO: adults with type 2 diabetes; intervention continuous glucose monitoring; comparator standard self-monitoring; outcomes HbA1c and hypoglycemia"
```

This runs the standard [`/lit` workflow](/docs/workflows/literature-review). For biomedical papers, the `researcher` agent searches PubMed first and Europe PMC for open-access full-text sections.

## Frame the question

Start with a structured research question. For intervention questions, prefer PICO or PICOS:

- **Population** -- patient group, disease definition, setting, age range, severity, and key exclusions
- **Intervention or exposure** -- treatment, diagnostic test, risk factor, care model, or exposure
- **Comparator** -- placebo, usual care, standard test, alternative intervention, or no comparator
- **Outcomes** -- primary and secondary outcomes, safety outcomes, follow-up duration, and clinically meaningful thresholds
- **Study design** -- systematic reviews, randomized trials, cohort studies, case-control studies, diagnostic accuracy studies, qualitative studies, or guidelines

For non-intervention questions, state the study type directly. Examples: prognosis, diagnostic accuracy, adverse event signal, mechanism, epidemiology, implementation, or health economics.

## Source priority

Ask Feynman to separate evidence by study design instead of treating every source as equal. A typical biomedical review should distinguish:

- clinical practice guidelines and consensus statements
- systematic reviews and meta-analyses
- randomized controlled trials
- prospective and retrospective cohort studies
- case-control studies
- diagnostic accuracy studies
- case series and case reports
- preprints, conference abstracts, and non-peer-reviewed material
- mechanistic, animal, or in vitro studies

When evidence conflicts, keep the disagreement visible. Do not collapse guideline statements, trials, observational studies, and mechanistic papers into one undifferentiated conclusion.

## What to ask Feynman to report

For biomedical topics, include these instructions in the prompt when they matter:

- define inclusion and exclusion criteria before searching
- report search terms, time window, and source types
- separate clinical outcomes from surrogate outcomes
- identify effect sizes, confidence intervals, follow-up duration, and absolute risk when sources provide them
- distinguish efficacy, effectiveness, safety, feasibility, and cost
- flag single-study conclusions, small samples, unadjusted analyses, and indirect evidence
- identify whether claims come from peer-reviewed publications, preprints, registry records, guidelines, or secondary summaries
- report safety signals and adverse events when relevant
- state limitations and unresolved questions before giving a bottom-line synthesis
- state that the output is research synthesis, not medical advice

If Feynman cannot access a full text, trial registry, guideline, supplement, dataset, or source URL, the review should mark that check as blocked instead of inferring missing details.

## Privacy and safety boundaries

Do not paste protected health information, identifiable patient details, imaging identifiers, hospital records, insurance records, or private clinical notes into a Feynman workflow. Use de-identified, aggregate, or fictionalized research questions instead.

Feynman outputs should be treated as research drafts. A biomedical review can help organize the literature, but it does not replace a systematic review protocol, clinical guideline process, institutional review, statistical analysis plan, or licensed clinical judgment.

Avoid prompts that ask for direct patient advice. If a topic touches diagnosis, treatment, screening, or safety, phrase the task as literature synthesis:

```text
Summarize the research literature on...
Compare the evidence for...
Identify limitations and gaps in studies about...
Draft a background section for a research protocol on...
```

Do not phrase it as:

```text
What should this patient do?
Which treatment should I choose for this case?
Diagnose this patient.
```

---

### Website Src Content Docs Workflows Compare (`website/src/content/docs/workflows/compare.md`)

---
title: Source Comparison
description: Compare multiple sources and produce an agreement/disagreement matrix.
section: Workflows
order: 8
---

The source comparison workflow puts papers, articles, or documents side by side and produces a source-grounded matrix of where they agree, disagree, and remain uncertain.

## Usage

From the REPL:

```
/compare "sparse attention methods for long-context language models"
```

```
/compare arxiv:2401.12345 arxiv:2402.67890 arxiv:2403.11111
```

From the CLI:

```bash
feynman compare "topic or list of sources"
```

Give a topic and let Feynman find the sources, or list the specific papers and documents to compare.

## How it works

Feynman writes a comparison plan (sources, dimensions to evaluate, output structure) to `outputs/.plans/<slug>.md`, summarizes it, and continues without waiting for confirmation unless you asked to review the plan.

When the comparison set is broad, the `researcher` agent gathers source material. The `verifier` agent then checks sources and adds inline citations to the final matrix.

## Output

One comparison at `outputs/<slug>-comparison.md` containing:

- **Comparison matrix** -- source, key claim, evidence type, caveats, and confidence for each source
- **Agreement, disagreement, and uncertainty** -- kept clearly separate
- **Tables and diagrams** -- a Markdown table for quantitative metrics and a Mermaid diagram for method or architecture comparisons when the sources support the structure
- **Sources** -- direct URLs for every source used

## When to use it

Use `/compare` when results in the literature conflict, when choosing between competing approaches to the same problem, or when writing a related-work section that must characterize a debate accurately.

---

### Website Src Content Docs Workflows Deep Research (`website/src/content/docs/workflows/deep-research.md`)

---
title: Deep Research
description: Run a thorough, multi-agent investigation that produces a cited research brief.
section: Workflows
order: 1
---

Deep research investigates a topic and produces a research brief with inline citations and a provenance record. Broad topics use parallel researcher agents; narrow explainers stay with the lead agent and direct searches.

## Usage

From the REPL:

```
/deepresearch What are the current approaches to mechanistic interpretability in LLMs?
```

From the CLI:

```bash
feynman deepresearch "What are the current approaches to mechanistic interpretability in LLMs?"
```

`/deepresearch` writes its plan, summarizes it, and continues. To review the plan before any searching, say so in the request (for example `/deepresearch <topic>, show me the plan first`).

## How it works

1. **Plan** -- Feynman writes `outputs/.plans/<slug>.md` with key questions, evidence needed, a scale decision, a task ledger, a verification log, and a decision log, then continues (or waits for you if you asked to review the plan).
2. **Scale** -- Narrow questions and "what is X" explainers use direct search by the lead agent (at least three distinct queries). Comparisons of 2-3 items use 2 `researcher` agents, broad surveys 3-4, and complex multi-domain topics 4-6.
3. **Gather** -- Researchers run in parallel, each writing its findings to a file. Feynman prefers abstracts, HTML pages, official docs, and paper metadata, and reads full text only for the few papers the conclusions depend on. Failed or missing research is recorded in the plan rather than assumed to exist.
4. **Draft** -- The lead agent writes the draft itself and removes or downgrades any claim that does not map to a source, note, or artifact.
5. **Cite** -- When researchers were used, the `verifier` agent adds inline citations and checks every URL. In direct-search runs, the lead agent does this itself.
6. **Review** -- When researchers were used, the `reviewer` agent checks the cited draft for unsupported claims, logical gaps, single-source critical claims, and overstated confidence; FATAL issues are fixed and re-reviewed before delivery. In direct-search runs, the lead agent writes the review itself.
7. **Deliver** -- The final brief and its provenance sidecar are written, and Feynman checks that every required file exists before responding.

If a tool or source fails, the run continues in degraded mode and still writes a final output marked `Verification: BLOCKED` or `PASS WITH NOTES`.

## Output

| File | Contents |
| --- | --- |
| `outputs/.plans/<slug>.md` | Plan, task ledger, verification log |
| `outputs/.drafts/<slug>-draft.md` | Uncited draft |
| `outputs/.drafts/<slug>-cited.md` | Draft with inline citations and Sources |
| `outputs/.drafts/<slug>-revised.md` | Written only when review fixes need a full rewrite |
| `outputs/<slug>.md` (or `papers/<slug>.md` for paper-style drafts) | Final brief |
| `<slug>.provenance.md` next to the final brief | Date, sources consulted/accepted/rejected, verification status, research files |

The brief contains an executive summary, findings organized by question or theme, evidence-backed caveats and disagreements, open questions, and a Sources section.

## Customization

Steer the run in your prompt. Narrow topics produce focused briefs; broad topics produce survey-style overviews. Constraints such as "focus on papers from 2025" or "only consider empirical results" narrow the search. Ask for comprehensive coverage if you want researcher agents on a topic that would otherwise be treated as a simple explainer.

---

### Website Src Content Docs Workflows Draft (`website/src/content/docs/workflows/draft.md`)

---
title: Draft Writing
description: Generate a paper-style draft from research findings and session context.
section: Workflows
order: 9
---

The draft writing workflow turns research findings into a paper-style draft with sections, explicit claims, and equations where they help. It is a natural follow-up to `/deepresearch` or `/lit`.

## Usage

From the REPL:

```
/draft A survey of retrieval-augmented generation techniques
```

From the CLI:

```bash
feynman draft "A survey of retrieval-augmented generation techniques"
```

## How it works

Feynman writes an outline to `outputs/.plans/<slug>.md` with the proposed title, sections, key claims, source material, and a verification log for critical claims, figures, and calculations. It summarizes the outline and continues without waiting for confirmation unless you asked to review it.

When the draft can be built from notes already collected, the `writer` agent produces it and the `verifier` agent then adds inline citations and checks sources. Before delivery, Feynman sweeps the draft for claims stronger than their support, marks tentative results as tentative, and removes unsupported numbers.

Drafts follow Feynman's provenance rules: missing results, figures, tables, or benchmarks become labeled placeholders or proposed experiments, not plausible-looking data. Plots use only source-backed data, and the plotting script is saved next to the draft.

## Output

One draft at `papers/<slug>.md` in Markdown, with LaTeX for equations, Markdown tables for quantitative comparisons, and Mermaid for architectures and pipelines. It includes at minimum:

- Title and abstract
- Problem statement
- Related work
- Method or synthesis
- Evidence or experiments
- Limitations
- Conclusion
- A `Sources` appendix with direct URLs for all primary references

## Iteration

Ask Feynman to revise specific sections, add detail, or restructure the argument. To render the draft as HTML or PDF, see [Preview](/docs/tools/preview).

---

### Website Src Content Docs Workflows Literature Review (`website/src/content/docs/workflows/literature-review.md`)

---
title: Literature Review
description: Run a structured literature review with consensus mapping, gap analysis, and lab/PI corpus mode.
section: Workflows
order: 2
---

The literature review workflow maps a field: what researchers agree on, where they disagree, and what remains open. When the input names a lab, PI, author, or lab website, `/lit` runs as a publication-corpus review instead: it resolves the identity, collects reachable publications, and maps research trajectories across them.

## Usage

From the REPL:

```
/lit Scaling laws for language model performance
```

From the CLI:

```bash
feynman lit "Scaling laws for language model performance"
feynman lit "Anthropic interpretability team"
```

## How it works

1. **Plan** -- Feynman writes the scope (key questions, source types, time period, expected sections, task ledger, verification log) to `outputs/.plans/<slug>.md`, summarizes it, and continues without waiting for confirmation unless you asked to review the plan.
2. **Gather** -- Wide sweeps use the `researcher` agent, which writes `<slug>-research-*.md` files; narrow topics are searched directly. For a lab or author, the lead agent first resolves the identity and writes a publication log to `notes/<slug>-publications.md` with titles, years, venues, URLs or DOIs, and gaps.
3. **Synthesize** -- Findings are separated into consensus, disagreements, and open questions, with suggested next experiments or reading when useful. For a lab or author, Feynman also identifies 3-5 research trajectories and the 3-5 papers that most changed the corpus direction, ranked by contrastive originality, methodology strength, and relationship to prior art rather than author prestige.
4. **Cite** -- The `verifier` agent adds inline citations and checks every source URL.
5. **Verify** -- The `reviewer` agent checks the cited draft for unsupported claims, logical gaps, and single-source critical findings. FATAL issues are fixed and re-checked; MAJOR issues go into Open Questions.
6. **Deliver** -- Feynman writes the review and its provenance record and checks that both exist on disk.

## Output

- `outputs/<slug>.md` -- the literature review, with Mermaid diagrams for taxonomies, method pipelines, or trajectory maps when the sources support them
- `outputs/<slug>.provenance.md` -- date, sources consulted, accepted, and rejected, verification status, and intermediate research files; for lab or author reviews, also the publication log path and unresolved corpus gaps

## When to use it

Use `/lit` at the start of a project to see what has already been done, when preparing a related-work section, or to understand a lab's or author's body of work.

For biomedical and clinical topics, see [Biomedical Literature Review](/docs/workflows/biomedical-literature-review) for research-only framing, evidence-type separation, and privacy boundaries.

---

### Website Src Content Docs Workflows Recipe (`website/src/content/docs/workflows/recipe.md`)

---
title: ML Training Recipe
description: Find ranked, implementable ML training recipes backed by papers, datasets, docs, and code.
section: Workflows
order: 7
---

The recipe workflow turns a training or fine-tuning goal into a ranked set of implementable recipes. It is designed for ML engineering questions where the useful answer is not just "what papers exist?" but "which dataset, method, hyperparameters, code path, and checks should I try first?"

The recipe-shaped output is borrowed from Hugging Face's [`ml-intern`](https://github.com/huggingface/ml-intern).

## Usage

From the REPL:

```
/recipe "fine-tune a small model for math reasoning"
```

From the CLI:

```bash
feynman recipe "fine-tune a small model for math reasoning"
```

You can use `/recipe` for tasks such as choosing an SFT dataset, reproducing a benchmark setup, selecting a practical training method, or turning a paper into an implementation plan.

## How it works

The workflow writes a plan to `outputs/.plans/<slug>-recipe.md` and continues automatically. Broad tasks use the `researcher` agent for the paper and code sweep; narrow tasks are researched directly. Research starts from evidence of results, not from example scripts alone.

For each candidate, Feynman links the reported result to the recipe that produced it: dataset, split/schema, method, hyperparameters, compute assumptions, benchmark, and implementation code. Datasets are checked for availability, splits, and format; anything not directly checked is marked `unverified`. For the top-ranked recipe, key source URLs and dataset and code availability are verified before delivery, or labeled `blocked` or `unverified`.

## Hugging Face grounding

When a candidate uses a Hugging Face dataset or repository, Feynman inspects it with read-only Hub tools:

- `hf_dataset_info` checks dataset metadata, tags, access status, card data, features, and splits.
- `hf_repo_files` lists files in model, dataset, and Space repos.
- `hf_repo_read_file` reads small text files such as dataset cards, configs, examples, and scripts.

These tools use public Hub endpoints by default and use `HF_TOKEN` or `HUGGINGFACE_HUB_TOKEN` when present for private or gated resources.

## Output

Research notes go to `outputs/.drafts/<slug>-recipe-research.md`. The final brief is `outputs/<slug>-recipe.md`, with a provenance sidecar at `outputs/<slug>-recipe.provenance.md`.

The brief includes:

- **Recommendation** -- The one recipe to try first and why
- **Ranked recipe table** -- Candidate recipes with paper/source, result, dataset, method, hyperparameters, compute, code/docs, and verification status
- **Dataset notes** -- Schema, splits, size, license/access constraints, and unchecked gaps
- **Implementation plan** -- Minimal steps to run the top recipe
- **Known gaps** -- Missing code, inaccessible data, unclear hyperparameters, benchmark mismatch, or unverified assumptions
- **Sources** -- URLs for every paper, repo, dataset, and doc page used

Feynman does not call a recipe state of the art, replicated, or production-ready unless the checks support it.

---

### Website Src Content Docs Workflows Replication (`website/src/content/docs/workflows/replication.md`)

---
title: Replication
description: Plan a replication of a paper's experiments and claims; execute only after choosing an environment.
section: Workflows
order: 6
---

The replication workflow builds a source-backed plan for reproducing a paper, benchmark result, or specific claim. It executes only after you choose an environment, and it does not call a result replicated unless the planned checks pass.

## Usage

From the REPL:

```
/replicate arxiv:2401.12345
```

```
/replicate "The claim that sparse attention achieves 95% of dense attention quality at 60% compute"
```

From the CLI:

```bash
feynman replicate "paper or claim"
```

## How it works

1. **Extract** -- The `researcher` agent pulls implementation details from the paper and any linked code. If `CHANGELOG.md` exists, Feynman reads its recent entries first.
2. **Recipe pass** -- For ML training, fine-tuning, benchmark, or dataset-heavy targets, each claimed result is linked to the exact dataset, method, hyperparameters, compute assumptions, metric, and code path that produced it. Dataset availability and schema are checked when possible (see [Hugging Face Hub](/docs/tools/hugging-face)); unchecked details are marked `unverified`.
3. **Plan** -- Feynman lists the code, datasets, metrics, and environment needed, separates what is verified, inferred, and missing, and names the checks that will decide whether the replication succeeded.
4. **Environment** -- Feynman asks where to execute: local, a virtual environment, Docker, Modal (if the `modal` CLI is set up), RunPod (if `runpodctl` is installed and `RUNPOD_API_KEY` is set), or plan only. Nothing is installed or run before you choose.
5. **Execute** -- In the chosen environment, Feynman implements and runs the steps and saves notes, scripts, raw outputs, and results to disk.
6. **Log** -- For multi-step or resumable work, Feynman appends entries to `CHANGELOG.md` after progress, failed attempts, and verification outcomes.
7. **Report** -- The result ends with a `Sources` section listing paper, dataset, documentation, and repository URLs.

## When to use it

Use `/replicate` before building on a result you have not seen reproduced, or to test one specific claim. Choose "plan only" to get the replication plan without running anything.

---

### Website Src Content Docs Workflows Review (`website/src/content/docs/workflows/review.md`)

---
title: Research Review
description: Run an internal research critique with severity-graded feedback.
section: Workflows
order: 4
---

The review workflow runs an internal research critique of a paper, draft, or other research artifact. It is not an external peer review or a publication decision; it finds methodology, evidence, clarity, and reproducibility issues before you trust or revise the work.

## Usage

From the REPL:

```
/review arxiv:2401.12345
```

```
/review ~/papers/my-draft.pdf
```

From the CLI:

```bash
feynman review arxiv:2401.12345
feynman review my-draft.md
```

Pass an arXiv ID, a URL, or a local file path.

## How it works

Feynman writes a plan to `outputs/.plans/<slug>-review-plan.md` with the artifact, the review criteria (novelty, empirical rigor, baselines, reproducibility, claims validity, figures and tables, metrics, related work, writing quality), and the checks needed. It then continues without waiting for confirmation unless you asked to review the plan first.

Feynman reads local files directly, parses PDFs with the available document tools, and fetches arXiv IDs and URLs. It inspects linked code, datasets, supplements, or citations when they are reachable and matter to the review. Evidence notes go to `outputs/.drafts/<slug>-review-evidence.md` before the final review is written.

For large artifacts, Feynman can delegate to the `researcher` and `reviewer` agents; smaller artifacts are reviewed directly.

If a PDF cannot be parsed or a source is unavailable, Feynman still writes the review, marks the affected sections `Verification: BLOCKED`, and keeps blocked checks separate from actual weaknesses in the work.

## Output

One review at `outputs/<slug>-review.md` with:

- **Summary Assessment**
- **Strengths**
- **Critical Issues**
- **Major Issues**
- **Minor Issues**
- **Reproducibility and Verification**
- **Inline Annotations** -- tied to sections, claims, figures, or tables where possible
- **Recommendation**
- **Sources**

## Customization

Focus the review in your prompt, for example "focus on the statistical methodology" or "check the claims in Section 4 against the experimental results."

---

--- METRICS ---
- Files Extracted: 29
- Estimated Token Budget: ~61687 tokens
- Canonical Reference: https://codewiki.google/github.com/getcompanion-ai/feynman