diff --git a/README.md b/README.md
index 82ceeab..3bda982 100644
--- a/README.md
+++ b/README.md
@@ -1,83 +1,161 @@
-# Joblantern
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Joblantern takes a job listing — a URL, a recruiter message, an offer letter —
+ and returns a sourced, reproducible verdict on whether it is safe.
+
+
+---
+
+## The problem
+
+Every year, migrant workers and first-time job seekers lose **billions** to
+fraudulent recruiters, fake licensing fees, and trafficking-adjacent schemes
+that look completely legitimate on the surface. The tools needed to expose
+them — company registries, domain history, scam databases, salary benchmarks,
+recruitment-fee law — already exist and are mostly free and open. They are
+simply not stitched together, and they are not in the hands of the people at
+risk, in the language they speak, on the device they own.
+
+**Joblantern stitches them together** behind a single question: *is this job real?*
+
+## How it works
+
+A submission is fanned out to a panel of specialist sub-agents — each wrapping
+one open data source through the Model Context Protocol — whose findings are
+fused by a deterministic risk engine into one of three bands. Every signal
+cites its source, and every verdict is reproducible.
+
+
+
+
+
+| Stage | What happens |
+|-------|--------------|
+| **Submit** | A URL, pasted recruiter message, or offer letter — via web, kiosk, bot, or REST/GraphQL API. |
+| **Orchestrate** | The agent fans the submission out to MCP sub-agents in parallel. |
+| **Investigate** | `pattern` (red-flag language), `address` (geocode + map via Nominatim), `registry` (company exists?), `domain`, `salary`, `law`/`routing`, `scam-db`, and adjacent-domain packs. |
+| **Score** | A deterministic engine fuses weighted, sourced facts into a **green / amber / red** band with a confidence figure. |
+| **Verdict** | A reproducible result with cited evidence, an optional map of the claimed office, and a publicly verifiable signature. |
+
+## Highlights
+
+- 🔎 **Evidence, not opinions** — every verdict lists weighted facts with the
+ tool and source that produced them. Nothing is a black box.
+- 🗺️ **Geospatial verification** — the claimed office address is geocoded and
+ shown on an OpenStreetMap map; addresses that do not resolve count against
+ the listing.
+- 🧩 **16 MCP servers** — each open data source is an independent, swappable
+ MCP server; deployments enable only what they need.
+- 🌐 **Built for the frontline** — multilingual UI, no-JS "lite" mode for
+ hostile networks, embassy kiosk mode, caller-ID lookups, and a one-tap
+ panic-wipe.
+- 🔬 **Open by design** — anonymized research API (REST + GraphQL), a public
+ knowledge graph, regulator integration, and citable annual archives.
+- 🛡️ **Accountable** — a Trust & Safety Council governs appeals, a hash-chained
+ audit log backs every action, and a continuous red-team probes the agent.
+
+## Project status
+
+**Pre-alpha, under active development.** Interfaces and schemas may change.
+See [`docs/ROADMAP.md`](docs/ROADMAP.md) and
+[`docs/ROADMAP-EXTENDED.md`](docs/ROADMAP-EXTENDED.md) for the full plan.
+
+## Tech stack
+
+| Layer | Choice |
+|-------|--------|
+| **Language** | Go 1.25+ |
+| **Agent** | Multi-agent orchestrator over the [official MCP Go SDK](https://github.com/modelcontextprotocol/go-sdk) |
+| **Web / API** | `chi` router · server-rendered templates · REST + GraphQL |
+| **Data** | PostgreSQL 16 + PostGIS + pgvector |
+| **Geo** | Self-hosted Nominatim + Overpass (OpenStreetMap) |
+| **Maps** | Leaflet (self-hosted) on OSM tiles |
+| **Observability** | Prometheus + structured `slog` |
+
+Architectural decisions are recorded in [`docs/ADR/`](docs/ADR/).
-[](https://github.com/yasserrmd/joblantern/actions/workflows/ci.yml)
-[](https://www.apache.org/licenses/LICENSE-2.0)
-[](https://go.dev/dl/)
-[](#status)
-
-> **An agentic AI system that protects job seekers from fraudulent
-> employers, fake listings, and exploitative recruitment schemes.**
-
-Joblantern takes a job listing — a URL, a recruiter message, an offer
-letter — and runs it through a multi-agent verification pipeline that
-checks the company's registration, the domain's history, public scam
-databases, salary plausibility, and recruitment-fee legality in the
-destination country. Every signal cites its source and every verdict
-is reproducible.
-
-## Why
+## Quickstart
-Migrant workers and first-time job seekers lose billions every year to
-fraudulent recruiters, fake licensing fees, and trafficking-adjacent
-schemes that look completely real on the surface. The tools to verify
-a recruiter already exist and are mostly free and open. They are just
-not stitched together. Joblantern stitches them together.
+### Docker (recommended)
-## Status
+```bash
+git clone https://github.com/yasserrmd/joblantern.git
+cd joblantern
-Pre-alpha. Active development.
+# Postgres + the address sub-agent + the app
+docker compose -f deploy/docker-compose.smoketest.yml up -d --build
+```
-## Stack
+Open **http://localhost:18080** and submit a listing. Tear down with:
-- **Backend:** Go 1.23+
-- **Agent framework:** [Google ADK for Go](https://github.com/google/adk-go)
-- **MCP:** [Official Go SDK](https://github.com/modelcontextprotocol/go-sdk)
-- **Database:** PostgreSQL 16
-- **Web:** chi + templ + HTMX + Tailwind CSS
-- **Observability:** OpenTelemetry + Prometheus + slog
+```bash
+docker compose -f deploy/docker-compose.smoketest.yml down -v
+```
-See [`docs/ADR/`](docs/ADR/) for locked architectural decisions.
-
-## Quickstart
+### Local build
```bash
-# clone
-git clone https://github.com/yasserrmd/joblantern.git
-cd joblantern
-
-# environment
cp .env.example .env
+make docker-up # bring up Postgres
+make migrate-up # run migrations
+make build && ./bin/joblantern
+```
-# bring up postgres
-make docker-up
+Visit `http://localhost:8080/healthz` — you should see `ok`.
-# run migrations
-make migrate-up
+## Try the API
-# build and run
-make build
-./bin/joblantern
+```bash
+curl -s -X POST http://localhost:18080/api/v1/verify \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "listing_text": "URGENT driver wanted Dubai AED 18000, send AED 2500 processing fee via Western Union, no interview, WhatsApp only",
+ "company_name": "QuickJobs Gulf",
+ "claimed_address": "Business Bay Tower, Dubai",
+ "jurisdiction": "AE"
+ }'
+# → { "verification_id": "…" } then GET /api/v1/verifications/
```
-Visit `http://localhost:8080/healthz` — you should see `ok`.
+The verdict comes back **red** with cited red-flag evidence (extraordinary pay,
+wire-only fee, no interview) and — if the address resolves — a map pin.
-## License
+## Documentation
-Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
+| Area | Docs |
+|------|------|
+| Architecture & decisions | [`docs/ADR/`](docs/ADR/) |
+| Self-hosting | [`docs/SELF-HOSTING.md`](docs/SELF-HOSTING.md) · [`docs/SCALING-RUNBOOK.md`](docs/SCALING-RUNBOOK.md) |
+| Research & data | [`docs/RESEARCH-API.md`](docs/RESEARCH-API.md) · [`docs/KNOWLEDGE-GRAPH.md`](docs/KNOWLEDGE-GRAPH.md) |
+| Frontline modes | [`docs/EMBASSY-KIOSK.md`](docs/EMBASSY-KIOSK.md) · [`docs/CALLER-ID.md`](docs/CALLER-ID.md) · [`docs/HOSTILE-NETWORK.md`](docs/HOSTILE-NETWORK.md) |
+| Governance | [`docs/GOVERNANCE.md`](docs/GOVERNANCE.md) · [`docs/COUNCIL-CHARTER.md`](docs/COUNCIL-CHARTER.md) · [`docs/TRANSPARENCY.md`](docs/TRANSPARENCY.md) |
+| Compliance | [`docs/COMPLIANCE/`](docs/COMPLIANCE/) (GDPR / DPDPA / PDPL) |
-Every dependency must be Apache 2.0, BSD, MIT, or another permissive
-license — no GPL, AGPL, LGPL, SSPL, BUSL, or Elastic License code may
-ship in the Joblantern binary.
+## License
-## Contributing
+Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
-See [CONTRIBUTING.md](CONTRIBUTING.md). All contributions are accepted
-under the Developer Certificate of Origin (DCO).
+Every dependency that ships in the Joblantern binary must be permissively
+licensed (Apache 2.0, BSD, MIT). No GPL, AGPL, LGPL, SSPL, BUSL, or Elastic
+License code may be linked in.
-## Security
+## Contributing & security
-See [SECURITY.md](SECURITY.md) for vulnerability disclosure.
+- Contributions are accepted under the Developer Certificate of Origin — see [CONTRIBUTING.md](CONTRIBUTING.md).
+- Report vulnerabilities per [SECURITY.md](SECURITY.md).
+- Community expectations: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
## Author
-Mohamed Yasser — Solutions Architect.
+**Mohamed Yasser** — Solutions Architect.
diff --git a/docs/assets/architecture.png b/docs/assets/architecture.png
new file mode 100644
index 0000000..eadfd33
Binary files /dev/null and b/docs/assets/architecture.png differ
diff --git a/docs/assets/banner.png b/docs/assets/banner.png
new file mode 100644
index 0000000..319cab6
Binary files /dev/null and b/docs/assets/banner.png differ