diff --git a/README.md b/README.md
index 0ae3b53..acd4476 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-
+
@@ -7,11 +7,11 @@
-
+
- Joblantern takes a job listing — a URL, a recruiter message, an offer letter —
+ Joblantern takes a job listing (a URL, a recruiter message, an offer letter)
and returns a sourced, reproducible verdict on whether it is safe.
@@ -22,8 +22,8 @@
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
+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.
@@ -31,8 +31,8 @@ risk, in the language they speak, on the device they own.
## 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
+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.
@@ -42,9 +42,9 @@ 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. |
+| **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. |
+| **Investigate** | `pattern` (red-flag language), `address` (geocode and 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. |
@@ -53,31 +53,31 @@ cites its source, and every verdict is reproducible.
- 
- Legitimate offer. A real Munich engineering role clears to green; the claimed office geocodes and is plotted on an OpenStreetMap map, with each fact cited to the tool that produced it.
+ 
+ Legitimate offer. A real Munich engineering role clears to green. The claimed office geocodes and is plotted on an OpenStreetMap map, with each fact cited to the tool that produced it.
|
- 
- Recruitment scam. A Dubai "driver" offer with a Western-Union processing fee, no interview, and WhatsApp-only contact is flagged red — the "Why" panel lists the red-flag patterns behind the verdict.
+ 
+ Recruitment scam. A Dubai "driver" offer with a Western-Union processing fee, no interview, and WhatsApp-only contact is flagged red. The "Why" panel lists the red-flag patterns behind the verdict.
|
## Highlights
-- 🔎 **Evidence, not opinions** — every verdict lists weighted facts with the
+- **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
+- **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
+- **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
+- **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
+- **Open by design.** Anonymized research API (REST and GraphQL), a public
knowledge graph, regulator integration, and citable annual archives.
-- 🛡️ **Accountable** — a Trust & Safety Council governs appeals, a hash-chained
+- **Accountable.** A Trust and Safety Council governs appeals, a hash-chained
audit log backs every action, and a continuous red-team probes the agent.
## Project status
@@ -92,11 +92,11 @@ See [`docs/ROADMAP.md`](docs/ROADMAP.md) and
|-------|--------|
| **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 |
+| **Web / API** | `chi` router, server-rendered templates, REST and GraphQL |
| **Data** | PostgreSQL 16 + PostGIS + pgvector |
-| **Geo** | Self-hosted Nominatim + Overpass (OpenStreetMap) |
+| **Geo** | Self-hosted Nominatim and Overpass (OpenStreetMap) |
| **Maps** | Leaflet (self-hosted) on OSM tiles |
-| **Observability** | Prometheus + structured `slog` |
+| **Observability** | Prometheus and structured `slog` |
Architectural decisions are recorded in [`docs/ADR/`](docs/ADR/).
@@ -127,7 +127,7 @@ make migrate-up # run migrations
make build && ./bin/joblantern
```
-Visit `http://localhost:8080/healthz` — you should see `ok`.
+Visit `http://localhost:8080/healthz` and you should see `ok`.
## Try the API
@@ -140,37 +140,37 @@ curl -s -X POST http://localhost:18080/api/v1/verify \
"claimed_address": "Business Bay Tower, Dubai",
"jurisdiction": "AE"
}'
-# → { "verification_id": "…" } then GET /api/v1/verifications/
+# returns { "verification_id": "..." }, then GET /api/v1/verifications/
```
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.
+wire-only fee, no interview), plus a map pin if the address resolves.
## Documentation
| 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) |
+| Architecture and decisions | [`docs/ADR/`](docs/ADR/) |
+| Self-hosting | [`docs/SELF-HOSTING.md`](docs/SELF-HOSTING.md), [`docs/SCALING-RUNBOOK.md`](docs/SCALING-RUNBOOK.md) |
+| Research and 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) |
## License
-Apache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
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.
-## Contributing & security
+## Contributing and security
-- Contributions are accepted under the Developer Certificate of Origin — see [CONTRIBUTING.md](CONTRIBUTING.md).
+- 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.