Husearch — Feature Summary

Last verified against the codebase: 2026-06-11. This document describes what is actually implemented and live, including operational limits and cost drivers, so it can be used as ground truth for planning, financial modelling, and strategic decisions.

What It Does

“Replit for humanities research” — an all-in-one workspace where researchers investigate, write, annotate, cite, and export without leaving the platform. Submit a research question, and four specialist AI agents investigate it in parallel. A synthesizer merges their findings into structured outputs — briefs, bibliographies, notes, summaries, and full agent transcripts. All research is stored, searchable, and organized by project and chapter. The platform extends beyond research into writing, annotation, citation management, data visualization, collaboration, and manuscript export.

Research Engine

Four Claude-powered agents run concurrently on every query:

• Data Agent — finds statistics, empirical data, and quantitative studies in whatever field the query belongs to (live data via FRED, World Bank, IMF, OECD, Eurostat, BIS, DBnomics, UN Comtrade; quantitative studies via academic search), calling only the sources that fit
• Theory Agent — identifies relevant theoretical frameworks (academic search via Semantic Scholar, OpenAlex, CrossRef, arXiv, CORE)
• History Agent — surfaces historical case studies, precedents, and primary sources (Internet Archive, DPLA, Europeana, Library of Congress)
• Critic Agent — generates counter-arguments, flags methodological weaknesses, and presents opposing viewpoints

An orchestrator tailors sub-prompts per agent, and a synthesizer resolves contradictions across all four outputs into a unified research brief. Follow-up queries can build on prior sessions for iterative investigation: “Follow up” on a finished session (in the Library reader or on a result in the research feed) files the next run with it as its parent.

Limits: max 2 running research sessions per user across all server instances (MAX_CONCURRENT_RESEARCH_PER_USER) and 3 per instance (MAX_CONCURRENT_RESEARCH); per-agent 5-minute hard timeout and 90-second idle timeout; up to 5 tool-calling rounds per agent; max query length 2,000 characters (the pipeline limits are defaults of RESEARCH_* variables, ADR-0046). All external API calls (Claude, CrossRef, FRED, etc.) have retry logic with backoff and human-readable error messages; data providers sit behind a circuit breaker (opens after 3 consecutive upstream failures — 5xx, 429, timeout — for 10 minutes).

Per-Project Research Focus

Each project can configure a “Research Focus” (discipline, specialization, key theories, regions, time period, key thinkers, critical lens, output emphasis, custom instructions). The orchestrator and all five agent prompts are customized at runtime from this config; projects without one use discipline-neutral base prompts.

Source Restriction Modes

Researchers control what the agents draw from:

• Broad Research (broad, default) — agents use Claude’s full training knowledge plus live tools
• Library + AI (hybrid) — agents prefer the user’s uploaded sources, tagging claims [LIBRARY] or [AI-KNOWLEDGE]
• My Library Only (library_only) — agents cite exclusively from uploaded PDFs and annotations

The marker vocabulary (provenance tags, [HIGH]/[MEDIUM]/[LOW] confidence tags, claim/evidence and contradiction/convergence markers, and the citation keys [REF: R1] / [CITE: R1] that tie the brief’s citations to bibliography entries) has a single owner in shared/research-markers.js, used by both server and client.

Citation Verification

After synthesis, citations are automatically verified against the CrossRef API; when CrossRef has no match or is down, OpenAlex and then Semantic Scholar are asked before a citation is marked unverified. Each bibliography entry gets a badge, joined to it by its citation key: Verified (DOI resolves, metadata matches), Partial match, Unverified (flagged for manual review), Pending (verification incomplete, e.g., CrossRef temporarily down), or Retracted (the publisher or the Retraction Watch database, via CrossRef, or OpenAlex, records a retraction). Web pages the agents cited through web search are listed in the bibliography and checked for reachability (Link reachable / Link unreachable). Researchers can manually override unverified and unreachable entries. Lookups are cached in a PostgreSQL table. See ADR-0045.

Evidence Chains

The synthesizer tags each claim with its supporting evidence and source agent. A claim-evidence parser extracts these into structured records, so any synthesized claim can be traced back to the specific agent output and passage that supported it.

Reasoning Trace

The full pipeline captures timestamped, structured events — orchestration decisions, agent progress, tool calls/results, fallbacks, retries, contradiction resolutions — built mechanically from callback traces (not LLM-generated) and stored as JSON. The transcript tab displays this as an interactive timeline. Each trace event also carries per-call token usage (input/output/cache-read/cache-write).

Reference Extraction (Extend)

Optional integration with Extend (extend-ai) extracts structured reference lists (journalArticle, book, bookSection, conferencePaper, thesis, report, webpage) from uploaded documents. Disabled unless EXTEND_API_KEY/EXTEND_PROCESSOR_ID are set.

Workspace Modes

The center panel is driven by a mode registry. Seven tab modes — Research (query), Annotate, Library, Write, Map (knowledge graph), Visualize (diagram canvas: concept maps, flowcharts, cause-effect, timelines, comparisons, hierarchies), Discover (federated academic paper search) — plus two sidebar modes: Analytics (writing productivity dashboard) and Timeline (project activity timeline). The research feed stays mounted across mode switches; heavy modes are lazy-loaded. A command palette (⌘K / Ctrl+K, or “Go to…” in the top bar) jumps to any mode, project, chapter, research session or source; inside the chapter editor the same keys insert a link.

Writing & Editing

Chapter Editor

Plate.js (Slate-based) rich text editor with ~29 plugins:

• Rich formatting — headings, block quotes, lists, links, horizontal rules, alignment, tables with bubble-menu editing
• Math blocks — KaTeX equation rendering (block and inline)
• Charts — Chart.js integration with specialized academic chart templates (see below)
• Images and media, drag-and-drop block reordering (dnd-kit)
• Auto-versioning — snapshots every 5 minutes or 50+ word changes, retaining up to 50 versions per chapter with visual diff comparison

Track Changes & Suggestions

Track-changes mode with suggestion controls and bulk accept/reject. Insertions and deletions are reviewed visually before committing.

Collaborative Editing

Real-time collaborative editing via Y.js (CRDT) with @slate-yjs/core binding and remote live cursors. Server-side WebSocket sync with Y.Doc persistence: an LRU cache holds up to 200 live docs; evicted docs are snapshotted to a PostgreSQL table and reconciled against canonical chapter content on reconnect.

AI Writing Assistance

In-editor AI tools: Expand (outline → prose), Style check (passage or document-wide), Transition generation, Abstract generation, Detect uncited claims, and Analyze (argument strength).

PDF Annotation

Upload PDFs (up to 100 MB; chapter attachments up to 50 MB), view with text layer, highlight with color-coded annotations, add notes, tag highlights. Annotations are embedded for semantic search and can be passed as context to research queries. The full text of every uploaded PDF is indexed in the background (page-attributed passages, embedded locally), so research agents can find and cite it. AI annotation synthesis summarizes highlights from a source.

Footnotes & Endnotes

Both footnotes and endnotes with independent numbering, citation-linked notes formatted through the CSL processor (citeproc), manual notes, footnote↔endnote conversion, automatic Ibid./short-form at export per Chicago 17th edition, and a notes list panel with click-to-navigate and batch re-format.

Document Comments

Threaded comments anchored to text ranges, with create/resolve/delete and multiple concurrent threads.

AI Peer Review Agent

A Claude-powered reviewer produces structured feedback anchored to exact quoted passages, categorized (argument, evidence, clarity, structure, citation, methodology, grammar), with open/resolved/ignored tracking. Supports full-chapter or selection review, context-aware follow-up rounds that see prior comments, threaded replies, and review-run history.

Organization

• Projects — top-level containers typed as book, essay, research paper, or dissertation
• Chapters — drag-to-reorder, with target word counts, deadlines, and progress tracking
• Chapter Outlines — hierarchical task lists with indent levels and completion tracking
• Pinned Citations and Chapter Attachments (files and URLs)
• Project Timeline — visual timeline of project activity and milestones
• Organizations — projects can belong to an organization with member roles (owner / admin / member / viewer)

Knowledge Synthesis

Connection Discovery & Knowledge Graph

A connection engine computes pairwise similarity between research sessions, annotations, and snippets using local Transformers.js embeddings. Connections are classified by cosine-similarity strength: Strong (> 0.55), Related (0.42–0.55), Potential (0.33–0.42). AI-generated labels describe each connection in plain language; researchers can confirm, dismiss, or manually create connections. Keyword-matching fallback if embeddings fail. A knowledge graph view (react-force-graph-2d) visualizes the network per project, with a keyboard-navigable node list beside the canvas that shares its selection.

Argument Mapping

The database keeps an argument model per chapter (node types thesis, claim, evidence, counter-argument, rebuttal, qualifier; edge types supports, contradicts, qualifies, depends on), which the example project seeds. It has no UI and no HTTP API: the unmounted ArgumentCanvas and then the uncalled /api/arguments routes were removed in the 2026-09-29 code-quality pass. Visual mapping in the app is the Visualize mode’s diagram canvas.

Search

• Keyword Search — PostgreSQL full-text search (weighted tsvector, trigger-maintained) across queries, briefs, notes, and summaries
• Semantic Search — pgvector cosine similarity over local Transformers.js embeddings (no external embedding API), HNSW-indexed
• Auto Mode — keyword and semantic search both run; their rankings are fused by reciprocal rank (RRF), so a strong semantic match is never hidden behind a few weak keyword hits. Each result says which search found it (keyword, semantic, or hybrid for both)
• Library retrieval — every imported PDF is split into page-attributed passages and embedded in the background (existing sources are backfilled at boot). Research agents search the project’s library by meaning with the searchProjectLibrary tool in every run, and Library Only / Hybrid runs receive the most relevant passages up front
• Annotation Search, Manuscript Search (with context snippets), Similar Sessions (vector similarity)
• RAG Search — AI-summarized answers from past research via a LangChain retrieval chain
• Academic Search Panel — federated search across all academic and primary-source providers from within the UI, with paged results and saved searches to re-run

Live Data Connections

Economic Data Providers

FRED (free key required), World Bank, IMF, OECD, Eurostat, BIS, DBnomics (no keys), UN Comtrade (optional key).

Academic Paper Providers

Semantic Scholar (optional key), OpenAlex, CrossRef, arXiv (no keys), CORE (optional key), Unpaywall (no key).

Primary Source & Cultural Heritage Providers

Internet Archive, Library of Congress (no keys), DPLA, Europeana (optional keys).

API keys are optional throughout — a provider whose key is unset is simply omitted from the agent’s toolset, and research runs with the rest. Provider responses are cached in PostgreSQL with configurable TTL; if a service is down after retries, stale cached data is returned with a warning. Full provider table in docs/data-providers.md.

Specialized Chart Templates

Beyond basic line/bar/scatter, the editor includes social-science publishing templates: Coefficient Plot (regression results with confidence intervals), Event Study Plot, Difference-in-Differences, Marginal Effects Plot, and Choropleth Map. All default to grayscale-friendly, print-safe formatting with source attribution lines.

Source Criticism (Historians)

Structured source evaluation per upload: external criticism (provenance, archive/collection, date, authorship, document type, language), internal criticism (purpose, audience, perspective, reliability), and classification (relic vs. narrative; primary/secondary/tertiary). AI-assisted pre-population suggests values from the document text; evaluations are editable, never auto-confirmed.

Citations & Zotero Integration

• Manual Citations — create/edit/delete with auto-generated cite keys
• Zotero Connection — API-key connection; search, browse, import with duplicate detection; export briefs to Zotero as tagged notes; version-aware refresh sync; sync audit log
• CSL Formatting — Chicago Author-Date, Chicago Notes-Bibliography, and APSA via citeproc with real CSL stylesheets; local APA fallback; batch formatting
• BibTeX Import/Export (LaTeX character decoding, BibTeX/BibLaTeX flavors) and RIS Import/Export
• Bibliography Generation — per-project formatted bibliographies
• Pre-Submission Compliance Checker — reference completeness, citation format, and metadata checks as a pass/fail/warning checklist (journal-specific profiles not yet implemented)

Document Import

DOCX (Mammoth), Markdown (with front matter), Notion exports, and Scrivener projects — via a pluggable importer registry. All imports logged for audit.

Template Gallery

Chapter templates by category: Working Paper, Dissertation, Book Proposal, Grant Proposal, Journal, and user-created Custom templates (creatable from existing chapters).

Writing Analytics

Session tracking with Pomodoro timer mode, cumulative word counts and pace, consecutive-day streaks, calendar heatmap, per-chapter word targets, and detailed activity reports. An email reporter service exists for scheduled activity summaries.

Export

• Single Session / Chapter / Project / Full Manuscript DOCX — manuscript export includes title page, TOC, page numbers, footers; footnotes at page bottom, endnotes at document end; citation-linked notes preprocessed through the CSL engine for ibid./short-form
• LaTeX Export — .tex with academic structure, math preservation, table conversion; ZIP-packaged with companion .bib; template selection; endnotes via \endnote{}
• Copy to Clipboard for any output section

(No direct PDF export yet — react-pdf is used for viewing/annotation only.)

Collaboration & Sharing

• Share Links — tokenized links with view / comment / edit permission and optional expiry
• Collaborators — project-level roles: owner, editor, commenter, viewer
• Organizations — org-level membership and roles (owner / admin / member / viewer)
• Real-time Editing — Y.js CRDT concurrent editing with WebSocket sync and live cursors

Access control follows a uniform four-source rule enforced in the repository layer: owner → organization → collaborator → share-token.

Accounts & Auth

• Clerk is the auth provider (sign-in/up, session JWTs verified server-side; users mirrored into the app database). The earlier ORCID sign-in is gone; only its users columns remain.
• Account management — GDPR-style data export and account deletion endpoints.

Progressive Web App & Offline Support

• Service Worker (Workbox via vite-plugin-pwa, prompt-to-update: a new deploy shows “A new version is available — Reload” and never reloads the page by itself) — static precache; runtime caching: CacheFirst fonts, NetworkFirst documents and API (7-day cap)
• Offline Reading of recently opened sessions and chapters (the last 20 and 10, cached in IndexedDB)
• Sync Engine — offline mutations queue in IndexedDB and replay on reconnect; closing the tab while writes are still queued triggers the browser’s leave-page warning
• Network Status Indicator — offline badge; research disabled with explanation when disconnected

Marketing & SEO

The landing page is pre-rendered to static HTML at build time (Vite SSR + prerender script) with react-helmet-async meta tags, while app routes load the SPA shell. There are currently no pricing, billing, or subscription pages.

Onboarding & Help

• First-Run Wizard — 3 steps: project type/discipline, source import method, guided example query with agent explanations
• 20 Example Queries tagged by discipline, filtered to the user’s selection
• Feature Discovery Tooltips after usage milestones
• In-App Help Panel — searchable FAQ, prompt tips, keyboard shortcuts

Error Handling

• Human-readable errors throughout (technical failures translated to plain language); structured error envelope (message/code/fields/requestId) from a central error handler
• Retry with exponential backoff on all external API calls; provider circuit breakers
• Graceful degradation: CrossRef down → “pending” badges; data providers down → stale cache with warning; embeddings fail → keyword fallback
• Research runs are durable (ADR-0042): each agent’s result is saved the moment it finishes, and a run interrupted by a restart, deploy or scale-to-zero is resumed from its last completed stage within about 90 seconds (or failed with the reason, keeping the finished agents’ findings); SSE streams have a 30-minute lifetime cap with polling fallback
• React ErrorBoundary wraps the app; agent cards show amber “Retrying…” status during retries

Accessibility

ARIA labels and aria-live regions, semantic landmarks, keyboard navigation with skip-to-content, light and dark mode. Automated axe-core checks run in both the client unit suite and the e2e suite (critical-violation assertions); a comprehensive WCAG 2.1 AA audit has not been done.

Operational Profile

LLM usage shape per research run

A research run makes these Claude calls:

1. Orchestrator — 1 call (query analysis + 4 sub-prompts), effort high
2. Four specialist agents, all launched at once under one Promise.all — each an agentic tool-calling loop of up to 5 rounds (so 1–5+ LLM calls per agent, plus tool executions against free external APIs), effort medium, 16k output tokens each, individual tool results capped at 12,000 chars
3. Synthesizer — 1 call merging all four outputs, effort high, 32k output tokens
4. Background post-processing: embeddings are generated locally (Transformers.js, no API cost); citation verification hits CrossRef (free)

• Models: claude-sonnet-5 (default) or claude-opus-5, both 1M-context. Adaptive thinking (thinking: { type: 'adaptive' }) is always on; output_config.effort is the only depth dial.
• Prompt caching: agent system prompts are marked with ephemeral cache_control, so multi-round loops re-read the tools + system prompt at a fraction of the input price; that prefix stays byte-identical when a provider’s circuit breaker opens (ADR-0046). The one-call orchestrator and synthesizer are not cached (their automatic breakpoint only ever paid the write surcharge).
• No queue, no fallback chain, no response cache, no batch mode. Those existed for an early, much lower rate limit; at current Anthropic limits each of them cost either latency or output quality. The SDK’s maxRetries: 3 covers a stray 429 or 5xx.
• AI writing assists, peer review, RAG search, annotation synthesis, and argument extraction are additional per-use Claude calls outside the research pipeline.

Usage observability

Per-session token usage (input/output/cache-read/cache-write, per stage and per call) is persisted in agent logs and trace events, and one structured [llm] line is logged per API call (model, latency, tokens, cache hits). With ARIZE_API_KEY + ARIZE_SPACE_ID set, every LLM, tool and retrieval call is also traced to Arize AX (OpenTelemetry + OpenInference): one trace per research run (orchestrator → four agents → synthesizer, grouped by project, scored with a citation_grounding annotation, stamped with the prompt version) and one per AI request elsewhere (writing assists, review, RAG search, …), each carrying the user and the feature. OPENINFERENCE_HIDE_INPUTS/OUTPUTS mask user content; recorded runs feed an Arize dataset and experiments (server/scripts/arize-*.mjs). /api/health exposes live session count, Y.Doc cache stats, memory, and disk — without pinging the database (preserves Neon auto-suspend).

Quotas and rate limits

Request budgets are counted per signed-in user (per IP for requests without one) and per server instance.

Infrastructure

• Hosting: any Node 22 host; the reference deployment is Replit (production serves the built client from Express)
• Database: PostgreSQL (Neon) with pgvector; pool max 50; HNSW vector index + access-rule btree indexes
• File storage: storage seam with two drivers — Replit App Storage (production, FILE_STORAGE=replit) or local disk (dev fallback, with grandfathered reads)
• Scaling: the research live feed and the per-user research cap work across instances (ADR-0043: a Postgres event log followed with LISTEN/NOTIFY); the Y.Doc cache of collaborative editing is still in-memory, so the deployment stays pinned to a single instance (ADR-0024)
• Monetization: none built yet — no Stripe/billing/subscriptions; auth is Clerk (which supports orgs already used for multi-tenancy)

Testing

• ~2,200 automated tests: ~1,960 server tests across 129 files (Vitest + Supertest; repository contract tests run against isolated Postgres schemas) and ~260 client tests across 36 files (Vitest + Testing Library, incl. axe-core)
• Playwright e2e suite: 22 specs covering public pages, workspace shell, all 9 modes, and cross-cutting flows (API smoke, settings, research focus, onboarding, export, sharing, a11y) — with a zero-spend fake-research stub and a prod-DB guard

Tech Stack

• Frontend: React 19, Vite, Tailwind CSS (semantic design tokens), Plate.js (platejs 53.x, ~29 plugins), React Router v7, React Flow (@xyflow/react), react-force-graph-2d, react-pdf, KaTeX, Chart.js, dnd-kit, Y.js + @slate-yjs/core, idb, vite-plugin-pwa, react-helmet-async, Clerk (@clerk/clerk-react). Server state via a useAsyncOperation hook + API client modules (React Query was removed).
• Backend: Node.js, Express, PostgreSQL (pg + pgvector), LangChain.js (@langchain/anthropic, @langchain/core, langchain), Anthropic Claude API (claude-sonnet-5 default, claude-opus-5 offered), Y.js + ws, Clerk (@clerk/express), Helmet, express-rate-limit, Zod, Multer, @replit/object-storage
• Search: PostgreSQL tsvector FTS + pgvector (HNSW) with local Transformers.js embeddings (Xenova/all-MiniLM-L6-v2, 384-dim) + LangChain RAG retrieval chain
• Data / Academic / Primary sources: FRED, World Bank, IMF, OECD, Eurostat, BIS, DBnomics, UN Comtrade; Semantic Scholar, OpenAlex, CrossRef, arXiv, CORE, Unpaywall; Internet Archive, DPLA, Europeana, Library of Congress
• Citations: CrossRef API, Zotero Web API v3, citeproc (CSL), @retorquere/bibtex-parser, RIS parser; Extend (extend-ai) reference extraction
• Export/Import: docx, custom LaTeX generator + JSZip; Mammoth, markdown-it, Notion/Scrivener importers
• Testing: Vitest, Supertest, Testing Library, axe-core, Playwright

What’s Not Yet Implemented

• Billing / payments / pricing — no Stripe or subscription infrastructure; no pricing page (most important gap for commercialization)
• Journal-specific submission profiles (AER, QJE, etc.) — the compliance checker exists but has no per-journal configs
• V-Dem political science data connector — mentioned in onboarding copy but not implemented
• Direct PDF export of manuscripts (DOCX and LaTeX only)
• Comprehensive WCAG 2.1 AA audit — automated axe-core checks exist, but no full audit
• Video walkthroughs — help panel has FAQ and tips only