freehire-search: us is a country, not a region (#630)

* freehire-search: us is a country, not a region

The docs and --help listed us as a --region value. In freehire's location
dictionary us is a country code and the region is north_america, so
--region us matched 168 'software engineer' postings against 100008 for
--country us. List the real region vocabulary and send single-country
searches to --country.

* freehire-search: add uk to the region list; fix the README row

* changelog: place the #630 entry under [Unreleased]

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Mads Lorentzen <madslorentzen_17@hotmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

.agents/skills/freehire-search/SKILL.md

@@ -101,7 +101,7 @@ field and drops the bodies entirely (fetch a shortlisted job's body with
 `detail`, or re-run the search without the flag).
 
 Facet filters (values come from freehire's controlled vocabularies; comma-separate for OR within a facet):
-- `--region <codes>` — macro-region, e.g. `global`, `eu`, `us`, `apac`, `latam`, `cis`. `--region eu,us`. Use `none` to match jobs whose region could **not** be resolved (see "Partial data" below).
+- `--region <codes>` - macro-region: `global`, `eu`, `uk`, `north_america`, `latam`, `apac`, `mena`, `africa`, `cis`. `--region eu,uk`. `eu` does not include the UK; add `uk` for Europe as a whole. For a single country use `--country` instead - `us` is a country code, not a region, and `--region us` matches nothing. `--region`, `--country` and `--city` form one OR-group, so `--country us` alone scopes to the US. Use `none` to match jobs whose region could **not** be resolved (see "Partial data" below).
 - `--country <codes>` — ISO-3166 alpha-2, e.g. `--country DE,GB`
 - `--city <names>` — city name(s), e.g. `--city Berlin`
 - `--seniority <levels>` — `junior`, `middle`, `senior`, `staff`, `principal`, `lead`, …

.agents/skills/freehire-search/cli/README.md

@@ -75,7 +75,7 @@ See `../SKILL.md` for the full flag reference and the hosted-dependency note.
 | `--jobage` | | Posted within N days (`posted_within_days`). |
 | `--page` | | 1-indexed page. Default 1. |
 | `--limit` | `-n` | Results per page (API limit). Default 25. |
-| `--region` | | Macro-region(s), comma = OR (e.g. `eu,us`). |
+| `--region` | | Macro-region(s), comma = OR: `global`, `eu`, `uk`, `north_america`, `latam`, `apac`, `mena`, `africa`, `cis` (e.g. `eu,uk`). A country such as `us` goes in `--country`. |
 | `--country` | | ISO-3166 alpha-2 code(s). |
 | `--city` | | City name(s). |
 | `--seniority` | | Seniority level(s). |

.agents/skills/freehire-search/cli/src/cli.ts

@@ -89,7 +89,9 @@ SEARCH FLAGS
                           full description is rendered (json output only).
 
 FACET FILTERS (values from freehire.me's controlled vocabularies; comma = OR)
-  --region <codes>        Macro-region: global, eu, us, apac, latam, cis, ...  e.g. --region eu,us
+  --region <codes>        Macro-region: global, eu, uk, north_america, latam, apac,
+                          mena, africa, cis  e.g. --region eu,uk
+                          (a country such as us goes in --country, not here)
   --country <codes>       ISO-3166 alpha-2, e.g. --country DE,GB
   --city <names>          City name(s), e.g. --city Berlin
   --seniority <levels>    junior, middle, senior, staff, principal, lead, ...

.agents/skills/freehire-search/url-reference.md

@@ -68,7 +68,7 @@ Query parameters used by the skill:
 | `limit` | `--limit` / `-n` | Page size. Default 25 in the CLI. |
 | `offset` | (derived) | `offset = (page - 1) * limit`. |
 | `posted_within_days` | `--jobage` | Restrict to postings from the last N days. |
-| `regions` | `--region` | Repeatable; OR within the facet. Values like `global`, `eu`, `us`, `apac`, `latam`, `cis`. |
+| `regions` | `--region` | Repeatable; OR within the facet. Values: `global`, `eu`, `uk`, `north_america`, `latam`, `apac`, `mena`, `africa`, `cis`. `us` is a country (`countries`), not a region. |
 | `countries` | `--country` | Repeatable; ISO-3166 alpha-2 (lowercased). |
 | `cities` | `--city` | Repeatable; display-name city. |
 | `seniority` | `--seniority` | Repeatable; `junior`, `middle`, `senior`, `staff`, … |

CHANGELOG.md

@@ -45,6 +45,15 @@ per-file diff commands.
   budget fails the request at once with a message naming the requested wait. Giving up on a
   persistent 5xx still takes about 25 s over 7 calls, as before.
 
+- **`freehire-search` docs list the real `--region` buckets and send a country to `--country`**
+  (#630, `.agents/skills/freehire-search/SKILL.md`, `url-reference.md`, `cli/README.md`, `--help`) -
+  the docs and `--help` offered `us` as a region, but in freehire's vocabulary `us` is a country code
+  and the macro-region that holds US postings is `north_america`. `--region us` returned 168
+  software-engineer postings where `--country us` returned about 100,000, with nothing in the output
+  to say why (reported in #616). The docs now list the nine buckets (`global`, `eu`, `uk`,
+  `north_america`, `latam`, `apac`, `mena`, `africa`, `cis`) plus `none`, note that `eu` excludes
+  the UK, and point single-country searches at `--country`.
+
 ## [1.7.3] - 2026-10-19
 
 ### Added