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, econometric studies, and macroeconomic indicators (live data via FRED, World Bank, IMF, OECD, Eurostat, BIS, DBnomics, UN Comtrade)
• 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.

Limits: max 3 concurrent research sessions (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. 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 failures, 1-hour cooldown).

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.

Batch Research Mode

An optional batch path (batch: true on submission) routes the query through the Anthropic Message Batches API: 50% token discount, typically ~1-hour turnaround (up to 24h). Trade-off: single-turn per agent — no tool calling, so no live data fetches. Sessions sit in a batch_processing status and a background poller collects results.

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) 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. Each citation gets a badge: Verified (DOI resolves, metadata matches), Partial match, Unverified (flagged for manual review), or Pending (verification incomplete, e.g., CrossRef temporarily down). Researchers can manually override status. CrossRef responses are cached in a PostgreSQL table.

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.

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

Argument Mapping

An argument canvas (React Flow) visualizes chapter logic. Node types: thesis, claim, evidence, counter-argument, rebuttal, qualifier. Edge types: supports, contradicts, qualifies, depends on. An AI argument extractor auto-populates the canvas from chapter text.

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 first, supplemented with semantic results if fewer than 3 matches
• 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

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). Legacy ORCID code exists but is no longer wired into routes.
• Account management — GDPR-style data export and account deletion endpoints.

Progressive Web App & Offline Support

• Service Worker (Workbox via vite-plugin-pwa, auto-updating) — static precache; runtime caching: CacheFirst fonts, NetworkFirst documents, StaleWhileRevalidate API (7-day cap)
• Offline Reading of cached sessions/chapters; explicit offline pinning
• Sync Engine — offline mutations queue in IndexedDB and replay on reconnect
• 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
• A stuck-session reaper sweeps every 15 minutes and fails research sessions stale for >30 minutes; 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 & Cost Profile

This section summarizes the cost drivers and operational limits relevant to unit economics.

LLM usage shape per research run

A standard (non-batch) research run makes these Claude calls:

1. Orchestrator — 1 call (query analysis + 4 sub-prompts)
2. Four specialist agents in parallel — 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); tool results truncated to 2,000 chars each; message history pruned after round 2 to contain token growth
3. Synthesizer — 1 call merging all four outputs
4. Background post-processing: embeddings are generated locally (Transformers.js, no API cost); citation verification hits CrossRef (free)

Cost controls in place:

• Models: default claude-sonnet-4-6; automatic fallback chains Opus → Sonnet → Haiku on rate-limit/server errors; extended thinking (10k-token budget) on Opus/Sonnet, stripped for Haiku
• Prompt caching: agent system prompts are marked with ephemeral cache_control (padded to the 2k-token cache minimum), so multi-round loops re-read the system prompt at ~10% of input price
• LLM response cache: in-process LRU (500 entries, 30-min TTL) deduplicates identical calls
• LLM queue: all calls serialized through a single queue (2s minimum gap) with live rate-limit tracking from Anthropic response headers; agents launch concurrently only when >30k tokens of rate-limit headroom remain
• Batch mode: 50% token discount for non-interactive runs (no tools)
• 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. A daily usage summary logs aggregate calls/tokens with cost estimates from a built-in per-model price table (including cache read/write multipliers). /api/health exposes queue depth, rate-limit state, live session count, Y.Doc cache stats, memory, and disk — without pinging the database (preserves Neon auto-suspend).

Quotas and rate limits

Infrastructure

• Hosting: Replit (production serves the built client from Express; deploys build the local workspace main)
• 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: optional multi-process clustering (CLUSTER_WORKERS); note that stream manager, Y.Doc cache, and LLM cache are in-memory per process (sticky sessions needed for multi-worker)
• 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 (@udecode/plate 48.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-4-6 default; claude-opus-4-6 and claude-haiku-4-5-20251001 in fallback chains) + Message Batches via @anthropic-ai/sdk, 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