v4 docs: README overhaul for Aletheia Research OS — Autopilot loop diagram, provenance, studios, cost router env vars

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Your Name

.env.example

@@ -24,6 +24,13 @@ ANTHROPIC_MODEL=claude-sonnet-4-5
 # --- OpenAI (optional fallback) ---
 # https://platform.openai.com/
 OPENAI_API_KEY=
+
+# Pipeline cost router (optional): override the model used per task-complexity
+# tier. Defaults are sensible per provider (cheap model for mechanical steps,
+# strong model for reasoning steps).
+LLM_MODEL_LIGHT=
+LLM_MODEL_STANDARD=
+LLM_MODEL_DEEP=
 OPENAI_MODEL=gpt-4o-mini
 
 # --- NCBI / PubMed E-utilities ---

README.md

@@ -1,115 +1,75 @@
-# MedCore Research Builder v2
+# Aletheia Research OS (v4)
 
 [![CI](https://github.com/Abdulsalam3302/medcore-research-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/Abdulsalam3302/medcore-research-builder/actions/workflows/ci.yml)
 
-A free, no-login, reporting-guideline-driven workspace for building the core of a **medical research manuscript**. Built for clinicians and researchers worldwide — drafts stay in your browser; scholarly lookups run server-side.
+**The AI research operating system for medical science.** State a research goal and Aletheia's
+specialist agents plan, draft, critique, and refine every deliverable — study design, protocol,
+SAP, IRB pack, runnable analysis, manuscript, cover letter, reviewer responses, poster, slides,
+graphical abstract — with an automated reviewer gating every stage and a provenance record on
+every artifact.
 
-**Live app:** https://medcore-research-builder.vercel.app  
+*Aletheia* (ἀλήθεια) is the Greek word for truth — the state of not being hidden. This is the
+next version of **MedCore Research Builder**: same non-negotiable integrity rules, a new agentic
+core.
+
+**Live app:** https://medcore-research-builder.vercel.app
 **Repository:** https://github.com/Abdulsalam3302/medcore-research-builder
 
-## What’s new in v3.10
-
-- **Library Navigator** — one deterministic search across all 363 library
-  entries (185+ skills, 12 workflows, 69 tips, 29 open-source tools, 57 MCP
-  servers, 9 built-in features): answer two guided questions (stage + kind of
-  help) or type a goal, get a ranked shortlist with match reasons, inline
-  skill steps, official verify links, and jump-to-lane buttons. Offline,
-  instant, can never hallucinate an entry. New lane under Quality & Empowerment.
-- **Catalog upgrades (verified, deduplicated)** — MCP: official Hugging Face
-  and Figma servers, NPI Registry (NPPES), Mermaid diagrams, World Bank Open
-  Data. Open-source tools: jamovi, OSF, Pandoc, OpenRefine, ASReview,
-  PRISMA2020 flow diagram. Skills: ICMJE-aligned AI-use disclosure, ORCID
-  researcher identity. Every entry keeps the no-fabrication rule: an official
-  verify link, honest confidence labels.
-- **Protocol is generated, not uploaded** — the Studio and readiness ladder
-  now lead with *Generate* (design-aware skeleton or AI draft built for you);
-  *Upload existing* stays as a clearly-labelled option for documents you
-  already have. Research Launch gains a "Generate my protocol →" next step.
-
-## What’s new in v3.9
-
-- **Submission Pipeline** — track every target journal from shortlist →
-  formatting → submission → peer review → revision → acceptance → publication,
-  with stage-by-stage best practice (ICMJE/COPE-aligned), duration stats, and
-  a full status timeline. New lane under Post-Research.
-- **Publication Club** — a community board (new Community phase): post and
-  join research opportunities, meet researchers by specialty, and share
-  MedCore projects via tokenized share links so studies are initiated *and*
-  finished on the platform. Supabase-backed (`docs/CLUB_TABLES.sql`), browse
-  as guest, post/join with a free account; plain-text only, RLS-enforced,
-  strict rate limits.
-- **DOAJ integration** — `/api/doaj/search` (articles + journals) and a new
-  `check_open_access_journal` MCP tool: verify a journal's DOAJ listing
-  (license, APC, publisher) as a legitimacy signal for the predatory check.
-- **Security** — HSTS header (2-year max-age) added to the middleware
-  security set; community endpoints are auth-gated, length-capped,
-  control-character-stripped, and rate-limited.
-
-## What’s new in v3.8
-
-- **First-party MCP server** — MedCore's engines (journal finder, design
-  registry, reference verification, coherence checks, preprint search) are now
-  exposed to any Model Context Protocol client at `/api/mcp`
-  (Streamable HTTP, stateless). See [`docs/MCP_SERVER.md`](docs/MCP_SERVER.md).
-  ```bash
-  claude mcp add --transport http medcore https://medcore-research-builder.vercel.app/api/mcp
-  ```
-- **Preprint search API** — `/api/preprints/search` queries bioRxiv/medRxiv and
-  other preprints via Europe PMC's `SRC:PPR` source (free, keyless), with
-  explicit *not peer reviewed* labelling.
-- **Lint gate** — `npm run lint` (next/core-web-vitals) now passes clean and
-  runs in CI; React hook dependency hazards fixed.
-- **Sync you can trust** — cloud-sync failures and local-storage save failures
-  now surface as visible alerts (including on mobile) instead of failing silently.
-
-## What’s new in v3
-
-- **Journal Finder** — a deep journal-suggestion engine over WoS SCIE/ESCI,
-  Scopus, PubMed/MEDLINE, PMC, and DOAJ, with a curated **100%-Saudi** journal
-  set, relevance + indexing ranking, filters, official verify links, and
-  per-journal **submission formatting**. Scales to tens of thousands via
-  `scripts/ingest-journals.mjs` (OpenAlex/DOAJ/Crossref) → `lib/journals/generated.ts`.
-- **Manuscript Coherence** — treats the manuscript as one connected unit:
-  checks title↔content, design↔claims, objective↔conclusion, results↔discussion
-  (numbers + causal language), citation **order**, and cited-vs-listed integrity.
-- **Protocol / Proposal Studio** — the platform *develops* protocols (offline
-  skeleton + AI draft), design-aware (SPIRIT/PRISMA-P/STROBE/STARD/TRIPOD/CARE).
-- **Figures & Results upgrade** — figure-type recommendation with caption/legend/
-  footnotes, a Table 1 scaffold, and AI-assisted results interpretation that
-  foregrounds effect size + CI and never fabricates numbers.
-- **Reference Safety** — an anti-hallucination layer flagging unverified,
-  low-confidence, irrelevant, or retracted citations for human review.
-- **Language Studio** — academic editing that preserves meaning and every
-  number, with honest (non-guarantee) readability / AI-pattern / originality aids.
-- **Instant auth** — sign-up with no email confirmation (auto sign-in); full
-  guest mode with zero registration. See `docs/AUTH_SETUP.md`.
-- **Durable rate limiting** (Upstash) + **tokenized share links**.
-- **Tests** — `npm run test:smoke` and `npm run test:auth`.
-
-### From v2
-
-- **63 study designs**, **34 journals**, **84 feature flags** via the design registry
-- **Research Launch** readiness scoring; **Title Lab** novelty scan
-- **Reference Verifier** across PubMed, Crossref, OpenAlex, Europe PMC, Semantic Scholar, Unpaywall
-- **Quality Suite**, **Reviewer Simulator**, **Statistician Copilot**, **Flow Diagram Builder**
-- **Version history**, **DOCX export**, **system status panel**, security headers
-
-## Core principles
-
-- **Never fabricate** PMIDs, DOIs, statistics, or citations
-- **Checklist-driven** against EQUATOR reporting guidelines (CONSORT, STROBE, PRISMA, SPIRIT, STARD, TRIPOD, CARE, etc.)
-- **Transparent LLM outputs** — missing data is flagged, not invented
-- **Privacy-first** — no account required; in guest mode drafts stay in your browser with no server-side storage. Optional Supabase sign-in enables cloud sync, which stores your draft server-side only while you are signed in.
+## What's new in v4 (Aletheia)
+
+- **Research Autopilot** — an agentic pipeline console inspired by autonomous-scientist systems
+  (Sakana AI Scientist). An orchestrator agent decomposes your goal into staged deliverables;
+  each stage runs a quality loop: *draft N independent candidates → reviewer critiques & selects →
+  specialist refines → strict review gate scores against explicit acceptance criteria*. Stages
+  advance only when their dependencies are approved. Pipeline graph, live stage status, run log,
+  and a visible token budget.
+- **Provenance on every artifact** (Claude-Science-style) — inputs used, models involved, token
+  counts, estimated cost, checks passed/failed, and the full step trace. Nothing is a black box.
+- **Deliverable Studios** — the full freelancer-replacement set, one deliverable at a time, each
+  produced through the same quality loop: Study Design Dossier, Protocol, Statistical Analysis
+  Plan, IRB/Ethics Pack, Runnable Analysis Code, Full Manuscript, Abstract, Cover Letter,
+  Response to Reviewers, print-ready Poster (HTML→PDF), Conference Slide Deck, Graphical
+  Abstract, Illustration Brief.
+- **Research Advisor** — interactive methodology/strategy consultations grounded in your actual
+  project, citing the applicable standard (EQUATOR, ICMJE, COPE, GRADE) with the strongest
+  counter-consideration.
+- **Runnable Analysis Lab** — reproducible statistics in the browser via Pyodide (WebAssembly):
+  pandas, numpy, scipy, statsmodels, matplotlib. Upload a CSV, run the statistician agent's
+  script locally — data never leaves your machine.
+- **Cost-effectiveness layer** — model routing by task complexity (light/standard/deep): cheap
+  models handle mechanical steps, strong models handle reasoning. Per-run token budget with soft
+  limits and cost estimates.
+- **Real URL routes** — every lane is addressable (`/w/autopilot`, `/w/methods`,
+  `/w/journal-finder`…), shareable, and back/forward-friendly.
+- **New identity & design** — Aletheia wordmark, Space Grotesk display type, indigo/cyan
+  "scientific instrument" palette; dark console surfaces for the agentic lanes, light paper
+  surfaces for writing lanes.
+
+Everything from MedCore v3 remains and is integrated as tools the agents and you share: Journal
+Finder, Reference Verifier + Safety, Manuscript Coherence, Quality Gates, Submission Pipeline,
+Publication Club, Library Navigator (363 entries), first-party MCP server, and the rest.
+
+## Core principles (unchanged since day one)
+
+- **Never fabricate** PMIDs, DOIs, statistics, or citations — missing facts are flagged
+  `[REQUIRED]`, never invented
+- **Checklist-driven** against EQUATOR reporting guidelines (CONSORT, STROBE, PRISMA, SPIRIT,
+  STARD, TRIPOD, CARE, …)
+- **Human in control** — agents assist and are gated; the researcher decides the science
+- **Privacy-first** — no account required; guest drafts and pipeline runs stay in your browser;
+  cloud sync is opt-in; analysis data never leaves the machine
 
 ## Tech stack
 
 | Layer | Technology |
 |-------|------------|
 | Framework | Next.js 14 (App Router) |
 | UI | React 18, TypeScript, Tailwind CSS |
-| State | Browser `localStorage` only |
-| Export | DOCX, Markdown, CSV, JSON |
-| Charts | Plotly (CDN) |
+| Agent engine | Stateless `/api/pipeline/*` ops + client-owned run state |
+| In-browser stats | Pyodide (WebAssembly Python) |
+| State | Browser `localStorage` (optional Supabase cloud sync) |
+| LLM providers | MiniMax (default), Anthropic, OpenAI — routed by task complexity |
+| Export | DOCX, Markdown, CSV, JSON, HTML (poster/slides/graphical abstract), PY |
 | Deploy | `output: "standalone"` — Vercel, Railway, or any Node host |
 
 ## Getting started
@@ -122,110 +82,80 @@ npm run dev
 # Open http://localhost:3000
 ```
 
-If port 3000 is stuck with a stale process (API 404, broken CSS), kill old Node processes and restart:
-
-```bash
-lsof -ti :3000 | xargs kill -9 2>/dev/null; npm run dev
-```
-
 ## Environment variables
 
-See `.env.example`. The app degrades gracefully when optional keys are missing.
+See `.env.example`. The app degrades gracefully when optional keys are missing — without an LLM
+key the scholarly engines, reference verification, deterministic pipeline planning, and the
+Pyodide analysis lab still work.
 
 | Variable | Required | Purpose |
 |----------|----------|---------|
 | `LLM_PROVIDER` | optional | `minimax` (default), `anthropic`, or `openai` |
 | `MINIMAX_API_KEY` | recommended | Default LLM provider |
 | `ANTHROPIC_API_KEY` | optional | Anthropic LLM |
 | `OPENAI_API_KEY` | optional | OpenAI fallback |
-| `NCBI_API_KEY` | optional | PubMed rate limit 3→10 req/s |
-| `NCBI_EMAIL` · `NCBI_TOOL` | recommended | NCBI polite identification |
-| `CROSSREF_MAILTO` | recommended | Crossref polite pool |
-| `OPENALEX_MAILTO` | recommended | OpenAlex polite pool |
-| `OPENALEX_API_KEY` | optional | OpenAlex premium limits |
-| `SEMANTIC_SCHOLAR_API_KEY` | optional | S2 higher rate limits |
-| `UNPAYWALL_EMAIL` | optional | Open-access PDF links in reference verifier |
-| `TAVILY_API_KEY` or `SERPAPI_API_KEY` | optional | Web search in Title Lab novelty scan |
-| `ELICIT_API_KEY` | optional | Elicit AI search (paid) |
-
-Without an LLM key: scholarly APIs, reference verification, stats engine, and heuristic parsers still work. Drafting features show a “configure LLM” message.
+| `LLM_MODEL_LIGHT` / `LLM_MODEL_STANDARD` / `LLM_MODEL_DEEP` | optional | Override the cost router's model per complexity tier |
+| `NCBI_API_KEY` · `NCBI_EMAIL` · `NCBI_TOOL` | recommended | PubMed limits + polite identification |
+| `CROSSREF_MAILTO` · `OPENALEX_MAILTO` | recommended | Polite API pools |
+| `SEMANTIC_SCHOLAR_API_KEY` · `OPENALEX_API_KEY` | optional | Higher rate limits |
+| `UNPAYWALL_EMAIL` | optional | Open-access PDF links |
+| `TAVILY_API_KEY` or `SERPAPI_API_KEY` | optional | Web search in Title Lab |
 
 ## Testing
 
 ```bash
-# Type check
-npm run typecheck
-
-# Production build
-npm run build
-
-# API smoke tests (dev server must be running)
-npm run test:smoke
-# Or against a specific port:
-BASE_URL=http://localhost:3006 npm run test:smoke
+npm run typecheck     # TypeScript
+npm run lint          # next/core-web-vitals
+npm run build         # production build
+npm run test:smoke    # 26 API smoke tests (dev server must be running)
 ```
 
-### Manual checks
+## The pipeline loop (how Autopilot works)
 
-```bash
-curl http://localhost:3000/api/status
-curl 'http://localhost:3000/api/pubmed/search?q=heart+failure&retmax=3'
+```
+goal ──► orchestrator plans stages (DAG with dependencies)
+          │
+          ▼  per stage, owned by a specialist agent
+        draft N candidates ──► reviewer critiques & selects best
+          ▲                          │
+          │                          ▼
+        refine against feedback ◄── review gate (score vs acceptance criteria)
+                                     │
+                          pass ──► stage approved, artifact + provenance saved
+                          revise ─► one bounded fix cycle, then re-gate
+                          fail ──► stage rejected for human decision
 ```
 
-In the UI: **Reference Verifier → Load demo → Verify** and **Title Lab → Load demo → Check similarity**.
-
-## Workflow
-
-1. **Research Launch** — team, IRB, budget, readiness score  
-2. **Research Type** — pick design, journal, features → guideline recommendation  
-3. **Title Lab** — PICO, novelty scan, refinement  
-4. **Manuscript sections** — Introduction → Methods → Results → Discussion → Conclusion  
-5. **References** — parse & verify across scholarly APIs  
-6. **Quality / Compliance / Export** — review, report, DOCX  
+Specialists: Study Designer, Methodologist, Statistician, Medical Writer, Scientific Designer,
+Research Advisor — all gated by the Automated Reviewer, all bound by the same integrity rules.
 
 ## Project layout
 
 ```
 app/
-  api/           # 40 server routes (LLM, scholarly, agents, registry)
-  page.tsx       # Dashboard shell
-components/      # Feature UI (20+ panels)
+  api/            # ~45 server routes (pipeline, LLM, scholarly, agents, registry)
+  w/[[...lane]]/  # Real URL routes for every workspace lane
+components/
+  pipeline/       # Autopilot console, Studios, Advisor, Analysis Lab, Provenance UI
 lib/
-  registry/      # Designs, journals, features (v2)
-  scholarly/     # PubMed, Crossref, OpenAlex, etc.
-  agents/        # Stats, evidence, retraction, figures
-  store.ts       # localStorage persistence
-scripts/
-  smoke-test.mjs # API smoke tests
-middleware.ts    # Security headers
-```
-
-## Deployment (public)
-
-**Production:** https://medcore-research-builder.vercel.app
-
-Hosted on Vercel (Next.js standalone). Environment variables are set in the Vercel project dashboard — never commit `.env.local`.
-
-To sync local env to Vercel (maintainers only):
-
-```bash
-./scripts/sync-vercel-env.sh .env.local
-vercel deploy --prod
+  pipeline/       # Agent roster, deliverable specs, orchestrator, cost router, types
+  registry/       # 63 study designs, journals, features
+  scholarly/      # PubMed, Crossref, OpenAlex, Europe PMC, DOAJ, …
+  swarm/          # v3 peer-review swarm (Review & Improve lane)
+middleware.ts     # Security headers (CSP incl. Pyodide wasm allowances)
 ```
 
-Before going public:
+## Deployment
 
-1. Set all env vars in the host dashboard (never commit `.env.local`)
-2. Run `npm run build && npm run test:smoke` against the deployed URL
-3. Set `CROSSREF_MAILTO`, `OPENALEX_MAILTO`, `NCBI_EMAIL` for polite API pools
-4. Consider adding `TAVILY_API_KEY` for Title Lab web search
-5. Monitor rate limits — defaults are ~24 LLM req/min/IP, 12 verify/min/IP
-6. (Optional) For server-stored share links, run [`docs/SHARE_TABLE.sql`](docs/SHARE_TABLE.sql) in Supabase — without it, sharing falls back to inline URL-fragment links
+Hosted on Vercel (Next.js standalone). Set environment variables in the host dashboard — never
+commit `.env.local`. Before going public: run `npm run build && npm run test:smoke`, set the
+polite-pool emails, and monitor rate limits (~24 LLM req/min/IP by default).
 
 ## License
 
-MIT — see [LICENSE](LICENSE). MedCore is independent of EQUATOR Network, NCBI, Crossref, and OpenAlex.
+MIT — see [LICENSE](LICENSE). Aletheia is independent of the EQUATOR Network, NCBI, Crossref,
+OpenAlex, Clarivate, Scopus, Sakana AI, and Anthropic.
 
 ## Contact
 
-Founder: Abdulsalam Aleid — feedback via the in-app contact links or GitHub issues.
+Founder: Dr. Abdulsalam Aleid — feedback via the in-app contact links or GitHub issues.