askaipods 0.2.3 → 0.2.5

package/README.md

@@ -7,7 +7,7 @@ $ askaipods "what are people saying about test-time compute"
 
 # askaipods · "what are people saying about test-time compute"
 
-*Tier: anonymous · Results: 20 · Quota: 1/10 daily*
+*Tier: anonymous · Results: 20 · Quota: 1/20 daily*
 
 ## Results — newest first
 
@@ -60,12 +60,12 @@ Then copy or symlink the `skill/askaipods/` directory into your agent's skills f
 | Runtime | Skill folder | Install guide |
 |---|---|---|
 | Claude Code | `~/.claude/skills/askaipods/` | [examples/claude-code-install.md](examples/claude-code-install.md) |
-| OpenAI Codex CLI | `~/.agents/skills/askaipods/` ✨ | [examples/codex-install.md](examples/codex-install.md) |
-| OpenClaw | `~/.agents/skills/askaipods/` ✨ or `~/.openclaw/skills/askaipods/` | [examples/openclaw-install.md](examples/openclaw-install.md) |
+| OpenAI Codex CLI | `~/.codex/skills/askaipods/` (or `$CODEX_HOME/skills/askaipods/`; project-scoped: `.agents/skills/askaipods/`) | [examples/codex-install.md](examples/codex-install.md) |
+| OpenClaw | `~/.agents/skills/askaipods/` or `~/.openclaw/skills/askaipods/` | [examples/openclaw-install.md](examples/openclaw-install.md) |
 | Hermes Agent | `~/.hermes/skills/askaipods/` | [examples/hermes-install.md](examples/hermes-install.md) |
 | Any other agentskills.io-compatible runtime | per runtime docs | follow the agentskills.io standard — copy `skill/askaipods/` into your agent's skills directory |
 
-✨ **Two-for-one tip**: Codex CLI and OpenClaw both read from `~/.agents/skills/`, so a single install at `~/.agents/skills/askaipods/` covers both runtimes simultaneously.
+**Per-runtime paths matter**: Codex CLI loads user-level skills from `~/.codex/skills/` (per the [official Codex skills docs](https://developers.openai.com/codex/skills)); project-scoped skills live under `.agents/skills/` in the repository and are discovered via workspace walk. OpenClaw typically reads from `~/.agents/skills/` or `~/.openclaw/skills/`. These paths are NOT interchangeable — install into each runtime's expected location.
 
 The skill folder is self-contained: it tells the host agent how to invoke `askaipods` (via `npx`), how to parse the JSON, and how to render the response with an **Insights** section. The section layout is tier-dependent — member tier renders **Latest 5** + **Top 5 Most Relevant** + **Insights**; anonymous tier renders **Recent Quotes** + **Insights** (the "Top Relevant" section is suppressed for anonymous because the API returns results sorted by date, not by semantic relevance).
 
@@ -83,7 +83,7 @@ askaipods "Anthropic safety research" --format json
 # Restrict to recent episodes only (anonymous tier caps --days at 90; member tier accepts any value)
 askaipods "GPU shortage" --days 90
 
-# Use a member-tier API key for 50/day instead of 10/day
+# Use a member-tier API key for 100/day instead of 20/day
 ASKAIPODS_API_KEY=pk_xxx askaipods "your query"
 askaipods "your query" --api-key pk_xxx
 ```
@@ -100,15 +100,15 @@ Your agent will recognize the trigger phrase, invoke `askaipods`, and present th
 
 | | Anonymous (default) | Member |
 |---|---|---|
-| **Daily quota** | 10 searches per IP | 50 searches per user |
-| **Results returned** | 20 (deterministic top 20, sorted newest-first) | 20 (deterministic top 20, sorted by relevance) |
+| **Daily quota** | 20 searches per IP | 100 searches per user |
+| **Results returned** | Top 20 newest (API returns newest-first; `api_rank` = temporal order) | Top 20 by semantic relevance (structured output is emitted newest-first; semantic rank preserved in `api_rank`) |
 | **Text length** | Full text | Full text |
 | **Date precision** | Month only (`2025-10`) | Full date (`2025-10-15`) |
 | **`--days` cap (when specified)** | 90 days | Unlimited |
 | **Setup** | Nothing | `ASKAIPODS_API_KEY` env var |
-| **Sign up** | n/a | https://podlens.net |
+| **Access** | n/a | invite-only · request at https://podlens.net |
 
-The anonymous tier exists so you can try the skill end-to-end with zero setup. Sign up for member access only when you outgrow the 10/day quota or need full dates and unlimited lookback.
+The anonymous tier exists so you can try the skill end-to-end with zero setup. Member access is currently invite-only — request access at https://podlens.net (you'll be added to the waitlist for review) only if you outgrow the 20/day quota or need full dates and unlimited lookback.
 
 ## Honest limitations
 

package/examples/claude-code-install.md

@@ -39,13 +39,13 @@ Or trigger it organically:
 
 > What are people saying about test-time compute on AI podcasts?
 
-Claude Code should recognize the trigger phrase, run `npx askaipods search "..." --format json`, parse the response, and render the structured results per the SKILL.md template (layout is tier-dependent — member tier shows Latest + Top Relevant + Insights; anonymous tier shows Recent Quotes + Insights).
+Claude Code should recognize the trigger phrase, run `npx -y askaipods search --format json -- "..."` (argv-style per SKILL.md's invocation rule), parse the response, and render the structured results per the SKILL.md template (layout is tier-dependent — member tier shows Latest + Top Relevant + Insights; anonymous tier shows Recent Quotes + Insights).
 
 ## Troubleshooting
 
 - **Skill not appearing**: Make sure the parent directory name matches the `name` field in `SKILL.md` (both must be `askaipods`).
 - **`npx askaipods` fails**: Check that Node.js 18.3.0+ is installed: `node --version`. The CLI uses zero dependencies so there are no other prereqs.
-- **Anonymous quota exhausted**: Sign up at https://podlens.net for 50/day, then `export ASKAIPODS_API_KEY=pk_xxx`.
+- **Anonymous quota exhausted**: Member tier is invite-only — request access at https://podlens.net, then once invited `export ASKAIPODS_API_KEY=pk_xxx` for 100/day.
 - **Skill triggers too rarely**: Front-load your prompt with the trigger phrases in `SKILL.md` description, or invoke directly with `/askaipods <query>`.
 
 ## Reference

package/examples/codex-install.md

@@ -1,6 +1,6 @@
 # Install askaipods in OpenAI Codex CLI
 
-Codex CLI typically looks in `~/.agents/skills/` (user-level) and `.agents/skills/` (project / repo level). Project-scoped skills win over user-scoped when both exist with the same name. For the authoritative scope list and any system-level paths your installed version supports, consult the [official Codex skills documentation](https://developers.openai.com/codex/skills/).
+Codex CLI loads user-level skills from `~/.codex/skills/` (or `$CODEX_HOME/skills/` if the env var is set) and project-scoped skills from `.agents/skills/` within the repository workspace. When both scopes carry the same skill name, repository-scoped wins. For the authoritative scope list and any system-level paths your installed version supports, consult the [official Codex skills documentation](https://developers.openai.com/codex/skills).
 
 For most users, the **user-level** install is what you want — it makes `askaipods` available across every project.
 
@@ -8,14 +8,14 @@ For most users, the **user-level** install is what you want — it makes `askaip
 
 ```bash
 git clone https://github.com/Delibread0601/askaipods.git ~/Code/askaipods
-mkdir -p ~/.agents/skills
-ln -s ~/Code/askaipods/skill/askaipods ~/.agents/skills/askaipods
+mkdir -p ~/.codex/skills
+ln -s ~/Code/askaipods/skill/askaipods ~/.codex/skills/askaipods
 ```
 
 Symlink (above) is recommended so `git pull` updates flow through automatically. Or copy:
 
 ```bash
-cp -r ~/Code/askaipods/skill/askaipods ~/.agents/skills/askaipods
+cp -r ~/Code/askaipods/skill/askaipods ~/.codex/skills/askaipods
 ```
 
 ## Project-only install
@@ -33,7 +33,7 @@ In Codex, ask:
 
 > What are people saying about reasoning models on AI podcasts?
 
-Codex should detect the trigger, run `npx askaipods search "..." --format json`, and render the structured response per `SKILL.md`.
+Codex should detect the trigger, run `npx -y askaipods search --format json -- "..."`, and render the structured response per `SKILL.md`.
 
 ## Troubleshooting
 

package/examples/hermes-install.md

@@ -22,7 +22,7 @@ In a Hermes session, ask:
 
 > Find what AI podcasts are saying about test-time compute
 
-Hermes should pick up the skill from `~/.hermes/skills/askaipods/`, shell out to `npx askaipods`, and present the structured results.
+Hermes should pick up the skill from `~/.hermes/skills/askaipods/`, shell out to `npx -y askaipods ...` (argv-style per SKILL.md's invocation rule), and present the structured results.
 
 ## Troubleshooting
 

package/examples/openclaw-install.md

@@ -4,24 +4,26 @@
 
 1. `<workspace>/skills/` — workspace skills (highest)
 2. `<workspace>/.agents/skills/` — project agent skills
-3. `~/.agents/skills/` — personal agent skills (shared with OpenAI Codex CLI)
+3. `~/.agents/skills/` — personal agent skills
 4. `~/.openclaw/skills/` — managed/local skills (shared across all agents on the machine)
 
-For most users, **option 3 is the best choice** because the same `~/.agents/skills/askaipods/` install also makes the skill available in OpenAI Codex CLI — one install, two runtimes.
+> **Note**: An earlier version of this guide claimed `~/.agents/skills/` was shared with OpenAI Codex CLI. That was incorrect — Codex CLI reads user-level skills from `~/.codex/skills/` per the [official Codex skills docs](https://developers.openai.com/codex/skills). If you also use Codex CLI, install askaipods into `~/.codex/skills/askaipods/` separately (see [examples/codex-install.md](codex-install.md)).
 
-## Recommended install (shared with Codex)
+## Recommended install
+
+Install into the OpenClaw-native location (option 4 — lowest precedence, but stable across agent versions):
 
 ```bash
 git clone https://github.com/Delibread0601/askaipods.git ~/Code/askaipods
-mkdir -p ~/.agents/skills
-ln -s ~/Code/askaipods/skill/askaipods ~/.agents/skills/askaipods
+mkdir -p ~/.openclaw/skills
+ln -s ~/Code/askaipods/skill/askaipods ~/.openclaw/skills/askaipods
 ```
 
-If you don't already use Codex and prefer to keep OpenClaw skills separate, install into the OpenClaw-native location instead:
+Or use the shared personal-skills location (option 3) if you want the skill visible to every agentskills.io-compatible runtime that respects the `~/.agents/skills/` convention:
 
 ```bash
-mkdir -p ~/.openclaw/skills
-ln -s ~/Code/askaipods/skill/askaipods ~/.openclaw/skills/askaipods
+mkdir -p ~/.agents/skills
+ln -s ~/Code/askaipods/skill/askaipods ~/.agents/skills/askaipods
 ```
 
 Or use the OpenClaw CLI once askaipods is published to the ClawHub registry (not yet — check back, or open an issue to track):
@@ -47,7 +49,7 @@ In OpenClaw, ask:
 
 > What are AI podcasts saying about reasoning models?
 
-OpenClaw should recognize the trigger phrase, shell out to `npx askaipods search "..." --format json`, and render the structured response per the SKILL.md template.
+OpenClaw should recognize the trigger phrase, shell out to `npx -y askaipods search --format json -- "..."` (argv-style per SKILL.md's invocation rule), and render the structured response per the SKILL.md template.
 
 ## Troubleshooting
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askaipods",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Search AI podcast quotes by topic — recent episode excerpts from Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens more. Universal agentskills.io skill compatible with Claude Code, OpenAI Codex, Hermes Agent, OpenClaw, and any other agent that supports the open skill standard. Powered by podlens.net.",
   "type": "module",
   "bin": {

package/skill/askaipods/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: askaipods
-description: Search AI podcast quotes about a topic. Use whenever the user asks "what are people saying about X", "latest takes on Y", "find AI podcast quotes about Z", "who is discussing <model/concept>", or wants to know how AI researchers, founders, or VCs are publicly discussing any AI topic — even when they don't say "podcast". Returns recent excerpts from real episodes of Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens more, sorted newest-first via the podlens.net semantic search API. Trigger eagerly on AI-research, ML-engineering, AI-investing, or AI-policy questions where real-human commentary beats a web search summary. Do not use for general web search, full transcript reading, or non-AI topics.
+description: Search AI podcast quotes about a topic. Use whenever the user asks "what are people saying about X", "latest takes on Y", "find AI podcast quotes about Z", "who is discussing <model/concept>", or wants to know how AI researchers, founders, or VCs are publicly discussing any AI topic — even when they don't say "podcast". Returns recent excerpts from Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens more via podlens.net. Optional ASKAIPODS_API_KEY unlocks invite-only member tier; anonymous works out of the box.
 license: MIT
-requirements: Node.js 18.3.0+ on PATH (the CLI uses `node:util.parseArgs`, which was added in 18.3.0), internet access to podlens.net. Optional ASKAIPODS_API_KEY env var unlocks the 50/day member tier with full dates and unlimited lookback; without it the skill works on the 10/day anonymous tier (per-IP, month-precision dates, `--days` capped at 90 when specified).
+requirements: Node.js 18.3.0+ on PATH (the CLI uses `node:util.parseArgs`, which was added in 18.3.0), internet access to podlens.net. Optional ASKAIPODS_API_KEY env var unlocks the 100/day member tier with full dates and unlimited lookback (member tier is invite-only — request access at https://podlens.net); without the key the skill works on the 20/day anonymous tier (per-IP, month-precision dates, `--days` capped at 90 when specified).
 ---
 
 # askaipods — AI podcast quote search
@@ -37,24 +37,34 @@ You may invoke even when the user does not say "podcast" — if the question is
 
 Run the bundled CLI and pass `--format json`. The flag matters because without it the CLI auto-detects the output format from `isTTY`, and an agent calling via shell may or may not get a TTY depending on the runtime — explicit `--format json` removes that variability.
 
+> **CRITICAL — argv-safety rule**: pass the user's query as a **separate argv argument**, never splice it directly into a shell command string. A query like `"; rm -rf ~` spliced into `bash -c "npx askaipods \"$QUERY\""` is a command-injection path. Runtimes that support argv-array execution (Claude Code's `Bash` tool, Codex CLI shell invocations, most SDK-based agents) must use that form. Runtimes that only support shell strings must apply proper shell-quoting (e.g., Node's `shell-quote` or `printf %q`) before interpolation. The `--` separator also guarantees the query is treated as a positional argument regardless of leading characters.
+
+Argv-array form (preferred for agent use):
+
+```
+["npx", "-y", "askaipods", "search", "--format", "json", "--", "<USER QUERY>"]
+```
+
+Shell-string form (only when argv is unavailable AND the query has been properly shell-quoted — do NOT use raw string interpolation):
+
 ```bash
-npx askaipods search "<USER QUERY>" --format json
+npx -y askaipods search --format json -- "<USER QUERY>"
 ```
 
-The `search` subcommand is optional — `npx askaipods "<USER QUERY>" --format json` works identically. Both forms are supported; use whichever reads better in context.
+The `-y` flag bypasses npm's first-run confirmation prompt; without it, a non-interactive runtime may hang on first use waiting for a TTY response that never comes (audit R7-03). The package is published on npm as `askaipods`, so `npx -y` resolves it regardless of whether the user has it installed globally. If `npx` is unavailable in the host environment, the user can install once with `npm install -g askaipods` and run `askaipods` directly.
 
-The package is published on npm as `askaipods`, so `npx` will resolve it regardless of whether the user has it installed globally. If `npx` is unavailable in the host environment, the user can install globally once with `npm install -g askaipods` and the skill will run the same command.
+The `search` subcommand is optional — `npx -y askaipods --format json -- "<USER QUERY>"` works identically. Both forms are supported; use whichever reads better in context.
 
-To restrict to recent episodes only, add `--days N`. When `--days` is passed, the API clamps the value to a maximum of 90 for anonymous tier (member tier accepts any value). When `--days` is omitted entirely, there is no time filter — the API returns all-time results.
+To restrict to recent episodes only, add `--days N`. When `--days` is passed, the server caps the value at 90 for anonymous tier (member tier accepts any value). When `--days` is omitted entirely, there is no time filter — the server returns all-time results.
 
 ```bash
-npx askaipods search "<USER QUERY>" --days 90 --format json
+npx -y askaipods search --days 90 --format json -- "<USER QUERY>"
 ```
 
 To authenticate with a PodLens API key (member tier), pass `--api-key <key>` or set the `ASKAIPODS_API_KEY` environment variable. The flag takes priority over the env var when both are present.
 
 ```bash
-npx askaipods search "<USER QUERY>" --api-key pk_abc123... --format json
+npx -y askaipods search --api-key pk_abc123... --format json -- "<USER QUERY>"
 ```
 
 The query must be 1–300 characters after trimming. Longer queries are rejected locally (exit code 1) before reaching the API.
@@ -96,10 +106,19 @@ Do NOT silently default every query to `--days 90` — omitting `--days` on broa
   ],
   "meta": {
     "total_returned": 20,
-    "quota": { "used": 3, "limit": 50, "period": "daily" },
+    "quota": { "used": 3, "limit": 100, "period": "daily", "next_reset": "2026-04-21T00:00:00Z" },
     "restrictions": null,
     "query_hash": "...",
-    "window": { "requested_days": 7, "served_days": 30, "expanded": true, "reason_code": "expanded_on_empty_window" }
+    "window": {
+      "requested_days": 7,
+      "served_days": 30,
+      "expanded": true,
+      "attempted_days": [7, 30],
+      "reason_code": "expanded_topk_filled"
+    },
+    "corpus_freshness": { "newest_date": "2026-04-18" },
+    "warning": null,
+    "cta": null
   }
 }
 ```
@@ -112,9 +131,27 @@ Field notes that affect how you render:
 - **`results[]`** — already sorted **newest first** by the CLI. Each result carries `api_rank` (1 = most semantically relevant in API order) so you can derive a "Top Relevant" sub-view without re-querying.
 - **`results[].podcast` / `episode` / `date`** — any of these may be `null` if the upstream record is incomplete. Render `Unknown podcast` / `Untitled episode` / `date unknown` rather than dropping the result. The CLI's own markdown renderer falls back the same way.
 - **`results[].date` format** — `YYYY-MM-DD` (or full ISO timestamp) for member tier; `YYYY-MM` only for anonymous tier (deliberately fuzzed by the API). Display whatever you got — don't guess a day.
-- **`meta.quota`** — passed through from the podlens.net API. Sub-fields like `used`, `limit`, `period` are reliably present; other sub-fields (e.g., a reset timestamp) may or may not appear depending on the server version. Treat all sub-fields as optional and degrade gracefully.
+- **`meta.quota`** — passed through from the podlens.net API. `used` and `limit` are guaranteed present (the CLI validates them as part of the success envelope); `period` is typically `"daily"`, `next_reset` is an ISO-8601 timestamp, and **`refunded`** (optional boolean) — when present and `true`, the server refunded this request's quota slot under its P1-b narrow-refund rule (triggered when the corpus is stale for the requested window AND zero results were delivered). The field is often absent; check with `quota.refunded === true` rather than `typeof quota.refunded === "boolean"`. When set, mention in the response that the search didn't count against the user's quota — it's a transparency signal worth surfacing.
 - **`meta.restrictions`** — `null` for member tier; for anonymous tier, an object describing the cap (e.g., `{ max_results: 20, text_truncated: false, results_randomized: false, date_precision: "month", max_days: 90, order: "published_at_desc" }`). If non-null, the closing anonymous-tier note (templated below) is the right way to surface it; do not parse the object field-by-field.
-- **`meta.window`** — present when the API includes window expansion metadata (may be `null` for older server versions). When the user passes `--days` and the requested window has no results, the API automatically retries with wider windows (`[30, 60, 90]` days). The `window` object contains: `requested_days` (what was asked), `served_days` (what actually returned results), `expanded` (boolean — `true` when the window was widened), `reason_code` (`"expanded_on_empty_window"` when expanded), and optionally `truncated` (`true` when a fallback query errored mid-expansion). **When `expanded` is `true`**, tell the user: "No results in the requested N-day window; showing results from the last M days" (using `requested_days` and `served_days`). When `expanded` is `false` and results are empty, the API tried all available windows and genuinely found nothing.
+- **`meta.window`** — present when the API includes window expansion metadata (may be `null` for older server versions). When the user passes `--days` and the requested window has no results, the API automatically retries with wider windows (`[30, 60, 90]` days). The `window` object contains:
+  - `requested_days` — what the client asked for.
+  - `served_days` — the last window actually attempted. When `expanded` is `true`, results came from that wider window.
+  - `expanded` — `true` when more than one window was attempted (regardless of whether any succeeded).
+  - `attempted_days` — array of every window queried, in order (e.g. `[7, 30, 60]`); diagnostic, safe to ignore for rendering.
+  - `reason_code` — one of three values, present only when `expanded` is `true` AND `truncated` is absent:
+    - `"expanded_topk_filled"` — wider windows tried AND delivered the full topK (20).
+    - `"expanded_partial_fill"` — wider windows tried AND delivered some but fewer than topK results.
+    - `"exhausted_windows_empty"` — wider windows tried AND delivered nothing.
+  - `truncated` — `true` when a fallback query errored mid-expansion, aborting further windows. When present, `reason_code` is suppressed.
+
+  **When `expanded` is `true` AND results were delivered**, tell the user: "No results in the requested N-day window; showing results from the last M days" (using `requested_days` and `served_days`). When `expanded` is `true` AND results are empty, the API tried all available windows and genuinely found nothing — prefer checking `meta.warning` first for a freshness-aware message before falling back to generic "no results" copy.
+- **`meta.corpus_freshness`** — `{ "newest_date": "YYYY-MM-DD" | null }`. The latest `published_at` indexed in the corpus. Use it as an honest "data as of X" signal, especially when results are empty and `meta.warning` indicates a stale corpus. `null` when the corpus-freshness probe failed server-side — render "date unknown" rather than omitting.
+- **`meta.warning`** — `null` in the common case. When present, an object `{ "code": "..." }` signalling an honest server-side explanation for an empty or partial response:
+  - `"corpus_stale_for_requested_window"` — the user bounded the search with `--days` but the newest indexed episode predates that window's cutoff. Tell the user: "No episodes indexed in the requested window (newest indexed episode: `<corpus_freshness.newest_date>`). Try a longer `--days` value or omit it." **Do NOT** suggest rephrasing the query — the cause is freshness, not semantics.
+  - `"index_metadata_stale"` — fresh episodes exist in the corpus but haven't propagated to the Vectorize index yet. Tell the user: "Recently indexed episodes are still propagating — retry in a few minutes."
+
+  These warnings mean an empty or near-empty result is an infrastructure signal, not a semantic-relevance signal — they take precedence over `window.expanded`/`truncated` messaging when both apply.
+- **`meta.cta`** — anonymous-tier call-to-action from the server (e.g., `{ follow: "https://x.com/..." }`) or `null`. Optional context for the closing anonymous-tier note; safe to ignore if you're already rendering the standard closing note.
 - **No speaker name and no episode URL.** The corpus is indexed at the key-point level without per-speaker attribution (the upstream pipeline intentionally avoids attributing quotes to individuals because automatic speaker diarization is unreliable). Episode URLs are also not exposed by the public API. Render `Podcast — Episode` only; do not fabricate "Dario said" if the text doesn't already attribute itself.
 
 ## How to render the response
@@ -123,6 +160,14 @@ Output exactly this structure. It is required for consistency across runtimes
 
 (Note: the CLI's own `--format markdown` output uses a different layout — `### N. Podcast — Episode` headings — because that mode targets humans running `askaipods` directly in a terminal. As an agent you should always pass `--format json` and reformat the parsed payload yourself per the templates below; do not copy the CLI's markdown.)
 
+**Freshness banner rule (applies to every render path below, regardless of result count)**: before the first section heading, if `meta.warning` is non-null, emit a one-line italicized note:
+
+- `meta.warning.code === "corpus_stale_for_requested_window"` AND results are present → `*Note: The indexed corpus has no episodes in the requested window (newest indexed episode: <meta.corpus_freshness.newest_date>) — results below may come from an expanded window. Consider omitting --days for broader coverage.*`
+- `meta.warning.code === "index_metadata_stale"` AND results are present → `*Note: Recently indexed episodes are still propagating to the search index — some relevant matches may be missing. Retry in a few minutes for complete coverage.*`
+- `meta.warning.code` is set to any other value AND results are present (forward-compat for future server codes) → `*Note: Server flagged a freshness concern with this search (code: <meta.warning.code>) — results may be incomplete.*`
+
+The banner is mandatory whenever `meta.warning` is non-null and the response is rendered — an unannotated partial result misrepresents the corpus state as authoritative. For empty-result renders, the equivalent freshness copy replaces the "no results" message per the §Error handling priority ladder (do not stack both).
+
 ### For `render_hint: "dual_view"` (member tier)
 
 ```markdown
@@ -142,7 +187,9 @@ Output exactly this structure. It is required for consistency across runtimes
 
 2. ...
 
-(these 5 are the results with `api_rank` 1 through 5, regardless of date — pull them from the `results` array by filtering on `api_rank`, **then sort ascending by `api_rank`** so rank 1 appears first. The `results` array is sorted newest-first, so a naive filter would leave these in date order instead of rank order.)
+(these 5 are the results with `api_rank` 1 through 5, regardless of date. Pull them from the `results` array by filtering on `api_rank`.
+
+**Then sort ascending by `api_rank`** so rank 1 appears first — the `results` array is sorted newest-first, so a naive filter without re-sorting would leave these in date order instead of rank order.)
 
 ## 💡 Insights
 
@@ -174,7 +221,7 @@ If the same result appears in both Latest and Top Relevant sections, that's fine
 
 ---
 
-*Anonymous tier: 20 results sorted newest-first, dates fuzzed to month, `--days` capped at 90 when specified. Set `ASKAIPODS_API_KEY` for 50 searches/day with full dates and unlimited lookback — sign up at https://podlens.net.*
+*Anonymous tier: 20 results sorted newest-first, dates fuzzed to month, `--days` capped at 90 when specified. Set `ASKAIPODS_API_KEY` for 100 searches/day with full dates and unlimited lookback — member tier is invite-only, request access at https://podlens.net.*
 ```
 
 The closing note about the anonymous tier matters because it tells the user (a) why the dates are coarse, (b) what the lookback cap is, and (c) what the upgrade path is. Skipping it leaves the user wondering why dates lack day precision.
@@ -209,10 +256,17 @@ The CLI uses stable exit codes so you can branch on the failure mode:
 | `2` | Daily quota exhausted | Surface the CLI's stderr message verbatim — it is already tier-aware (distinct copy for member vs anonymous) and includes the correct reset time and upgrade path. |
 | `3` | Transient or unexpected failure (network error, rate-limit burst, service 503, protocol/shape error, or internal exception) | Retry once after a brief pause. If it fails again, surface the CLI's stderr message verbatim — it distinguishes "rate limited, retry in a minute" from "podlens.net temporarily unavailable" from "unexpected response shape" from internal exceptions, so the user sees the actionable detail. |
 
-If the `results` array is empty (zero matches above the similarity threshold), check `meta.window` first:
-- If `meta.window.expanded` is `true`: the API already widened the search window (e.g., from 7 to 30 days) and still found nothing — tell the user: "No quotes found. The API expanded the search from N to M days but found no matches. Try rephrasing or broadening the query."
-- If `meta.window.truncated` is `true`: the expansion was interrupted by a transient error — tell the user to retry in a moment.
-- Otherwise (no expansion, or `meta.window` is `null`): say "No quotes found for that topic. The corpus is AI-focused — for non-AI topics, try a web search instead. For AI topics, try rephrasing or broadening the query."
+If the `results` array is empty (zero matches above the similarity threshold), check the honesty signals in this priority order — freshness warnings dominate because they tell the user something stronger than "rephrase your query":
+
+1. **`meta.warning.code === "corpus_stale_for_requested_window"`** — corpus has no indexed episodes in the requested window. Tell the user: "No episodes indexed in the requested window (newest indexed episode: `<meta.corpus_freshness.newest_date>`). Try a longer `--days` value or omit it." Do NOT suggest rephrasing the query.
+2. **`meta.warning.code === "index_metadata_stale"`** — fresh episodes exist but haven't propagated to the vector index. Tell the user: "Recently indexed episodes are still propagating to the search index — retry in a few minutes."
+3. **`meta.warning.code` is set to any other value** (forward-compat for future server codes) — preserve the signal rather than falling through. Tell the user: "No results. The server flagged a freshness issue with this search (code: `<meta.warning.code>`) — results may be incomplete or the requested window may be stale. Try omitting `--days` or retry in a few minutes."
+4. **`meta.window.truncated === true`** — the expansion was interrupted by a transient error. Tell the user to retry in a moment.
+5. **`meta.window.expanded === true`** — the API widened the window (e.g., 7→30 days) and still found nothing. Tell the user: "No quotes found. The API expanded the search from N to M days but found no matches. Try rephrasing or broadening the query." If `meta.corpus_freshness.newest_date` is present, append "(corpus indexed through `<newest_date>`)" as an honest data-freshness signal.
+6. **Otherwise** (no warning, no expansion): say "No quotes found for that topic. The corpus is AI-focused — for non-AI topics, try a web search instead. For AI topics, try rephrasing or broadening the query."
+
+If `meta.quota.refunded === true`, add a one-line note at the end: "_This search was refunded — it did not count against your daily quota._" (The server's P1-b narrow-refund rule fires when the corpus is stale for the requested window AND zero results are delivered.)
+
 Do not invent quotes to fill the gap.
 
 Never silently swallow an error. Never fabricate quotes when the API returns nothing.

package/src/cli.js

@@ -14,7 +14,7 @@ import { parseArgs } from "node:util";
 import { search, AskaipodsError } from "./client.js";
 import { renderJson, renderMarkdown } from "./format.js";
 
-const VERSION = "0.2.3";
+const VERSION = "0.2.5";
 
 const HELP_TEXT = `askaipods ${VERSION} — search AI podcast quotes by topic
 
@@ -30,9 +30,9 @@ OPTIONS:
   -v, --version              Show version
 
 ENVIRONMENT:
-  ASKAIPODS_API_KEY          PodLens API key. Without it: 10 searches/day per IP (anonymous).
-                             With it: 50 searches/day per user (member).
-                             Sign up at https://podlens.net to get one.
+  ASKAIPODS_API_KEY          PodLens API key. Without it: 20 searches/day per IP (anonymous).
+                             With it: 100 searches/day per user (member).
+                             Member tier is invite-only — request access at https://podlens.net.
 
 EXIT CODES:
   0  success
@@ -87,8 +87,22 @@ export async function run(argv) {
   // operation today and adding it as a flag-free first positional means
   // future subcommands (e.g., `askaipods quota`) won't break the v0
   // muscle memory.
+  //
+  // Only strip "search" as a subcommand when there are additional
+  // positionals after it (audit R6-02). Treating a lone `search`
+  // positional as a subcommand would produce a misleading "missing
+  // query" error for the plausible case `askaipods search` (user
+  // typed the subcommand name expecting an interactive prompt); and
+  // stripping a leading `search` from a multi-word unquoted query
+  // like `askaipods search engines and AI` would silently drop the
+  // first word without the user noticing. The refined rule: if the
+  // user types exactly one positional equal to "search", treat it as
+  // the literal one-word query "search" rather than a subcommand
+  // with missing argument. For multi-word queries beginning with the
+  // literal word "search", the user should quote:
+  // `askaipods "search engines and AI"`.
   let query;
-  if (positionals[0] === "search") {
+  if (positionals[0] === "search" && positionals.length > 1) {
     query = positionals.slice(1).join(" ").trim();
   } else {
     query = positionals.join(" ").trim();

package/src/client.js

@@ -97,10 +97,24 @@ function isValidPublishedAt(v) {
 //   data.meta.quota.used       : finite number
 //   data.meta.quota.limit      : finite number
 //
-// Optional (kept loose on purpose):
+// Optional (kept loose on purpose unless they affect render logic):
 //   data.meta.quota.period, data.meta.quota.next_reset,
-//   data.meta.query_hash, data.meta.restrictions, data.meta.cta,
-//   data.meta.window
+//   data.meta.query_hash, data.meta.restrictions, data.meta.window
+//
+// Optional but shape-checked because they drive conditional render
+// branches in format.js — a malformed value would let the bad state
+// silently cross the exit-0 / exit-3 boundary:
+//   data.meta.quota.refunded    — boolean iff present (drives header
+//                                 "· refunded" tag in renderMarkdown)
+//   data.meta.warning           — {code: string} iff present (drives
+//                                 empty-result priority ladder and the
+//                                 freshness banner in non-empty render)
+//   data.meta.corpus_freshness  — {newest_date: string|null} iff present
+//                                 (the "data as of X" signal)
+//   data.meta.cta               — object iff present (passthrough only,
+//                                 no render logic depends on its shape,
+//                                 but reject non-object so downstream
+//                                 type assumptions hold)
 function isValidSuccessEnvelope(data) {
   if (!isPlainObject(data)) return false;
   if (typeof data.total !== "number" || !Number.isFinite(data.total)) return false;
@@ -124,6 +138,98 @@ function isValidSuccessEnvelope(data) {
   if (!isPlainObject(q)) return false;
   if (typeof q.used !== "number" || !Number.isFinite(q.used)) return false;
   if (typeof q.limit !== "number" || !Number.isFinite(q.limit)) return false;
+  // quota.refunded is optional; when present it MUST be boolean. A
+  // string like "yes" would truthy-trigger the "· refunded" tag in
+  // format.js renderMarkdown header, claiming a refund that didn't
+  // happen.
+  if (q.refunded !== undefined && typeof q.refunded !== "boolean") return false;
+  // warning is optional; when present it MUST be a plain object with a
+  // string `code`. A non-string code would bypass the equality checks
+  // in format.js empty-result ladder and non-empty banner, producing
+  // no user-facing message when one was intended.
+  if (m.warning != null) {
+    if (!isPlainObject(m.warning)) return false;
+    if (typeof m.warning.code !== "string") return false;
+  }
+  // corpus_freshness is optional. The server contract is **best-effort
+  // metadata**: when the upstream freshness probe fails, semantic.ts
+  // emits `console.warn` and continues with `newest_date: null` rather
+  // than aborting the request. The client must mirror that philosophy
+  // — a malformed `newest_date` should NOT turn an otherwise-successful
+  // search (valid results + tier + quota) into an exit-3 error.
+  //
+  // Split into two levels:
+  //   - Structural (object shape, type of newest_date): envelope-fatal
+  //     via `return false`. A non-string newest_date means the server
+  //     broke contract shape-wise.
+  //   - Content (non-ISO / non-calendar-valid YYYY-MM-DD): coerce
+  //     `newest_date` to null in place. format.js banner treats null
+  //     as "no freshness data" and omits the "newest indexed episode:
+  //     X" suffix cleanly.
+  if (m.corpus_freshness != null) {
+    if (!isPlainObject(m.corpus_freshness)) return false;
+    // `newest_date` is a required sub-field when corpus_freshness is
+    // present (SKILL.md contract: always present as string|null). An
+    // absent property is a protocol break — without this presence
+    // check, the `nd != null` guard below would early-exit for
+    // undefined after R4's structural/content split, letting a {}-
+    // shaped corpus_freshness leak through (R5-01).
+    if (!("newest_date" in m.corpus_freshness)) return false;
+    const nd = m.corpus_freshness.newest_date;
+    if (nd != null) {
+      if (typeof nd !== "string") return false;
+      let isoValid = /^\d{4}-\d{2}-\d{2}$/.test(nd);
+      if (isoValid) {
+        const [y, mo, d] = nd.split("-").map(Number);
+        if (mo < 1 || mo > 12 || d < 1 || d > 31) {
+          isoValid = false;
+        } else {
+          const dt = new Date(Date.UTC(y, mo - 1, d));
+          if (
+            dt.getUTCFullYear() !== y ||
+            dt.getUTCMonth() !== mo - 1 ||
+            dt.getUTCDate() !== d
+          ) {
+            isoValid = false;
+          }
+        }
+      }
+      if (!isoValid) {
+        // Coerce malformed ISO content to null and continue validation.
+        // Downstream format.js sees null and skips the freshness banner
+        // suffix, matching the server's own probe-failure degradation.
+        m.corpus_freshness.newest_date = null;
+      }
+    }
+  }
+  // cta is passthrough-only (no render logic reads its fields today),
+  // but reject non-object so future render paths don't crash on a
+  // primitive where they expect an object.
+  if (m.cta != null && !isPlainObject(m.cta)) return false;
+  // window shape-check (R3-01): format.js renderMarkdown reads
+  // `window.truncated`, `window.expanded`, `window.requested_days`,
+  // `window.served_days` to drive the empty-result priority ladder.
+  // A malformed window (e.g., `expanded: "true"` string, missing
+  // requested_days) would silently misroute rendering — e.g., a
+  // string "false" is truthy and would trigger the expanded branch
+  // when the server meant the opposite. Required fields are validated
+  // strictly; truncated/reason_code/attempted_days are optional and
+  // only checked when present.
+  if (m.window != null) {
+    if (!isPlainObject(m.window)) return false;
+    const w = m.window;
+    if (typeof w.requested_days !== "number" || !Number.isFinite(w.requested_days)) return false;
+    if (typeof w.served_days !== "number" || !Number.isFinite(w.served_days)) return false;
+    if (typeof w.expanded !== "boolean") return false;
+    if (w.truncated !== undefined && typeof w.truncated !== "boolean") return false;
+    if (w.reason_code !== undefined && typeof w.reason_code !== "string") return false;
+    if (w.attempted_days !== undefined) {
+      if (!Array.isArray(w.attempted_days)) return false;
+      for (const n of w.attempted_days) {
+        if (typeof n !== "number" || !Number.isFinite(n)) return false;
+      }
+    }
+  }
   return true;
 }
 
@@ -137,7 +243,7 @@ export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT
 
   const headers = {
     "Content-Type": "application/json",
-    "User-Agent": "askaipods/0.2.3 (+https://github.com/Delibread0601/askaipods)",
+    "User-Agent": "askaipods/0.2.5 (+https://github.com/Delibread0601/askaipods)",
   };
   if (apiKey) {
     headers["X-PodLens-API-Key"] = apiKey;
@@ -148,28 +254,70 @@ export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT
     body.days = days;
   }
 
+  // 30s total budget covers both connection setup and body consumption
+  // (audit R7-02). podlens.net edge workers may take 5-10s for the
+  // Vectorize + Gemini embed round-trip on cold starts; 30s leaves
+  // comfortable headroom while still producing a deterministic
+  // exit-3 instead of hanging a CLI invocation indefinitely on a
+  // half-open socket or unresponsive upstream. Applied via
+  // AbortSignal.timeout() so the signal covers the downstream
+  // `response.json()` body read as well — the same controller
+  // aborts whichever phase happens to be pending.
+  const TIMEOUT_MS = 30_000;
   let response;
   try {
     response = await fetch(endpoint, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
     });
   } catch (err) {
-    // fetch() throws TypeError on DNS / connection failure / abort.
-    // Treat all of these as exit code 3 (transient/network) so the
-    // SKILL.md can advise "retry in a moment" instead of looking like
-    // a usage error.
+    // AbortSignal.timeout fires with DOMException(name: "TimeoutError")
+    // in modern runtimes; some Node 18 versions use AbortError. Treat
+    // both as distinct, user-actionable exit-3 failures with the
+    // concrete timeout budget in the message so the user/agent knows
+    // the failure mode (stalled network vs. DNS failure vs. 404).
+    const name = err?.name;
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw exitErr(
+        3,
+        `request to podlens.net timed out after ${TIMEOUT_MS / 1000}s (possible network stall or slow upstream). Retry in a moment.`,
+      );
+    }
+    // fetch() throws TypeError on DNS / connection failure. Treat as
+    // exit code 3 (transient/network) so the SKILL.md can advise
+    // "retry in a moment" instead of looking like a usage error.
     throw exitErr(3, `network error contacting podlens.net: ${err?.message ?? err}`);
   }
 
   // The server always responds with JSON for both success and error
   // paths (see jsonResponse() in functions/api/search/semantic.ts), so
   // a non-JSON body means an upstream proxy/CDN is in the way.
+  //
+  // Two distinct failure classes in this catch (audit R8-01):
+  //   1. TimeoutError/AbortError — headers arrived in time but the
+  //      body read stalled past the signal's 30s budget. The same
+  //      AbortSignal attached at fetch() propagates to the response
+  //      body stream, so timeouts during `response.json()` surface
+  //      here rather than at the fetch() catch above.
+  //   2. Anything else — real JSON parse failure or truncated body
+  //      (e.g., an upstream proxy returned HTML or closed the
+  //      connection mid-stream).
+  // Must distinguish because the user-actionable advice differs:
+  // "retry, your network stalled" vs. "retry, an upstream proxy
+  // mangled the response."
   let data;
   try {
     data = await response.json();
-  } catch {
+  } catch (err) {
+    const name = err?.name;
+    if (name === "TimeoutError" || name === "AbortError") {
+      throw exitErr(
+        3,
+        `request to podlens.net timed out after ${TIMEOUT_MS / 1000}s while reading response body (possible network stall or slow upstream). Retry in a moment.`,
+      );
+    }
     throw exitErr(
       3,
       `unexpected non-JSON response from podlens.net (HTTP ${response.status}). ` +
@@ -190,15 +338,15 @@ export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT
   // Distinguish 429 cases by inspecting the message: the server uses
   // distinct strings for "burst limit hit" vs "daily quota exhausted",
   // and only the latter warrants the "daily quota" exit code. The
-  // quota message is tier-aware: a member hitting the 50/day cap must
+  // quota message is tier-aware: a member hitting the 100/day cap must
   // not be told to "set ASKAIPODS_API_KEY" — they already have one.
   if (response.status === 429) {
     const msg = String(data?.error ?? "").toLowerCase();
     if (msg.includes("quota")) {
       const quotaMsg = apiKey
-        ? "daily search quota exhausted (member tier: 50/day). Quota resets at 00:00 UTC."
-        : "daily search quota exhausted (anonymous tier: 10/day). Quota resets at 00:00 UTC. " +
-          "For 50 searches/day, set ASKAIPODS_API_KEY (sign up at https://podlens.net).";
+        ? "daily search quota exhausted (member tier: 100/day). Quota resets at 00:00 UTC."
+        : "daily search quota exhausted (anonymous tier: 20/day). Quota resets at 00:00 UTC. " +
+          "For 100 searches/day, set ASKAIPODS_API_KEY — member tier is invite-only, request access at https://podlens.net.";
       throw exitErr(2, quotaMsg);
     }
     throw exitErr(3, "rate limited by podlens.net (too many requests in a short window). Retry in a minute.");

package/src/format.js

@@ -13,7 +13,8 @@
 
 const ANONYMOUS_NOTE =
   "Anonymous tier: 20 results sorted newest-first, dates fuzzed to month, " +
-  "--days capped at 90 when specified. Set ASKAIPODS_API_KEY for 50 searches/day with full dates and unlimited lookback.";
+  "--days capped at 90 when specified. Set ASKAIPODS_API_KEY for 100 searches/day with full dates and unlimited lookback " +
+  "(member tier is invite-only — request access at https://podlens.net).";
 
 // Sort results newest-first by parsing each `published_at` to a UTC
 // millisecond timestamp and comparing numerically. Pure lexical compare
@@ -92,6 +93,20 @@ export function toStructured(query, response) {
       restrictions: response.meta.restrictions ?? null,
       query_hash: response.meta.query_hash ?? null,
       window: response.meta.window ?? null,
+      // New honesty signals (server audit 2026-04-17 → 2026-04-19):
+      //   warning.code       — "corpus_stale_for_requested_window" or
+      //                        "index_metadata_stale"; tells the agent
+      //                        the empty/partial result is a freshness
+      //                        issue rather than a semantic mismatch.
+      //   corpus_freshness   — { newest_date: "YYYY-MM-DD" | null };
+      //                        lets the agent render "data as of X".
+      //   cta                — anonymous-tier call-to-action (e.g.
+      //                        follow URL) passed through unchanged.
+      // All three are optional — defaulted to null so the structured
+      // output shape is stable across server versions.
+      warning: response.meta.warning ?? null,
+      corpus_freshness: response.meta.corpus_freshness ?? null,
+      cta: response.meta.cta ?? null,
     },
   };
 }
@@ -112,19 +127,65 @@ export function renderMarkdown(query, response) {
   const quotaLabel = quota
     ? `${quota.used}/${quota.limit} ${quota.period ?? "daily"}`
     : "unknown";
-  lines.push(`*Tier: ${tierLabel} · Results: ${data.results.length} · Quota: ${quotaLabel}*`);
+  // Server's P1-b narrow refund: when corpus is stale AND delivered
+  // results are empty, the quota slot is refunded (see server CLAUDE.md
+  // §Two-Tier Search Access). Surface as a trailing tag so the user
+  // knows the search was free — `quota.used` is already decremented
+  // upstream, so we only need the marker, not a separate count.
+  const refundedTag = data.meta.quota?.refunded ? " · refunded" : "";
+  lines.push(`*Tier: ${tierLabel} · Results: ${data.results.length} · Quota: ${quotaLabel}${refundedTag}*`);
   lines.push("");
 
   if (data.results.length === 0) {
     const win = data.meta.window;
-    if (win && win.expanded) {
+    const warningCode = data.meta.warning?.code;
+    const newest = data.meta.corpus_freshness?.newest_date;
+    // Priority: freshness warnings take precedence over window/expansion
+    // messaging because they tell the user something stronger — the
+    // corpus (not just their query phrasing) is the reason for the
+    // empty response.
+    // Priority ladder (must match SKILL.md §Error handling):
+    //   1. warning.code = corpus_stale_for_requested_window
+    //   2. warning.code = index_metadata_stale
+    //   3. warning.code = any other value (forward-compat, R6-01)
+    //   4. window.truncated (transient fallback error — retry)
+    //   5. window.expanded (API widened the window, still empty)
+    //   6. generic (no signal — likely semantic mismatch)
+    // truncated MUST be checked before expanded: when a fallback
+    // Vectorize query errors mid-expansion, both flags are true, and
+    // the truncated copy ("retry in a moment") is strictly more
+    // actionable than the expanded copy ("rephrase").
+    if (warningCode === "corpus_stale_for_requested_window") {
+      const asOf = newest ? ` (newest indexed episode: ${newest})` : "";
       lines.push(
-        `No results found. The API expanded the search window from ${win.requested_days} to ${win.served_days} days but still found no matches. Try a different phrasing or broader topic.`,
+        `No results in the requested window${asOf}. The indexed corpus has no episodes matching that window — try a longer \`--days\` value or omit it.`,
+      );
+    } else if (warningCode === "index_metadata_stale") {
+      lines.push(
+        "No results. Recently indexed episodes are still propagating to the search index — retry in a few minutes.",
+      );
+    } else if (warningCode) {
+      // Forward-compat: server may introduce new warning codes (audit
+      // R6-01). Preserve the signal rather than silently falling
+      // through to generic "rephrase" copy, which would mislead the
+      // user into thinking the empty result is their fault.
+      lines.push(
+        `No results. The server flagged a freshness issue with this search (code: ${warningCode}) — results may be incomplete or the requested window may be stale. Try omitting \`--days\` or retry in a few minutes.`,
       );
     } else if (win && win.truncated) {
       lines.push(
         "No results found (search window expansion was interrupted by a transient error). Try again in a moment, or try a different phrasing.",
       );
+    } else if (win && win.expanded) {
+      // SKILL.md §Error handling step 4 mandates appending the
+      // corpus-indexed-through suffix when newest_date is present —
+      // an honest freshness signal distinct from the freshness warning
+      // (which would have landed on the warning branches above). Keeps
+      // CLI markdown and SKILL.md's agent render instructions aligned.
+      const indexedThrough = newest ? ` (corpus indexed through ${newest})` : "";
+      lines.push(
+        `No results found. The API expanded the search window from ${win.requested_days} to ${win.served_days} days but still found no matches${indexedThrough}. Try a different phrasing or broader topic.`,
+      );
     } else {
       lines.push("No results found. Try a different phrasing or broader topic.");
     }
@@ -135,6 +196,37 @@ export function renderMarkdown(query, response) {
     return lines.join("\n");
   }
 
+  // Freshness warning (partial-results case): SKILL.md's meta.warning
+  // contract covers both empty AND partial responses. When results are
+  // present but the server still flags a freshness issue (e.g.,
+  // index_metadata_stale: fresh episodes exist but some haven't
+  // propagated to Vectorize yet), emit a banner above the results so
+  // the user knows the set is incomplete rather than authoritative.
+  // Placed before the expansion note so freshness signals dominate —
+  // same priority intent as the empty-branch ladder.
+  const warningCode = data.meta.warning?.code;
+  const newest = data.meta.corpus_freshness?.newest_date;
+  if (warningCode === "corpus_stale_for_requested_window") {
+    const asOf = newest ? ` (newest indexed episode: ${newest})` : "";
+    lines.push(
+      `*Note: The indexed corpus has no episodes in the requested window${asOf} — results below may come from an expanded window. Try omitting \`--days\` for broader coverage.*`,
+    );
+    lines.push("");
+  } else if (warningCode === "index_metadata_stale") {
+    lines.push(
+      "*Note: Recently indexed episodes are still propagating to the search index — some relevant matches may be missing. Retry in a few minutes for complete coverage.*",
+    );
+    lines.push("");
+  } else if (warningCode) {
+    // Unknown server warning code (forward-compat, audit R6-01).
+    // Surface the raw code so the signal reaches the user rather
+    // than being silently dropped.
+    lines.push(
+      `*Note: Server flagged a freshness concern with this search (code: ${warningCode}) — results may be incomplete.*`,
+    );
+    lines.push("");
+  }
+
   // Surface window expansion so the user knows the actual time range
   const win = data.meta.window;
   if (win && win.expanded) {