freehire-search: document the OR and title: operators in -q (#674)

* freehire-search: document the OR and title: operators in -q

freehire's search now parses two operators in q: uppercase OR between
up to five alternatives (a union, filtered and paged as one result),
and a leading title: that restricts an alternative to the job title.
The CLI already passes -q through unchanged, so both work today; this
tells the agent they exist, in SKILL.md, --help, the CLI README and
url-reference.md.

* changelog: place the #674 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

@@ -81,6 +81,7 @@ bun run .agents/skills/freehire-search/cli/src/cli.ts search [-q "<keywords>"] [
 
 Key flags:
 - `--query <text>` / `-q <text>` — keyword search (title, skill, role). Full-text; optional.
+  Supports `OR` and `title:` (see "Query operators" below).
 - `--jobage <days>` — posted within N days (maps to `posted_within_days`).
 - `--page <n>` — 1-indexed page. Default 1.
 - `--limit <n>` / `-n <n>` — results per page (API limit). Default 25.
@@ -89,6 +90,26 @@ Key flags:
   rendered. Default `markdown`, which keeps the posting's headings and requirement
   lists intact. `json` output only.
 
+**Query operators.** `-q` understands two operators; the CLI passes the text through
+unchanged and the API parses it:
+
+- `OR` between alternatives returns jobs matching **any** of them, e.g.
+  `-q "golang OR rust"`. Uppercase only: a lowercase `or` is an ordinary search
+  word. Plain space-separated words are **not** a union (`-q "golang rust"` returns
+  fewer jobs than `-q golang` alone), so use `OR` for synonyms and alternative stacks
+  instead of running one search per keyword. At most 5 alternatives; a 6th is
+  rejected with an error. An `OR` inside double quotes is literal text.
+- A leading `title:` restricts that alternative to the job **title**, e.g.
+  `-q "title:staff engineer"` skips postings that merely mention the words in their
+  description. It applies per alternative, so repeat it on each one:
+  `-q "title:staff engineer OR title:principal engineer"`. It only counts at the start
+  of an alternative; `title:` in the middle is searched as text. Quotes work inside it:
+  `-q 'title:"staff engineer"'` matches the phrase.
+
+Facet flags, `--jobage`, `--page` and `--limit` apply to the combined result: every
+alternative is filtered the same way, and a job matching several alternatives
+appears once.
+
 **Search results already carry the full description.** This skill queries freehire's
 agent search endpoint, which replaces the index's truncated preview with each
 posting's complete text, so a search of 20 roles is 1 request rather than 1 + 20.
@@ -139,6 +160,12 @@ just returned only re-reads a description you already have.
 # Senior backend roles, table view
 bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "backend engineer" --seniority senior --limit 10 --format table
 
+# Go or Rust roles, one search (OR must be uppercase)
+bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "golang OR rust" --remote remote --format table
+
+# Staff or principal titles only, not postings that mention them in passing
+bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "title:staff engineer OR title:principal engineer" --format table
+
 # Remote React roles in the EU
 bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "react" --remote remote --region eu --format table
 

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

@@ -74,7 +74,7 @@ See `../SKILL.md` for the full flag reference and the hosted-dependency note.
 
 | Flag | Alias | Description |
 |------|-------|-------------|
-| `--query` | `-q` | Keywords (title / skill / role). Full-text; optional. |
+| `--query` | `-q` | Keywords (title / skill / role). Full-text; optional. `a OR b` matches either (uppercase `OR`, max 5 alternatives); a leading `title:` searches the job title only. |
 | `--jobage` | | Posted within N days (`posted_within_days`). |
 | `--page` | | 1-indexed page. Default 1. |
 | `--limit` | `-n` | Results per page (API limit). Default 25. |

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

@@ -79,6 +79,8 @@ USAGE
 
 SEARCH FLAGS
   --query, -q <text>      Keywords (title, skill, role). Full-text; optional.
+                          "a OR b" matches either (uppercase OR, max 5);
+                          a leading title: searches the job title only.
   --jobage <days>         Posted within N days (maps to posted_within_days).
   --page <n>              1-indexed page. Default 1.
   --limit, -n <n>         Results per page (API limit). Default 25.

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

@@ -64,7 +64,7 @@ Query parameters used by the skill:
 
 | Param | Maps to CLI flag | Notes |
 |-------|------------------|-------|
-| `q` | `--query` / `-q` | Keyword full-text query. |
+| `q` | `--query` / `-q` | Keyword full-text query. Uppercase `OR` separates up to 5 alternatives (more is a 400); a leading `title:` restricts an alternative to the title. |
 | `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. |

CHANGELOG.md

@@ -13,6 +13,15 @@ per-file diff commands.
 
 ## [Unreleased]
 
+### Changed
+
+- **`freehire-search` documents the `OR` and `title:` query operators** (#674,
+  `.agents/skills/freehire-search/SKILL.md`, `url-reference.md`, `cli/README.md`, `--help`) -
+  freehire's search parses an uppercase `OR` between up to five alternatives and a leading `title:`
+  per alternative, but nothing told the agent, so "Go or Rust" became two searches merged by hand
+  or `-q "golang rust"`, which returns fewer jobs than `golang` alone. Measured live: `golang`
+  3,550, `golang OR rust` 6,805. The CLI already passes `-q` through unchanged.
+
 ### Fixed
 
 - **`freehire-search detail` no longer asks the API for a slug cut out of a URL on another