# Release Notes

This file is the public release history for Hypatia. Keep entries user-facing: what changed, why it matters, and anything users should do after upgrading.

GitHub release notes are generated from the matching `## vX.Y.Z` section in this file.

## v0.1.3 - 2026-10-16

- **Reliable delegated research**: update `pi-subagents` to 0.78.0, which restores background scout startup on Pi 1.2 after 0.77.0 required a `chord` package that host removed.
- **Current Pi and research packages**: align Pi AI, CLI, and TUI at 1.3.0; update `pi-web-access` to 0.41.0 and Alpha Hub to 0.1.7.
- **Pi 1.3 TUI update**: keep Hypatia on matching core packages and the published theme schema. `/sources` and `/idea` lists navigate with the mouse wheel, and the Idea Forge selector fills the terminal width to keep transcript text from showing through its edges.
- **Searchable `/outputs` browser**: browse reports, provenance, drafts, and other artifacts in one responsive TUI panel. Search by title or path, preview bounded text excerpts, switch to a matching report/provenance file, open the full reader, copy paths, or send a file path to chat.
- **Readable chat equations**: display equations use Pi's native Unicode LaTeX layout with upright text styling. This changes only the chat presentation; saved transcript text and exports are unchanged.
- **Project research wiki**: initialize a workspace-local Markdown knowledge base, including empty source/concept folders; ingest sources into reviewable proposals, query linked synthesis, and lint for broken links or missing evidence. Canonical wiki pages change only after explicit approval.
- **Wiki context across research workflows**: `/lit`, `/deepresearch`, `/compare`, and `/replicate` consult relevant indexed pages read-only. Leads pass selected page paths, claim status, and original source URLs to evidence-scout briefs; scouts verify the originals and record pages consulted. `/idea` freezes up to 12 selected concept/source pages and their hashes in its approved knowledge bundle. Pending proposals are excluded.
- **Expanded public AlphaXiv research**: semantic/keyword search now supports publication-date filters, ranking preferences, and result limits; fast title search and linked GitHub implementation lookup work without login. Public paper reading remains keyless; agentic search, PDF Q&A, and repository file reading still use optional account-backed tools.
- **Kev-backed paper advisory**: Kev replaces Laya as the optional local scorer and uses Kev's TypeSafe System One API. The advisory remains explicit, opt-in, and source-order preserving; use `HYPATIA_KEV_*` settings.
- **Transparent Kev advisory ranks**: each suggested result reports its source rank, suggested rank, signed displacement, and score; the primary source order is unchanged.

## v0.1.2 - 2026-10-13

- **A clearer research chat**: the Hypatia header now keeps the H mark as its sole accent and labels duplicate workspace names and UUID sessions compactly. Fullscreen transcripts keep the relevant prompt in view while scrolling, with Pi's built-in jump-to-latest control. Live subagent activity can be collapsed, and `/lit` and `/deepresearch` show observed workflow stages.
- **Source-grounded diagrams and summaries**: a built-in `research-diagrams` skill guides compact Mermaid diagrams for terminal chat and evidence-aware artifacts. `/compact` and optional `/tree` summaries retain observed sources, evidence states, unresolved questions, and next steps.
- **Safer literature guidance**: optional Laya scoring is explicit and advisory; it preserves the provider's source order. The 30-query SciFact development evaluation underperformed BM25 (0.5777 vs. 0.8095 nDCG@10), so automatic reranking remains disabled.
- **More reliable setup and model recovery**: model setup cancellation exits cleanly; OAuth callbacks without a code and common provider failures now include recovery guidance. Copilot model recommendations prefer available Claude Opus, then Sonnet, then GPT. PubMed keeps affiliations for collective authors.
- **Installer and workflow improvements**: `hpt` is available as a short CLI alias, with rollback-safe npm and standalone installers. Updated `pi-subagents` and `pi-btw` improve long reports and side-chat command handling; research agents can fall back to `python3` when `python` is unavailable.

## v0.1.1 - 2026-10-11

- **Optional local Laya paper reranking**: opt into bounded, loopback-only relevance reranking for topical literature searches; exact lookups retain source order, and service failures preserve the original results. Laya remains off by default.
- **Laya evaluation tooling**: compare against named retrieval baselines and generate deterministic Hypatia or SciFact development candidate pools. The three-query SciFact smoke regressed against BM25, so it does not support enabling reranking by default.
- **Quick research command panel and searchable `/help`**: the welcome logo gives way to research commands after first interaction; `/help` filters grouped commands and prefills the composer without sending.
- **Scrollable citation browser**: `/sources` presents citations from the latest answer in a bounded TUI panel with filtering, open, and copy controls; verification appears only when explicitly stated.
- **Provider and scholarly-source reliability**: legacy Azure settings migrate safely to Pi's `azure` provider ID; PubMed preserves inline text and affiliations; OpenAlex lookup errors point to matching search tools; rejected OAuth grants include recovery guidance. Updated bundled `pi-subagents` and `pi-web-access` packages.

## v0.1.0 - 2026-10-10

- **Initial public release**: install the open-source research agent from npm or use the standalone macOS, Linux, and Windows bundles. The CLI is built on stock Pi and includes traceable research workflows and provenance artifacts.

- **Transcript search, source browser, and compact chat layout**: long sessions surface Pi's transcript-search shortcut; `/sources` lists citations from the latest answer with explicitly stated verification status and lets you open or copy URLs. Short fullscreen terminals use a compact header and hide welcome art/tips first.
- **Compact research tool cards**: Code-search results show match counts, the top repository path and snippet; Hugging Face results summarize dataset schema/access, file lists, or file reads. Press `Ctrl+O` to expand the original tool result.
- **Updated the Pi runtime to 1.1.0**: Pi AI, CLI, and TUI packages now use the matching release, and `pi-btw` is upgraded to a Pi 1.x-compatible version. The MCP SDK is pinned to 1.32.1; the production dependency audit now reports no advisories. Hypatia keeps its fullscreen chat layout through its explicit TUI setting.
- **Tool timing and optional Codemode**: compact paper-search and paper-read results show Pi's recorded duration when available, while Pi's standard render shell applies the configured output padding. `--codemode` adds Pi Codemode for one launch; users can also enable it persistently through `defaultTools` in their agent settings.
- **Native ideas and experiment setup in chat**: `/idea <goal>` or `/experiments generate <goal>` opens an opaque model selector docked above the TUI input, for one current model or three distinct available models. A scrollable contract review organizes scope, panel and limits and estimates up to three requests per model; caps below the full-panel estimate are rejected before approval. Defaults are 12 API attempts, 900 seconds, 5000 output tokens per request and 90 seconds per request unless the user asks otherwise. Approving the generation contract starts the bounded run in the same tool flow; benchmark execution still needs a separate contract approval. Built-in Idea Forge guidance now includes information retrieval/ranking, RAG evaluation, agent evaluation and statistical design, alongside QML, ML, LLM and general research. The bundled `research-ideation` skill supports broad, chat-based exploration of 3–5 speculative directions without starting separate Idea Forge panel calls. No AutoResearch clone or Python backend is needed for new idea runs. `/experiments create <goal>` and proposal selection prepare contracts through chat, with inferred defaults, grouped prerequisite questions and one final approval per generation/benchmark. Request caps, caches, provenance and review gates persist; old Python-backed runs remain compatible.

- **Legacy Idea Forge provider configuration**: optional `providerConfig` selects a private JSON for generation and persists across worker launches/resume. Relative `AUTORESEARCH_CONFIG` paths resolve against the backend clone rather than the experiment workspace.
- **Experiment environment fingerprints**: new `/autoresearch` contracts bind the environment label, host platform/architecture/Node runtime, benchmark executable and hashes of declared frozen inputs. Include dependency lockfiles in `inputFiles`; inherited environment variables and installed-package inventories are deliberately not captured.
- **Lineage-linked `/autoresearch` experiment trees**: compare sibling candidates in detached Git worktrees seeded from a parent's verified best snapshot. Tree mode requires a clean Git repository root, gives each node its own existing version-1 contract/receipts/reviews, and enforces shared trial/time/parallel-run budgets with recoverable reservations. `/experiments tree promote` records a reviewed winner without merging or changing the checkout; tree close writes aggregate report and provenance.

- **Legacy Python-backed Idea Forge generation**: `/experiments generate` combines one signal and one knowledge direction with an explicitly approved 3–6-model backend panel. API attempt/time/token caps, frozen config/source/knowledge identity, response checkpoints and pause/resume persist. Generated proposals can prepare an experiment in chat with verified artifact provenance; proposal/model-review validity remains unverified. Proposal preview is readable and scrollable; View status shows request/cache/receipt integrity. Uses a local AutoResearch Python backend with its own credentials; collectors/publishers are not invoked.

- **Experiment setup and independent reviews**: `/experiments create <goal>` prepares benchmark scope, metric, seeds, environment and budgets in chat, with one contract approval. `create-json` preserves JSON import. New contracts automatically run a fresh read-only critic before benchmarks and an auditor before closure. Review verdicts bind exact evidence hashes; findings, model identity, usage and capped attempts persist across sessions. Blocked, malformed or stale reviews cannot pass a required gate.

- **Persistent bounded experiments**: `/autoresearch` uses approved benchmark contracts, cached baselines, observed metric receipts, scoped snapshots and durable pause/resume budgets. `/experiments` manages state and imports AutoResearch idea/provenance snapshots; final report/provenance are readable in `/outputs`, and the footer follows experiment state. Execution initially supports macOS/Linux; Windows supports management/import. New experiment contracts require independent review gates; optional bounded Idea Forge generation is available through the management menu. Source updates need a build and Hypatia restart.

- **Codex-style exit summary**: quitting an interactive chat prints the working directory, git branch (with `*` when dirty), session elapsed time, and a `hypatia --session <id>` reconnect command (`hypatia -c` when the session id cannot be resolved). It appears only on clean interactive exits, never in RPC/JSON/one-shot runs or for `--no-session`.
- **Centered new-session logo**: an empty fullscreen chat renders the supplied Hypatia PNG directly when the terminal supports inline images, and uses an automatic truecolor rendition otherwise. Slash commands and keyboard shortcuts dismiss it immediately; it adds no transcript or model content. Regular mode uses a compact scale.
- **Inline image attachments in chat**: pasting a clipboard image shows an accent-blue `[Image #1]` marker in the composer instead of a temporary file path. On send, the image is attached as image content for the model.
- **Coordinated composer borders**: when Pi shows an active `Working` status in the upper composer border, the lower border now uses the same Pi border color; the idle composer keeps its muted lower border.
- **Collapsible warning inbox**: TUI warning notifications are collected in a footer count; press `F2` and select one to read its full text, then `d` to dismiss it. When a user skill shadows a bundled Hypatia skill, the already-skipped bundle copy is filtered before Pi loads resources, so the winning user skill remains active without a collision diagnostic. Long Hindsight setup notices are included; other Pi diagnostics, errors, and info notifications retain their existing display.
- **Grouped activity and turn receipts**: the chat shows a live `Exploring` line with operation groups, safe file basenames, and observed issue counts. Each settled turn leaves a transcript receipt with outcome, elapsed time, local finish time, and grouped operations. `Ctrl+O` expands operations and available tool error details.
- **Accurate TUI mode notices**: changing TUI mode in `/settings` reports that it was applied immediately; a saved mode that differs from the active layout after settings reload says the current session needs a restart.
- **Contextual English chat tips**: tips appear only while the editor is empty and the agent, tools, subagents, and blocking input are idle. Successful visible tool results suggest the configured expand shortcut; new or updated reports in `outputs/` or `papers/` suggest `/outputs`. Report detection reads file metadata and excludes hidden files, drafts, provenance, and links; it makes no verification claim. Tips stay outside the input border and add no model context.
- **Shift+Enter for multiline input**: new installations use Enter to send, Shift+Enter or Ctrl+J for a newline, and Alt+Enter to queue a follow-up. Existing user keybindings are retained on upgrade; edit `~/.hypatia/agent/keybindings.json` and reload to apply your preferred mapping.
- **Clearer chat typography and composer**: You/Hypatia labels distinguish prompts from answers, with a small accent marker and open answer layout. The thin composer border carries a `› Message` label and an empty-state research placeholder. Contextual tips occupy the chat area above the composer when idle and empty. They are UI-only; the composer border stays free of shortcut text. Multiline scrolling, autocomplete, shell mode, and Pi's working indicator are retained. Reload an idle chat to apply; existing custom editors take precedence.
- **Citation-aware answer rendering**: arXiv, OpenReview, and DOI URLs use compact labels, clickable through OSC 8 where supported. Bibliography numbers and paper titles stand out while venue/year details recede; deeper Markdown headings no longer expose `###` prefixes; explicit verification and completeness notes use amber callouts. This changes only the TUI presentation, not transcript text, model context, or exports.
- **Read outputs directly in chat**: `/outputs` groups reports, provenance, drafts, and auxiliary artifacts, with newest files first. Markdown/text readers support scrolling and literal search; `p` switches to the paired sidecar/report and `c` copies the current absolute path. Viewer actions preserve the composer; an explicit Read in chat action prefills it for review. Large files/PDFs retain copy/read actions; local previews are capped at 2 MiB.
- **Compare completed-run provenance in chat**: `/compare-provenance` shows differences in recorded dates, rounds, source coverage, and verification status. It compares sidecar metadata without judging which run is better.
- **Renamed bundled research agents**: the five roles are now `evidence-scout`, `scribe`, `auditor`, `critic`, and `reviser`. Existing model-route and Pi override keys migrate to the new names. The old `writer`, `verifier`, and `patcher` selectors remain aliases; use the new names for `researcher` and `reviewer`, which Pi reserves for built-in agents. Startup settings normalization is serialized; command-specific model and service-tier writes remain outside this lock. A timeout names the lock file, which can be removed only after confirming no Hypatia startup is active.

- **Two-row chat footer**: model, thinking level, context, cumulative token usage, and recorded cost share one row; live activity or idle research shortcuts use the next. Narrow windows shorten labels and preserve leading errors/activity. The header keeps Hypatia, project, and session. Usage includes cache warming, tool usage, and compaction summaries; missing or partial values are marked rather than filled in.
- **Live research activity and compact search results**: the footer now follows the main agent, parallel tools, blocking input, and subagents with elapsed time. Research shortcuts return after the chat turn actually settles, including across retries and continuations. Paper-search summaries show delivered sources, returned counts, fallback reasons, notes, and errors; `Ctrl+O` expands the full result.
- **Graphite colors**: the bundled `hypatia` theme and CLI output now use soft white text, pale blue accents, and charcoal panels, with green success, yellow warnings, and red errors. Run `/reload` in an open chat to refresh the bundled theme. Set your terminal background to `#151515` and foreground to `#E6E6E6` for the full palette.

- **Renamed to Hypatia** (`@tquang122/hypatia`): binary `hypatia`, home `~/.hypatia`, env prefix `HYPATIA_*`.
- **Telemetry is off by default.** Nothing is sent unless you opt in with `HYPATIA_TELEMETRY=1` and your own `HYPATIA_POSTHOG_KEY`.
- **New scholarly sources**: CORE open-access full text (`CORE_API_KEY` unlocks downloads), DOAB open-access books, and OA recovery (`source: oa`) finding a legal open-access copy via Unpaywall, Europe PMC, then CORE.
- **Resilient paper search** (ported from upstream v0.5.16–v0.5.19): Semantic Scholar ↔ OpenAlex fallback on rate limits, alphaXiv tools fall back to OpenAlex/arXiv, `"null"` optional fields accepted, rejected Semantic Scholar keys named.
- **Per-role subagent model and thinking controls**: `/model-routes` in chat or `hypatia model routes` in a shell configures each role's primary model, ordered launch fallbacks, and thinking level; inheriting the agent/Pi default remains available. Use `--json` for non-interactive model-route inspection. Research evals and provenance capture actual model and reported token/cost usage by role.
- **Fullscreen research chat by default**: the transcript scrolls while the composer and status stay in view. Idle research shortcuts below the composer yield to live subagent status during delegated work. Switch back with `/settings` or `tuiMode: "regular"` in `~/.hypatia/agent/settings.json` (Pi currently labels fullscreen mode experimental).
- **Benchmark score lanes**: `evals/score-lane.mjs` aggregates official ScholarQA-CS2/AstaBench, DeepResearch FACT, and SciCoQA results by model and role without bundling gated benchmark data or inventing judge scores.
- **Subagent outputs land in the workspace** with every file under `outputs/.drafts/`; workflow scripts run from `outputs/.plans/<slug>-workflow.js`.
- **`.docx` drafts readable without LibreOffice** (paragraph text fallback); `hypatia packages remove <preset>` removes optional packages.
- **Pi 0.99.2**, pi-subagents 0.74.0, pi-btw 0.7.0, pi-web-access 0.35.0; the temporary undici pin is gone.