feat(search): add session-backed search filters

README.md

@@ -101,7 +101,7 @@ export KAGI_API_TOKEN='...'
 
 | credential | what it unlocks |
 | --- | --- |
-| `KAGI_SESSION_TOKEN` | base search, `search --lens`, `ask-page`, `assistant`, `summarize --subscriber` |
+| `KAGI_SESSION_TOKEN` | base search fallback, `search --lens`, filtered search, `ask-page`, `assistant`, `summarize --subscriber` |
 | `KAGI_API_TOKEN` | public `summarize`, `fastgpt`, `enrich web`, `enrich news` |
 | none | `news`, `smallweb`, `auth status`, `--help` |
 
@@ -124,7 +124,7 @@ notes:
 - environment variables override `.kagi.toml`
 - base `kagi search` defaults to the session-token path when both credentials are present
 - set `[auth] preferred_auth = "api"` if you want base search to prefer the API path instead
-- `search --lens` always requires `KAGI_SESSION_TOKEN`
+- `search --lens` and all runtime search filters require `KAGI_SESSION_TOKEN`
 - `auth check` validates the selected primary credential without using search fallback logic
 
 for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.dev/reference/auth-matrix) docs page.
@@ -133,8 +133,8 @@ for the full command-to-token matrix, use the [`auth-matrix`](https://kagi.micr.
 
 | command | purpose |
 | --- | --- |
-| `kagi search` | search Kagi with JSON by default or `--format pretty` for terminal output |
-| `kagi batch` | run multiple searches in parallel with JSON, compact, pretty, markdown, or csv output |
+| `kagi search` | search Kagi with JSON by default, optional live filters, or `--format pretty` for terminal output |
+| `kagi batch` | run multiple searches in parallel with JSON, compact, pretty, markdown, or csv output and shared filters |
 | `kagi auth` | inspect, validate, and save credentials |
 | `kagi summarize` | use the paid public summarizer API or the subscriber summarizer with `--subscriber` |
 | `kagi news` | read Kagi News from public JSON endpoints |
@@ -183,6 +183,12 @@ scope search to one of your lenses:
 kagi search --lens 2 "developer documentation"
 ```
 
+run a filtered search against the subscriber web-product path:
+
+```bash
+kagi search --region us --time month --order recency "rust release notes"
+```
+
 run a few searches in parallel:
 
 ```bash

docs/api-coverage.md

@@ -3,7 +3,7 @@
 ## Current support in this CLI
 
 ### Implemented
-- **Search / session-token HTML search** - fully implemented and live-verified for base search and lens-aware search
+- **Search / session-token HTML search** - fully implemented and live-verified for base search, lens-aware search, and runtime search filters (`r`, `dr`, `from_date`, `to_date`, `order`, `verbatim`, `personalized`)
 - **Search / official API-token path** - implemented for base search only; if Kagi rejects the API-token search path, base search falls back to session-token search when available
 - **Universal Summarizer API** - implemented on the documented paid public API path
 - **FastGPT API** - implemented on the documented paid public API path
@@ -35,7 +35,7 @@ This CLI also implements non-public or product-only seams:
 
 ## Notes
 
-- Lens support is not documented on the official Search API. In this CLI it works through Kagi's live HTML/session flow using the `l=<index>` query parameter.
+- Lens support and runtime search filters are not documented on the official Search API. In this CLI they work through Kagi's live HTML/session flow using the `l`, `r`, `dr`, `from_date`, `to_date`, `order`, `verbatim`, and `personalized` query parameters.
 - The official Search API uses `Authorization: Bot <token>` on `https://kagi.com/api/v0/search`.
 - Search API access is still account-gated in practice, and API-token search can also fail for billing reasons.
 - Base-search fallback to session-token search happens on the user-facing `search` command only. `auth check` validates the selected primary credential without fallback.