docs(readme): rewrite for accuracy, structure, and honest scope

Replace the flat 15-bullet feature list with a grouped, scannable layout:
hero with logo, TOC, value props, features by domain, visual-tour grid,
production + dev quick-start, mermaid architecture diagram, reorganised
docs, tech-stack table, and a new Scope & Limitations section.

Tone down marketing language (drop 'Universal', HIPAA implication, 'Full
compliance with FHIR', generic 'Async Processing'). Surface real shipped
features that were missing: FHIR R4 server facade (18 resources), Unified
Catalog Registry + knowledge graph, vaccinations, export/import backups,
HITL proposal model, full notifications system, security posture, MCP/
webhook/bridge integrations, PWA/offline/i18n.

Author: constLiakos

CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- **README rewrite — accurate, structured, no overclaiming.** Replaced the flat 15-bullet feature list with a grouped, scannable layout: hero with logo, table of contents, "what's different" value props, features organised by domain (clinical data model, workflows, AI, integrations, notifications, security & ops, platform), visual-tour thumbnail grid, a production Docker quick-start (`setup_env.py` → `docker compose … standalone up -d` → `create_system_admin.py`) alongside the dev path, a mermaid architecture diagram, the docs reorganised into the 5 `docs-tree.json` categories, the tech-stack table, and a new honest **Scope & Limitations** section. Toned down marketing language: dropped "Universal", the HIPAA-certification implication, "Full compliance with FHIR" (now "18 R4 resources, advanced conformance is roadmap"), and the generic "Async Processing" bullet (folded into Architecture). Surfaced previously-missing shipped features: the FHIR R4 server facade, Unified Catalog Registry + knowledge graph, Vaccinations/Immunizations, Export/Import backups, the HITL proposal model ("AI never writes clinical data"), the full notifications system, the security posture (Fernet-encrypted keys, prompt-injection guard, HMAC webhooks, audit provenance), the MCP client + webhook + bridge integrations, and PWA/offline/i18n. Added explicit "no medical certification, not HIPAA/GDPR-certified" and the telemetry-outside-FHIR tradeoff to Scope. All 23 doc links + 5 images + logo verified to resolve. Support block moved below features.
+
 - **Popup/dropdown clipping fix on create forms (allergy / examination / medication / clinical events).** Calendar (DatePicker), AI assistant (AIAssistButton), and the selector family (SearchableDropdown, DoctorSelector, OrganizationSelector, CategorySelector, CategoryDropdown, UnitSelector, AnatomyTypeahead) previously rendered their dropdowns inline with `absolute z-50`. Inside modal forms with `overflow-hidden` + `max-h-[90vh]` + `overflow-y-auto`, those dropdowns were clipped at the form/modal boundary — invisible near the bottom edge or on small screens. **New reusable `Popover` primitive** (`components/ui/Popover.tsx`) renders via `createPortal(…, document.body)` with `position: fixed` coordinates from `getBoundingClientRect()`, **auto-flips** when there's no room below (renders above the trigger), **auto-shifts** horizontally to stay in the viewport, and **repositions on scroll/resize** (capture-phase scroll listener, so nested scroll containers inside modal forms also trigger it). All 8 popup components converted; outside-click handling now centralised in one place. Type-check clean; production build green.
 
 - **Hybrid catalog search (trigram + FTS + RRF) for the agentic chatbot + REST + global search.** `search_catalogs`, `search_available_biomarkers`, `search_medications`, and `search_concepts` chatbot tools — plus the `/catalogs/search`, `/search`, and `/concepts/search` REST endpoints — now run through one unified hybrid pipeline in `catalog_search_service.py`. For each catalog, a single SQL runs three matchers (trigram `%` over name/slug/code + `websearch_to_tsquery` FTS over description/indications/info/aliases + `ILIKE` substring fallback) and fuses them via **Reciprocal Rank Fusion** (k=60). Cross-catalog hits are then globally RRF-ranked with a per-type floor so a strong biomarker match can't completely hide an allergy hit. The LLM-facing payload is now enriched: every hit carries `matched_on` (e.g. `["name", "alias", "text"]`), a `ts_headline` snippet showing the match context, and the `score`. Alias matching is fuzzy via `::text ILIKE` (so `"FBS"` now finds `"Fasting Glucose"` via its alias — previously only exact JSONB `@>` containment worked). New migration `j1a2b3c4d5e6` adds per-column trigram GIN indexes (`ix_<table>_<col>_trgm`) + FTS tsvector expression GIN indexes (`ix_<table>_fts`) on biomarker/medication/allergy/anatomy/vaccine/concept catalogs. 11 new tests (`test_hybrid_search.py`); the existing `search_*` per-domain functions keep their ORM-returning signatures (internal delegation only). Plan: `dev/plans/unified-catalog-architecture-2026-07-08.md` Phase 5.