Document the demo flow, field notes, and trace sharing process.

DEMO_SCRIPT.md

@@ -0,0 +1,42 @@
+# Borderless Demo Script
+
+## Setup
+
+1. Open the Space and sign in with Hugging Face.
+2. Point out the guided profile form, demo personas, chat, and live globe.
+3. Select **India software engineer** to fill the chat box.
+4. Send the prompt.
+
+## Narration
+
+"Borderless starts from the kind of messy profile a real person has: passport,
+education, work history, languages, budget, timeline, and goals. Instead of
+answering from memory, the agent plans a research session, searches for official
+immigration sources, reads the relevant pages, and marks viable countries on the
+globe."
+
+## Expected Beats
+
+- The tool trace shows planning, country profile lookup, web search, page
+  scraping, and globe updates in readable language.
+- The globe flies to a shortlist and opens the first pathway label.
+- The final answer uses `Snapshot`, `Best-Fit Countries`, `Pathway Details`,
+  `Documents To Prepare`, `Risks And Tradeoffs`, `Official Sources`, and
+  `Next Steps`.
+- The answer cites official URLs and flags anything that still needs checking.
+
+## Follow-Up Prompt
+
+After the first answer, ask:
+
+> Pick the strongest country from this shortlist and give me a 90-day document
+> preparation plan.
+
+This shows that Borderless can move from broad exploration to a concrete action
+plan while keeping the same user profile in context.
+
+## Closing Line
+
+"The point is not to replace an immigration lawyer. The point is to help a person
+arrive at a short, evidence-backed list of countries and pathways worth serious
+follow-up."

FIELD_NOTES.md

@@ -0,0 +1,56 @@
+# Borderless Field Notes
+
+## Why This Exists
+
+Immigration research is high-stakes, fragmented, and exhausting. A person trying
+to move for work, study, family, or safety often has to compare government pages,
+embassy notes, point calculators, processing-time pages, blogs, and anecdotes.
+Borderless is built for the moment before someone pays a lawyer: "What countries
+are realistically worth researching for my profile?"
+
+## Why A Small Model Fits
+
+The hard part is not memorizing every immigration rule. Policies change too
+often. A small model works well when it is used as a planner and synthesizer:
+
+- It turns an everyday-language profile into a concrete research plan.
+- It calls search and scraping tools for current official sources.
+- It compares tradeoffs in plain language.
+- It drives the globe so geography is part of the reasoning, not decoration.
+
+This is a better fit than a larger model guessing from stale training data.
+
+## What Changed After Prototype Testing
+
+The first prototype was a pure chat with visible tool JSON and an editable system
+prompt. It worked, but a new user had to know what to ask and judges had to read
+through debugging details.
+
+The award-ready version adds:
+
+- A guided intake form that creates a complete research prompt.
+- Demo personas for quick evaluation.
+- A stricter research protocol focused on official sources.
+- Source-quality labels in search results.
+- Country-profile metadata for shortlist and globe grounding.
+- Friendlier tool traces that explain progress without raw JSON noise.
+- Globe loading and empty states so the visual panel is useful immediately.
+- Local JSONL trace logging that can be shared as hackathon evidence.
+
+## Responsible Use
+
+Borderless is research support, not legal advice. The agent is instructed to cite
+official sources for eligibility, documents, fees, timelines, and application
+steps. When official data is missing or a tool fails, the answer should say what
+needs verification instead of inventing details.
+
+## Hackathon Award Fit
+
+- Backyard AI: a practical tool for a real, specific life decision.
+- Best Agent: multi-step tool use, source quality, partial synthesis, and globe
+  updates are all model-driven.
+- Best Demo: the guided form plus globe shortlist creates an immediate visual
+  story.
+- Sharing is Caring: JSONL traces can be published with the Space or linked in a
+  writeup.
+- Field Notes: this report documents the product choices and constraints.

README.md

@@ -25,9 +25,10 @@ Built for the [Build Small Hackathon](https://huggingface.co/build-small-hackath
 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 economic context from official sources.
+2. **Use guided intake or chat** — start from a structured profile form, a demo persona, or a free-form message.
+3. **Get a shortlist** — the agent reasons over your profile and surfaces destination countries that fit.
+4. **Explore on a 3D globe** — shortlisted countries appear on an interactive MapLibre globe beside the chat with pathway labels.
+5. **Dig into the details** — visa pathways, required documents, realistic timelines, risks, and source links from official pages.
 
 No forms to decode. No keyword guessing. Just a research session that meets you where you are.
 
@@ -37,23 +38,27 @@ Borderless is a **Gradio agent** powered by **[Qwen/Qwen3.6-27B](https://hugging
 
 | Tool | What it fetches |
 |------|-----------------|
-| `search_immigration_info` | Web search for official immigration pages, policies, and pathways (Exa) |
+| `get_country_profile` | Country metadata and official immigration domain hints (REST Countries + curated hints) |
+| `search_immigration_info` | Web search with source-quality labels for official immigration pages, policies, and pathways (Exa) |
 | `scrape_web_page` | Markdown content from a specific official government or embassy URL (Firecrawl) |
 | `crawl_web_site` | Multiple pages from an official immigration website section (Firecrawl) |
 | `update_globe` | Marks, highlights, and flies to countries on the MapLibre globe |
 
-Tool calls stream in the chat so you can follow the agent's reasoning. Globe updates are also tool-driven: when the agent recommends destinations or the user asks to mark countries, it sends ISO country codes to the map and the UI renders markers, highlights, and camera movements. After up to five tool rounds, it synthesizes a clear answer with pathways, documents, timelines, and cited sources.
+Tool calls stream in the chat so you can follow the agent's progress. Globe updates are also tool-driven: when the agent recommends destinations or the user asks to mark countries, it sends ISO country codes and pathway labels to the map. The default research budget is seven tool rounds, then Borderless synthesizes a clear answer with pathways, documents, timelines, risks, and cited sources.
 
 Sign in with your Hugging Face account to run inference through the Inference API.
 
 ## Features
 
+- **Guided intake** — form fields turn citizenship, education, work, languages, budget, and goals into a complete research prompt
 - **Agentic research** — multi-turn tool use, not a single-shot prompt
-- **Tool-driven 3D globe** — MapLibre GL globe projection with markers, highlights, fly-to camera moves, drag, rotate, and zoom
+- **Structured recommendations** — shortlist, pathways, documents, risks, timelines, next steps, and official sources
+- **Tool-driven 3D globe** — MapLibre GL globe projection with markers, highlights, pathway labels, fly-to camera moves, drag, rotate, and zoom
+- **Source quality** — search results identify likely official government, embassy, and unofficial context sources
 - **Web search** — Exa discovers official immigration pages, visa rules, and policy sources
 - **Official page scraping** — Firecrawl extracts markdown from government immigration sites
 - **Country metadata** — REST Countries powers ISO-2 / ISO-3 lookup and map coordinates
-- **Transparent traces** — every tool call and result visible in the chat
+- **Transparent traces** — tool progress is visible in chat, and JSONL traces can be sanitized and shared
 - **Chat history** — pick up where you left off in the sidebar
 
 ## Example prompts
@@ -77,6 +82,9 @@ Sign in with your Hugging Face account to run inference through the Inference AP
 
 ```
 app.py                  # Gradio Blocks entry point
+FIELD_NOTES.md          # Build notes and award narrative
+DEMO_SCRIPT.md          # Short demo-video script
+TRACE_SHARING.md        # How to sanitize and share agent traces
 ui/
   chat.py               # ChatInterface + globe layout
   globe.py              # MapLibre globe panel
@@ -86,10 +94,13 @@ ui/
   country_coords.py     # Country lookup for globe coordinates
 apis/
   rest_countries.py     # REST Countries metadata client
+  country_profile.py    # Country profile tool wrapper
+  official_sources.py   # Official-domain hints and source classification
   exa.py                # Exa web search client
   firecrawl.py          # Firecrawl scrape/crawl client
 assets/
-  globe.js / globe.css  # Globe rendering
+  app.css               # Gradio branding
+  globe.js / globe.css  # Globe rendering, loading, and empty states
 ```
 
 ## Hackathon fit
@@ -99,6 +110,8 @@ assets/
 | 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 |
+| Sharing is Caring | JSONL tool traces can be sanitized and published |
+| Field Notes | See `FIELD_NOTES.md` |
 
 **Track:** Backyard AI — immigration research is a real, specific problem faced by millions of people weighing where they can live, work, and study.
 
@@ -118,6 +131,10 @@ For web research tools, set API keys from [dashboard.exa.ai](https://dashboard.e
 |----------|-------|
 | `EXA_API_KEY` | `search_immigration_info` |
 | `FIRECRAWL_API_KEY` | `scrape_web_page`, `crawl_web_site` |
+| `BORDERLESS_MODEL_ID` | Optional model override, default `Qwen/Qwen3.6-27B` |
+| `BORDERLESS_MAX_TOOL_ROUNDS` | Optional tool-round budget, default `7` |
+| `BORDERLESS_TRACE_DIR` | Optional JSONL trace output directory |
+| `BORDERLESS_DISABLE_TRACE_LOGS` | Set to `1` to disable local trace logs |
 
 On Hugging Face Spaces, add both as **Space secrets** (Settings → Secrets). Without keys, web tools return a clear error. The agent uses Exa to discover URLs, then Firecrawl to fetch full official page content.
 

TRACE_SHARING.md

@@ -0,0 +1,26 @@
+# Trace Sharing
+
+Borderless writes non-blocking JSONL tool traces to `agent_traces/` by default.
+These traces are ignored by git so local demos do not accidentally commit noisy
+runtime files.
+
+Each line includes:
+
+- Timestamp
+- Tool name
+- Tool arguments
+- Duration
+- Truncated tool result
+
+Use these traces to support the Build Small **Sharing is Caring** badge:
+
+1. Run a polished demo prompt in the Space or locally.
+2. Review the generated `agent_traces/borderless-YYYYMMDD.jsonl` file.
+3. Remove any personal information from the user profile or tool results.
+4. Publish the sanitized trace as a Hugging Face dataset, gist, or appendix to a
+   field-notes post.
+
+Configuration:
+
+- `BORDERLESS_TRACE_DIR`: output directory, default `agent_traces`.
+- `BORDERLESS_DISABLE_TRACE_LOGS=1`: disable trace logging.