Update README.md to reflect new project focus and features for the Borderless immigration research tool, including detailed descriptions of functionality, tech stack, and example prompts.

README.md

@@ -1,6 +1,6 @@
 ---
 title: Borderless
-emoji: 💬
+emoji: 🌍
 colorFrom: yellow
 colorTo: purple
 sdk: gradio
@@ -12,4 +12,99 @@ hf_oauth_scopes:
 - inference-api
 ---
 
-An example chatbot using [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
+# Borderless
+
+**An agentic immigration research tool — describe your background in plain English, explore where you could go.**
+
+Live demo: **[build-small-hackathon/borderless](https://huggingface.co/spaces/build-small-hackathon/borderless)**
+
+Built for the [Build Small Hackathon](https://huggingface.co/build-small-hackathon) — small models (≤32B), big adventure.
+
+## What it does
+
+Immigration research is fragmented across government sites, forums, and spreadsheets. Borderless puts it in one conversational flow:
+
+1. **Describe yourself** — citizenship, education, work history, languages, budget, and goals in everyday language.
+2. **Get a shortlist** — the agent reasons over your profile and surfaces destination countries that fit.
+3. **Explore on a 3D globe** — shortlisted countries appear on an interactive MapLibre globe beside the chat.
+4. **Dig into the details** — visa pathways, required documents, realistic timelines, and live economic context from the World Bank.
+
+No forms to decode. No keyword guessing. Just a research session that meets you where you are.
+
+## How it works
+
+Borderless is a **Gradio agent** powered by **[Qwen/Qwen3.6-27B](https://huggingface.co/Qwen/Qwen3.6-27B)** (27B parameters — within the hackathon's 32B cap). The model plans multi-step research and calls tools when it needs ground truth:
+
+| Tool | What it fetches |
+|------|-----------------|
+| `get_visa_requirement` | Visa rules between your passport country and a destination |
+| `get_passport_stats` | Aggregate visa-free / visa-on-arrival access for a passport |
+| `get_economic_indicator` | World Bank time series (GDP, inflation, trade, and more) |
+
+Tool calls stream in the chat so you can follow the agent's reasoning. After up to five tool rounds, it synthesizes a clear answer with pathways, documents, timelines, and economic snapshots.
+
+Sign in with your Hugging Face account to run inference through the Inference API.
+
+## Features
+
+- **Agentic research** — multi-turn tool use, not a single-shot prompt
+- **3D globe** — MapLibre GL globe projection with drag, rotate, and zoom
+- **Live visa data** — passport strength and country-pair requirements
+- **Economic context** — World Bank indicators to compare destinations
+- **Transparent traces** — every tool call and result visible in the chat
+- **Chat history** — pick up where you left off in the sidebar
+
+## Example prompts
+
+- *"I'm a software engineer from India with 5 years of experience and a master's degree. Where could I realistically relocate for work?"*
+- *"I hold a Hong Kong passport and want to study in Europe on a modest budget. What are my visa options?"*
+- *"Compare GDP growth and unemployment for Canada, Germany, and Australia over the last decade."*
+- *"What documents do I need to apply for a skilled worker visa from the UK to Portugal?"*
+
+## Tech stack
+
+- **[Gradio](https://gradio.app)** — chat UI, OAuth, and custom HTML/JS globe panel
+- **[Qwen3.6-27B](https://huggingface.co/Qwen/Qwen3.6-27B)** — reasoning and tool planning via Hugging Face Inference API
+- **[huggingface_hub](https://huggingface.co/docs/huggingface_hub)** — `InferenceClient` with streaming and function calling
+- **[MapLibre GL JS](https://maplibre.org/)** — interactive 3D globe
+- **[World Bank Open Data API](http://api.worldbank.org/)** — economic indicators
+- **Passport Visa API** — visa requirements and passport mobility stats
+
+## Project structure
+
+```
+app.py                  # Gradio Blocks entry point
+ui/
+  chat.py               # ChatInterface + globe layout
+  globe.py              # MapLibre globe panel
+  sidebar.py            # HF login + history sidebar
+  inference/            # Agent loop, tools, streaming
+apis/
+  world_bank.py         # World Bank indicator client
+  passport_visa.py      # Visa & passport stats client
+assets/
+  globe.js / globe.css  # Globe rendering
+```
+
+## Hackathon fit
+
+| Constraint | Borderless |
+|------------|------------|
+| Model ≤ 32B | Qwen3.6-27B (27B) |
+| Gradio on HF Spaces | Yes — [live Space](https://huggingface.co/spaces/build-small-hackathon/borderless) |
+| Agentic | Multi-tool research loop with visible traces |
+
+**Track:** Backyard AI — immigration research is a real, specific problem faced by millions of people weighing where they can live, work, and study.
+
+## Run locally
+
+```bash
+pip install gradio huggingface_hub requests
+python app.py
+```
+
+Set a Hugging Face token with Inference API access, or sign in through the app's OAuth flow when deployed.
+
+## License
+
+Apache-2.0 (model: [Qwen/Qwen3.6-27B](https://huggingface.co/Qwen/Qwen3.6-27B))