> ## Documentation Index
> Fetch the complete documentation index at: https://docs.closient.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hyperlocal Nearby

> Discover what's interesting near the user right now — new arrivals, local-independent retailers, time-sensitive offers.

Discovery skill rather than search: given only a location, surface products
and stores worth the user's attention *right now*.

## When to use

* User asks "what's around me?" or "anything interesting nearby?"
* Ambient context (weather, time of day, user history) suggests discovery
  rather than targeted search.
* Agent is filling slow time — e.g. user is waiting at a bus stop — and
  wants to show something local.

## Inputs to gather

* `latitude`, `longitude` — required
* `radius_km` — default 2 (hyperlocal; tighter than regular search)
* Optional: category hint ("food", "home goods"), time window

## Flow

### 1. Pull nearby stores

```
GET /locations/api/v1/nearby?lat=...&lon=...&radius_km=2
```

Returns stores with geo distance, categories, and last-updated inventory
timestamps.

### 2. Prioritize

Score each store by a few signals (all optional; use what's available):

* **Local-independent** (not a national chain) — bonus
* **Recently updated inventory** (`last_inventory_sync < 1d`) — bonus
* **New products added this week** — via offer `created` timestamps
* **Popular nearby** — via scan/search activity in the area (when the
  brand-search-demand view exists publicly; today it's brand-scoped only)

### 3. Sample 3-5 noteworthy products per top store

For each top store, get a small sample of offers:

```
GET /retailers/api/v1/organizations/{store_org_id}/in-store-offers?limit=5
```

Prefer items that are new, seasonal, or match category hints. Skip generic
staples unless explicitly relevant.

### 4. Present

Return a short list (3-5 stores, 3-5 products each) with reasons ("new this
week at your local butcher").

## Guidance for agents

* **Tight radius by default** — "nearby" means walkable. Go wider only if
  there's genuinely nothing interesting under 2 km.
* **Novelty over volume** — the user didn't ask for 50 results. 3 excellent
  picks beats 30 mediocre ones.
* **Respect preferences** — don't surface things the user has AVOID stances
  against (meat items to vegans, alcohol to non-drinkers).

## Planned

* Dedicated `GET /search/api/v1/nearby` endpoint returning a curated
  discovery feed server-side.
* "New this week" facet on the search API.

## Related skills

* `local-product-search` — when the user knows *what* they want, use that
* `plan-shopping-trip` — if the user turns discovery into purchase intent