askaipods 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,13 @@
 # askaipods
 
-> Search AI podcast quotes about a topic — find what real guests on Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens of other AI podcasts are actually saying. A universal [agentskills.io](https://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](https://podlens.net).
+> Search AI podcast quotes about a topic — recent episode excerpts from Lex Fridman, Dwarkesh Patel, No Priors, Latent Space, and dozens of other AI podcasts, surfaced as short indexed quotes (no per-speaker attribution). A universal [agentskills.io](https://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](https://podlens.net).
 
 ```
 $ askaipods "what are people saying about test-time compute"
 
 # askaipods · "what are people saying about test-time compute"
 
-*Tier: anonymous · Results: 10 · Quota: 1/10 daily*
+*Tier: anonymous · Results: 20 · Quota: 1/5 daily*
 
 ## Results — newest first
 
@@ -23,7 +23,7 @@ $ askaipods "what are people saying about test-time compute"
 > Test-time compute as a paradigm pushes toward smaller base models because
 > the cost of solving a prob...
 
-(...8 more results, newest-first...)
+(...18 more results, newest-first...)
 ```
 
 ## Why this exists
@@ -67,7 +67,7 @@ Then copy or symlink the `skill/askaipods/` directory into your agent's skills f
 
 ✨ **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.
 
-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 a **Latest** + **Top Relevant** + **Insights** structure.
+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).
 
 ## Usage
 
@@ -80,10 +80,10 @@ askaipods "what are VCs saying about reasoning models"
 # JSON output (for scripts and agents)
 askaipods "Anthropic safety research" --format json
 
-# Restrict to recent episodes only (max 7 days for anonymous tier; member tier accepts any value)
-askaipods "GPU shortage" --days 7
+# 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 50/day instead of 5/day
 ASKAIPODS_API_KEY=pk_xxx askaipods "your query"
 askaipods "your query" --api-key pk_xxx
 ```
@@ -94,27 +94,28 @@ Once the skill is installed in your agent's skills directory, simply ask:
 
 > What are people saying about test-time compute on AI podcasts?
 
-Your agent will recognize the trigger phrase, invoke `askaipods`, and present the results with a Latest section, a Top Relevant section, and an AI-generated Insights summary. No CLI knowledge required from the user.
+Your agent will recognize the trigger phrase, invoke `askaipods`, and present the results with an AI-generated Insights summary. The exact layout is tier-dependent: **member tier** renders dual sections (Latest 5 + Top 5 Most Relevant + Insights); **anonymous tier** renders a single section (Recent Quotes + Insights), because anonymous results are sorted by date (not semantic relevance) and showing a "Top Relevant" view would be misleading. No CLI knowledge required from the user either way.
 
 ## Tier comparison
 
 | | Anonymous (default) | Member |
 |---|---|---|
-| **Daily quota** | 10 searches per IP | 50 searches per user |
-| **Results returned** | 10 (randomized from top 20) | 20 (fixed top 20) |
-| **Text length** | Truncated by rank (150/100/60 chars) | Full text |
+| **Daily quota** | 5 searches per IP | 50 searches per user |
+| **Results returned** | 20 (deterministic top 20, sorted newest-first) | 20 (deterministic top 20, sorted by relevance) |
+| **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 |
 
-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 text and exact dates.
+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 5/day quota or need full dates and unlimited lookback.
 
 ## Honest limitations
 
 - **No speaker attribution.** The corpus indexes quotes at the episode level but does not attempt to identify *which guest* said each quote. The upstream pipeline avoids speaker labeling because automatic diarization is unreliable, and a wrong attribution is worse than no attribution.
 - **No episode URLs.** The public API does not expose direct podcast or episode links. You will need to search the podcast and episode title in your podcast app of choice.
 - **AI-focused corpus.** Coverage is dense for AI research, ML engineering, AI investing, and AI policy. Off-topic queries return sparse, noisy results.
-- **Short quote excerpts.** Each result is typically 1-3 sentences (anonymous tier truncates further). For long-form context, listen to the episode.
+- **Short quote excerpts.** Each result is typically 1-3 sentences. For long-form context, listen to the episode.
 
 These are not bugs. The skill surfaces them honestly so neither you nor your agent fabricate things the API does not provide.
 
@@ -125,7 +126,7 @@ These are not bugs. The skill surfaces them honestly so neither you nor your age
 | `0` | Success |
 | `1` | Usage error / invalid arguments / API key rejected |
 | `2` | Daily quota exhausted |
-| `3` | Network error / podlens.net unavailable |
+| `3` | Transient or unexpected failure — network error, rate-limit burst, service 503, protocol/shape error, or internal exception. stderr has the actionable detail. |
 
 ## How the skill renders results
 
@@ -142,7 +143,7 @@ For member tier (`render_hint: dual_view`), the host agent renders two sections
 (3-5 bullets synthesizing patterns across the quotes)
 ```
 
-For anonymous tier (`render_hint: single_view`), only Latest and Insights — the Top Relevant section is intentionally suppressed because anonymous results are randomized within the top 20, so api_rank does not represent true semantic relevance.
+For anonymous tier (`render_hint: single_view`), only Recent Quotes and Insights — the Top Relevant section is intentionally suppressed because anonymous results are sorted by date (newest-first), so api_rank reflects temporal order, not semantic relevance.
 
 See [`skill/askaipods/SKILL.md`](skill/askaipods/SKILL.md) for the full skill specification.
 
@@ -158,12 +159,12 @@ askaipods/
 ├── skill/askaipods/
 │   └── SKILL.md           ← agentskills.io standard skill file
 ├── examples/              ← per-runtime install guides
-├── package.json           ← zero dependencies (Node 18+ stdlib only)
+├── package.json           ← zero dependencies (Node 18.3.0+ stdlib only)
 ├── LICENSE                ← MIT
 └── README.md
 ```
 
-The CLI is intentionally zero-dependency (Node 18+ stdlib only) so `npx askaipods` cold-starts in under a second and the package install footprint is minimal.
+The CLI is intentionally zero-dependency (Node 18.3.0+ stdlib only — `node:util.parseArgs` requires 18.3.0) so `npx askaipods` cold-starts in under a second and the package install footprint is minimal.
 
 ## Contributing
 

package/bin/askaipods.js

@@ -4,5 +4,10 @@ import { run } from "../src/cli.js";
 run(process.argv.slice(2)).catch((err) => {
   const message = err?.message ?? String(err);
   process.stderr.write(`askaipods: ${message}\n`);
-  process.exit(typeof err?.exitCode === "number" ? err.exitCode : 1);
+  // AskaipodsError carries an explicit exitCode for known user/protocol
+  // failures. Any other exception is an internal or unexpected failure
+  // (format-time RangeError, unhandled rejection, etc.) — these are
+  // closer in semantics to exit 3 "protocol / unexpected failure" than
+  // to exit 1 "usage error", so default to 3 instead of 1.
+  process.exit(typeof err?.exitCode === "number" ? err.exitCode : 3);
 });

package/examples/claude-code-install.md

@@ -39,12 +39,12 @@ 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 Latest / Top Relevant / Insights sections.
+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).
 
 ## 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+ is installed: `node --version`. The CLI uses zero dependencies so there are no other prereqs.
+- **`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`.
 - **Skill triggers too rarely**: Front-load your prompt with the trigger phrases in `SKILL.md` description, or invoke directly with `/askaipods <query>`.
 

package/examples/codex-install.md

@@ -39,7 +39,7 @@ Codex should detect the trigger, run `npx askaipods search "..." --format json`,
 
 - **Skill not detected**: Restart Codex (per the official docs, "If an update doesn't appear, restart Codex").
 - **Multiple skills with the same name across scopes**: Codex shows both in the selector — repository-scoped wins by default.
-- **`npx askaipods` fails**: Check Node.js 18+: `node --version`.
+- **`npx askaipods` fails**: Check Node.js 18.3.0+: `node --version`.
 
 ## Reference
 

package/examples/hermes-install.md

@@ -26,7 +26,7 @@ Hermes should pick up the skill from `~/.hermes/skills/askaipods/`, shell out to
 
 ## Troubleshooting
 
-- **`npx askaipods` fails**: Hermes is Python-based but the askaipods CLI is Node. Make sure Node.js 18+ is on PATH alongside Python: `node --version`.
+- **`npx askaipods` fails**: Hermes is Python-based but the askaipods CLI is Node. Make sure Node.js 18.3.0+ is on PATH alongside Python: `node --version`.
 - **Skill not picked up**: Hermes documentation indicates skills are loaded from `~/.hermes/skills/`. Restart the agent after install if needed.
 - **Quota exhausted**: Set `ASKAIPODS_API_KEY` in your shell environment before launching Hermes so the variable propagates to subprocess calls.
 

package/examples/openclaw-install.md

@@ -52,7 +52,7 @@ OpenClaw should recognize the trigger phrase, shell out to `npx askaipods search
 ## Troubleshooting
 
 - **Skill not detected**: Run `openclaw skills update --all` to refresh, or restart the OpenClaw session. Check that the directory name `askaipods` matches the `name` field in `SKILL.md`.
-- **`npx askaipods` fails**: Make sure Node.js 18+ is on PATH: `node --version`.
+- **`npx askaipods` fails**: Make sure Node.js 18.3.0+ is on PATH: `node --version`.
 - **Conflicting copies across precedence levels**: Only the highest-precedence one wins. If you have askaipods in both `~/.agents/skills/` and `<workspace>/skills/`, the workspace one takes effect.
 
 ## Reference

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "askaipods",
-  "version": "0.1.0",
-  "description": "Search AI podcast quotes by topic — find what Lex Fridman, Dwarkesh Patel, No Priors, and Latent Space guests are actually saying. 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.",
+  "version": "0.2.0",
+  "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": {
     "askaipods": "./bin/askaipods.js"
@@ -19,7 +19,7 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=18.3.0"
   },
   "scripts": {
     "start": "node bin/askaipods.js",

package/skill/askaipods/SKILL.md

@@ -2,14 +2,14 @@
 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.
 license: MIT
-requirements: Node.js 18+ on PATH, internet access to podlens.net. Optional ASKAIPODS_API_KEY env var unlocks the 50/day member tier; without it the skill works on the 10/day anonymous tier (per-IP).
+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 5/day anonymous tier (per-IP, month-precision dates, `--days` capped at 90 when specified).
 ---
 
 # askaipods — AI podcast quote search
 
 This skill turns "what is the AI community saying about X" into a list of real quote excerpts pulled from recent episodes of top AI podcasts. The corpus is semantically indexed (embedding-based search), so phrasings like "test-time compute", "inference-time scaling", and "thinking longer" all return overlapping results — the user does not need to guess the exact words a guest used.
 
-The data source is the public PodLens search API at `podlens.net`. The skill never hits that API directly from your model context — it shells out to a small bundled CLI (`askaipods`) that handles HTTP, retries, error mapping, and result sorting. Your job is to invoke the CLI, parse its JSON, and present the results in the format below.
+The data source is the public PodLens search API at `podlens.net`. The skill never hits that API directly from your model context — it shells out to a small bundled CLI (`askaipods`) that handles HTTP, error mapping, and result sorting. Your job is to invoke the CLI, parse its JSON, and present the results in the format below.
 
 ## When to invoke
 
@@ -40,17 +40,31 @@ Run the bundled CLI and pass `--format json`. The flag matters because without i
 npx askaipods search "<USER QUERY>" --format json
 ```
 
-If `npx askaipods` is not available in the user's environment (e.g. the package was not yet published to npm), fall back to running the local CLI from this skill's parent directory:
+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.
+
+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.
 
 ```bash
-node <path-to-askaipods-repo>/bin/askaipods.js search "<USER QUERY>" --format json
+npx askaipods search "<USER QUERY>" --days 90 --format json
 ```
 
-To restrict to recent episodes only, add `--days N` (the API caps anonymous tier at 7 days; member tier accepts any value):
+### Time-intent mapping (important)
 
-```bash
-npx askaipods search "<USER QUERY>" --days 30 --format json
-```
+When the user's query implies a time window, you MUST pass the appropriate `--days` value. Without it, the API returns all-time results regardless of recency words in the query.
+
+| User intent | `--days` value |
+|---|---|
+| "recent", "latest", "最近", "current" | `90` |
+| "this month", "这个月" | `30` |
+| "this week", "这周", "last week" | `7` |
+| "today", "yesterday", "last few days" | `3` |
+| "last N days/weeks/months" | Convert N to days |
+| "this quarter", "这个季度" | `90` |
+| "this year", "今年" | `365` (member only; anonymous capped to 90) |
+| Explicit date range (e.g. "since January") | Convert to days from today |
+| No time intent (broad research) | Omit `--days` (all time — no cap applied) |
+
+Do NOT silently default every query to `--days 90` — omitting `--days` on broad research queries preserves valuable historical context that the user did not ask to exclude.
 
 ## JSON shape returned by the CLI
 
@@ -80,13 +94,13 @@ npx askaipods search "<USER QUERY>" --days 30 --format json
 
 Field notes that affect how you render:
 
-- **`tier`** — `member` if the user has a valid API key, `anonymous` otherwise. Drives the rendering branch below. The CLI defaults `tier` to `"anonymous"` if the upstream response somehow lacks the field, so you will always land on one of the two documented branches — never on a third "unknown" path.
-- **`render_hint`** — `dual_view` for member, `single_view` for anonymous. Honor this. The reason: anonymous results are a randomized 10-of-20 subset, so `api_rank` only describes order *within that random subset*, not true semantic relevance against the corpus. Showing a "Top Most Relevant" section for anonymous tier would mislead the user.
+- **`tier`** — `member` if the user has a valid API key, `anonymous` otherwise. Drives the rendering branch below. On exit `0`, `tier` is always one of these two values — there is no third "unknown" path to handle (the CLI validates the upstream response and exits `3` if the value is missing or unexpected).
+- **`render_hint`** — `dual_view` for member, `single_view` for anonymous. Honor this. The reason: anonymous results are sorted by `published_at` desc (newest-first) by the API, so `api_rank` reflects temporal order, not semantic relevance. Showing a "Top Most Relevant" section for anonymous tier would mislead the user. Member results arrive in similarity order, so `api_rank` is meaningful for relevance-based views.
 - **`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 for query privacy). Display whatever you got — don't guess a day.
+- **`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.restrictions`** — `null` for member tier; for anonymous tier, an object describing the cap (e.g., `{ max_results: 10, text_truncated: true, results_randomized: true }`). 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.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.
 - **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
@@ -114,7 +128,7 @@ 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 same `results` array by filtering on `api_rank`)
+(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.)
 
 ## 💡 Insights
 
@@ -136,7 +150,7 @@ If the same result appears in both Latest and Top Relevant sections, that's fine
 
 2. ...
 
-(all returned results, in `results` array order which is already newest-first; expect up to 10)
+(all returned results, in `results` array order which is already newest-first; expect up to 20)
 
 ## 💡 Insights
 
@@ -146,14 +160,14 @@ If the same result appears in both Latest and Top Relevant sections, that's fine
 
 ---
 
-*Anonymous tier: 10 randomized results from top 20, text truncated by rank, dates fuzzed to month. Set `ASKAIPODS_API_KEY` for 50 searches/day with full text and full dates — 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 50 searches/day with full dates and unlimited lookback — sign up at https://podlens.net.*
 ```
 
-The closing note about the anonymous tier matters because it tells the user (a) why the text looks chopped, (b) why the dates are coarse, and (c) what the upgrade path is. Skipping it leaves the user wondering if the skill is broken.
+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.
 
 ## Insights guidelines
 
-The Insights section is the most valuable part of your response — it is what differentiates this skill from a raw API call. The user could read 10 quotes themselves; what they cannot easily do is *spot the patterns across the 10*. That is your job.
+The Insights section is the most valuable part of your response — it is what differentiates this skill from a raw API call. The user could read 20 quotes themselves; what they cannot easily do is *spot the patterns across the 20*. That is your job.
 
 Write 3-5 bullets, each one concrete and one sentence long. Cover at least three of these dimensions:
 
@@ -178,8 +192,8 @@ The CLI uses stable exit codes so you can branch on the failure mode:
 |---|---|---|
 | `0` | Success | Render the results normally |
 | `1` | Usage error / invalid arguments / API key rejected | Surface the stderr message verbatim — it will be a clear actionable error |
-| `2` | Daily quota exhausted | "Daily search quota reached. Anonymous tier resets at 00:00 UTC; for 50 searches/day, set `ASKAIPODS_API_KEY` (sign up at https://podlens.net)." |
-| `3` | Network error / podlens.net unavailable | Retry once after a brief pause; if it fails again, tell the user "PodLens search is temporarily unavailable. Try again in a few minutes." |
+| `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), say so explicitly: "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." Do not invent quotes to fill the gap.
 
@@ -190,6 +204,6 @@ Never silently swallow an error. Never fabricate quotes when the API returns not
 - **No speaker attribution.** The API returns "podcast + episode + quote text" but not "who said it". The upstream pipeline avoids per-speaker attribution because automatic speaker diarization is unreliable — surfacing wrong attribution would be worse than no attribution.
 - **No episode URLs.** The public API does not expose direct links to episodes. Users who want to listen will need to search the podcast and episode title in their podcast app of choice.
 - **AI-focused corpus.** Coverage is dense for AI research, ML engineering, AI investing, and AI policy. Coverage for unrelated topics is sparse and noisy.
-- **Short quote excerpts, not transcripts.** Each result is one extracted "key point" from an episode, typically 1-3 sentences (anonymous tier truncates further). For long-form context, the user will need to listen.
+- **Short quote excerpts, not transcripts.** Each result is one extracted "key point" from an episode, typically 1-3 sentences. For long-form context, the user will need to listen.
 
 These limitations are not bugs — surfacing them honestly is better than the user discovering them mid-task and losing trust.

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.1.0";
+const VERSION = "0.2.0";
 
 const HELP_TEXT = `askaipods ${VERSION} — search AI podcast quotes by topic
 
@@ -24,21 +24,22 @@ USAGE:
 
 OPTIONS:
   --format <json|markdown>   Output format (default: markdown if TTY, json if piped)
-  --days <N>                 Only return results from the last N days (max 7 for anonymous tier; member tier accepts any value)
+  --days <N>                 Only return results from the last N days (anonymous tier caps at 90; member tier accepts any value)
   --api-key <key>            PodLens API key (overrides ASKAIPODS_API_KEY env var)
   -h, --help                 Show this message
   -v, --version              Show version
 
 ENVIRONMENT:
-  ASKAIPODS_API_KEY          PodLens API key. Without it: 10 searches/day per IP (anonymous).
+  ASKAIPODS_API_KEY          PodLens API key. Without it: 5 searches/day per IP (anonymous).
                              With it: 50 searches/day per user (member).
                              Sign up at https://podlens.net to get one.
 
 EXIT CODES:
   0  success
   1  usage error / invalid arguments / API key rejected
-  2  daily quota exhausted
-  3  network error / podlens.net unavailable
+  2  daily quota exhausted (tier-aware message on stderr)
+  3  transient or unexpected failure — network / rate-limit burst / 503 /
+     protocol error / internal exception (stderr has the actionable detail)
 
 EXAMPLES:
   askaipods "what are people saying about test-time compute"
@@ -99,9 +100,22 @@ export async function run(argv) {
 
   let days;
   if (values.days !== undefined) {
+    // Strict positive integer match. Three reasons for the shape:
+    //   (1) parseInt("7abc",10) silently returns 7 — reject any
+    //       non-digit suffix / scientific notation / decimals / sign.
+    //   (2) client.js only forwards `days` to the API when it's > 0,
+    //       so "0" or "00" would silently drop the filter entirely
+    //       instead of filtering to "0 days" as the user expected.
+    //   (3) Number.parseInt("9".repeat(400), 10) returns Infinity, and
+    //       JSON.stringify({days: Infinity}) emits {"days":null}, which
+    //       would send a malformed body instead of the user's intent.
+    //       Reject inputs that don't survive round-trip as a safe int.
+    if (!/^[1-9]\d*$/.test(values.days)) {
+      throw usageError("--days must be a positive integer (1 or greater)");
+    }
     const n = Number.parseInt(values.days, 10);
-    if (!Number.isFinite(n) || n < 0) {
-      throw usageError("--days must be a non-negative integer");
+    if (!Number.isSafeInteger(n)) {
+      throw usageError("--days value is too large");
     }
     days = n;
   }
@@ -111,7 +125,51 @@ export async function run(argv) {
     throw usageError(`--format must be 'json' or 'markdown', got '${format}'`);
   }
 
-  const apiKey = values["api-key"] ?? process.env.ASKAIPODS_API_KEY;
+  // Source of truth for the API key:
+  //   1. --api-key flag if provided AND non-empty after trim. An empty
+  //      or whitespace-only flag is rejected as a usage error — Node's
+  //      Headers constructor normalizes a whitespace-only header value
+  //      to empty, so without this trim the user would silently get no
+  //      X-PodLens-API-Key header and a silent tier downgrade from
+  //      member to anonymous.
+  //   2. ASKAIPODS_API_KEY env var if --api-key is unset. The env var
+  //      is trimmed and treated as unset when empty/whitespace — shell
+  //      unset/export mishaps and trailing-newline cases are common and
+  //      unlikely to reflect user intent, so we silently coerce rather
+  //      than erroring.
+  // HTTP header values must be ByteStrings (each character ≤ 0xFF).
+  // Characters outside the printable ASCII + Latin-1 extended range
+  // cause Node's Headers constructor to throw a ByteString TypeError,
+  // which the fetch catch in client.js would mislabel as a network
+  // error (exit 3) instead of a user input problem. This allowlist
+  // rejects C0 controls (0x00-0x1F), DEL (0x7F), and any codepoint
+  // above 0xFF (LS, PS, ZWSP, emoji, etc.) at the CLI boundary with
+  // exit 1.
+  const INVALID_KEY_CHARS = /[^\x20-\x7E\x80-\xFF]/;
+  let apiKey;
+  if (values["api-key"] !== undefined) {
+    const trimmed = values["api-key"].trim();
+    if (trimmed.length === 0) {
+      throw usageError(
+        "--api-key value cannot be empty or whitespace-only; omit the flag to use the anonymous tier or the ASKAIPODS_API_KEY env var",
+      );
+    }
+    if (INVALID_KEY_CHARS.test(trimmed)) {
+      throw usageError("--api-key value contains invalid characters (control chars, non-Latin-1 Unicode, or emoji are not allowed in HTTP headers)");
+    }
+    apiKey = trimmed;
+  } else {
+    const envTrimmed = (process.env.ASKAIPODS_API_KEY ?? "").trim();
+    if (envTrimmed.length === 0) {
+      apiKey = undefined;
+    } else if (INVALID_KEY_CHARS.test(envTrimmed)) {
+      throw usageError(
+        "ASKAIPODS_API_KEY env var contains invalid characters (control chars, non-Latin-1 Unicode, or emoji are not allowed in HTTP headers)",
+      );
+    } else {
+      apiKey = envTrimmed;
+    }
+  }
 
   const response = await search({ query, days, apiKey });
 

package/src/client.js

@@ -26,6 +26,106 @@ function exitErr(code, message) {
   return new AskaipodsError(message, code);
 }
 
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+// Strict calendar validation for published_at. Accepts only the three
+// documented shapes, validates all numeric components against calendar
+// and clock bounds, and round-trips via Date.UTC to catch impossible
+// day/month combinations (Feb 30 etc). Timezone offset is required
+// whenever a time component is present — a timezone-less datetime like
+// "2025-10-15T12:00:00" would be ambiguous (Date.parse interprets it
+// in the system's local timezone, making sort order non-deterministic
+// across machines). Format: Z or ±HH:MM (colonized), hour bounded
+// 0-14, minute bounded 0-59.
+const PUBLISHED_AT_SHAPE =
+  /^(\d{4})-(\d{2})(?:-(\d{2})(?:T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(Z|[+-]\d{2}:\d{2}))?)?$/;
+function isValidPublishedAt(v) {
+  if (v == null) return true;
+  if (typeof v !== "string") return false;
+  const parts = v.match(PUBLISHED_AT_SHAPE);
+  if (!parts) return false;
+  const year = Number(parts[1]);
+  const month = Number(parts[2]);
+  if (year < 1970 || year > 9999) return false;
+  if (month < 1 || month > 12) return false;
+  if (parts[3] !== undefined) {
+    const day = Number(parts[3]);
+    if (day < 1 || day > 31) return false;
+    const dt = new Date(Date.UTC(year, month - 1, day));
+    if (
+      dt.getUTCFullYear() !== year ||
+      dt.getUTCMonth() !== month - 1 ||
+      dt.getUTCDate() !== day
+    ) {
+      return false;
+    }
+    if (parts[4] !== undefined) {
+      const hh = Number(parts[4]);
+      const mm = Number(parts[5]);
+      const ss = Number(parts[6]);
+      if (hh > 23 || mm > 59 || ss > 59) return false;
+      if (parts[7] !== undefined && parts[7] !== "Z") {
+        // parts[7] is "±HH:MM" (enforced by regex). Check offset bounds.
+        const offHh = Number(parts[7].slice(1, 3));
+        const offMm = Number(parts[7].slice(4, 6));
+        if (offHh > 14 || offMm > 59) return false;
+      }
+    }
+  }
+  return true;
+}
+
+// Validate the PodLens success envelope against the documented contract.
+// Any mismatch is treated as a protocol break and surfaces as exit 3 —
+// better a loud AskaipodsError(exitCode=3) than a TypeError escaping as
+// exit 1 when format.js tries to operate on malformed fields.
+//
+// Required envelope:
+//   data                       : non-array object
+//   data.total                 : finite number
+//   data.results               : array (may be empty)
+//   data.results[i]            : non-array object
+//   data.results[i].text       : string (required, never null)
+//   data.results[i].episode_title  : string or null/undefined
+//   data.results[i].podcast_name   : string or null/undefined
+//   data.results[i].published_at   : string or null/undefined
+//   data.meta                  : non-array object
+//   data.meta.tier             : closed enum {"anonymous","member"}
+//   data.meta.quota            : non-array object
+//   data.meta.quota.used       : finite number
+//   data.meta.quota.limit      : finite number
+//
+// Optional (kept loose on purpose):
+//   data.meta.quota.period, data.meta.quota.next_reset,
+//   data.meta.query_hash, data.meta.restrictions, data.meta.cta
+function isValidSuccessEnvelope(data) {
+  if (!isPlainObject(data)) return false;
+  if (typeof data.total !== "number" || !Number.isFinite(data.total)) return false;
+  if (!Array.isArray(data.results)) return false;
+  for (const item of data.results) {
+    if (!isPlainObject(item)) return false;
+    // text must be a non-empty, non-whitespace-only string. An all-
+    // whitespace text would otherwise render as an empty blockquote
+    // row (`> ` with nothing after it) in --format markdown.
+    if (typeof item.text !== "string" || item.text.trim().length === 0) return false;
+    // `!= null` intentionally matches both null and undefined (contract
+    // allows either as "missing"), but rejects numbers, objects, arrays.
+    if (item.episode_title != null && typeof item.episode_title !== "string") return false;
+    if (item.podcast_name != null && typeof item.podcast_name !== "string") return false;
+    if (!isValidPublishedAt(item.published_at)) return false;
+  }
+  const m = data.meta;
+  if (!isPlainObject(m)) return false;
+  if (m.tier !== "anonymous" && m.tier !== "member") return false;
+  const q = m.quota;
+  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;
+  return true;
+}
+
 export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT }) {
   if (typeof query !== "string" || query.trim().length < MIN_QUERY_LEN) {
     throw exitErr(1, "query is required (1-300 characters)");
@@ -36,7 +136,7 @@ export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT
 
   const headers = {
     "Content-Type": "application/json",
-    "User-Agent": "askaipods/0.1.0 (+https://github.com/Delibread0601/askaipods)",
+    "User-Agent": "askaipods/0.2.0 (+https://github.com/Delibread0601/askaipods)",
   };
   if (apiKey) {
     headers["X-PodLens-API-Key"] = apiKey;
@@ -77,20 +177,28 @@ export async function search({ query, days, apiKey, endpoint = PODLENS_ENDPOINT
   }
 
   if (response.ok) {
+    if (!isValidSuccessEnvelope(data)) {
+      throw exitErr(
+        3,
+        "unexpected response shape from podlens.net (envelope, results entries, meta.tier, or meta.quota failed contract validation). Retry in a moment.",
+      );
+    }
     return data;
   }
 
   // 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 telling the user about API keys.
+  // and only the latter warrants the "daily quota" exit code. The
+  // quota message is tier-aware: a member hitting the 50/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")) {
-      throw exitErr(
-        2,
-        "daily search quota exhausted. Anonymous tier resets at 00:00 UTC. " +
-          "For 50 searches/day, set ASKAIPODS_API_KEY (sign up at https://podlens.net).",
-      );
+      const quotaMsg = apiKey
+        ? "daily search quota exhausted (member tier: 50/day). Quota resets at 00:00 UTC."
+        : "daily search quota exhausted (anonymous tier: 5/day). Quota resets at 00:00 UTC. " +
+          "For 50 searches/day, set ASKAIPODS_API_KEY (sign up 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

@@ -12,21 +12,38 @@
 // Relevant" sub-views — see SKILL.md.
 
 const ANONYMOUS_NOTE =
-  "Anonymous tier: 10 randomized results from top 20, text truncated by rank, " +
-  "dates fuzzed to month. Set ASKAIPODS_API_KEY for 50 searches/day with full text and dates.";
+  "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.";
 
-// Lexical compare on YYYY-MM[-DD][THH:MM:SSZ] descending puts newest
-// first regardless of whether the date is a full ISO timestamp (member
-// tier) or a YYYY-MM month-prefix (anonymous tier). Nulls sort to the
-// end so absent-date results don't crowd out the dated ones.
+// Sort results newest-first by parsing each `published_at` to a UTC
+// millisecond timestamp and comparing numerically. Pure lexical compare
+// is broken for ISO timestamps with timezone offsets:
+// "2025-01-01T00:30:00+14:00" (UTC 2024-12-31T10:30Z) lex-sorts ahead
+// of "2024-12-31T23:30:00-12:00" (UTC 2025-01-01T11:30Z), reversing the
+// newest-first contract for any member-tier response that carries
+// offset timestamps. Numeric UTC compare fixes that.
+//
+// Anonymous tier dates are YYYY-MM (month only); Date.parse is
+// inconsistent across engines for that shape, so normalize to
+// YYYY-MM-01 first. Member tier dates are always Date.parse-able
+// (either YYYY-MM-DD or a full ISO 8601 timestamp with offset).
+//
+// Nulls and any unparseable value sort to the end so absent-date
+// results don't crowd out the dated ones.
+function toUtcMs(dateStr) {
+  if (!dateStr) return null;
+  const normalized = /^\d{4}-\d{2}$/.test(dateStr) ? `${dateStr}-01` : dateStr;
+  const ms = Date.parse(normalized);
+  return Number.isNaN(ms) ? null : ms;
+}
 export function sortByDateDesc(items) {
   return [...items].sort((a, b) => {
-    const ad = a?.published_at ?? "";
-    const bd = b?.published_at ?? "";
-    if (ad === bd) return 0;
-    if (!ad) return 1;
-    if (!bd) return -1;
-    return bd < ad ? -1 : 1;
+    const am = toUtcMs(a?.published_at);
+    const bm = toUtcMs(b?.published_at);
+    if (am === bm) return 0;
+    if (am === null) return 1;
+    if (bm === null) return -1;
+    return bm - am;
   });
 }
 
@@ -34,18 +51,25 @@ export function sortByDateDesc(items) {
 // its `api_rank` (1 = most semantically relevant in API order) so the
 // SKILL.md can tell the agent to derive a "Top Relevant" sub-view for
 // member tier without re-querying. For anonymous tier api_rank reflects
-// only the relative order within a randomized subset, not the corpus
-// rank — `render_hint` flags that distinction.
+// temporal order (newest-first from the API), not semantic relevance —
+// `render_hint` flags that distinction.
 //
-// `tier` defaults to "anonymous" rather than "unknown" if the upstream
-// response is missing the field, so the SKILL.md tier branch (which
-// only documents `anonymous` and `member`) always lands on a documented
-// path. Anonymous is the safer default because it disables the
-// "Top Relevant" view — better to under-promise relevance ranking than
-// to render a misleading section based on randomized data.
+// Preconditions: `response` must be a validated success envelope from
+// `client.search()`. `client.js` validates `meta.tier` is a non-empty
+// string and `meta.quota` is an object before returning, so we read
+// those fields directly here without a fallback. A programmatic caller
+// that bypasses client.search() and hands toStructured a malformed
+// response will get a TypeError — that's louder than a silent fallback
+// and matches the "protocol break → exit 3" philosophy of client.js.
 export function toStructured(query, response) {
-  const tier = response?.meta?.tier ?? "anonymous";
-  const apiResults = Array.isArray(response?.results) ? response.results : [];
+  // These fields are guaranteed by client.js's success-envelope validator:
+  //   response.results (array), response.meta (object),
+  //   response.meta.tier (non-empty string), response.meta.quota (object).
+  // Read them directly. The remaining fields below (total,
+  // meta.query_hash, meta.restrictions) are optional per the server
+  // contract and keep their `?? null` / fallback defenses.
+  const tier = response.meta.tier;
+  const apiResults = response.results;
 
   const withRank = apiResults.map((r, idx) => ({ ...r, api_rank: idx + 1 }));
   const sorted = sortByDateDesc(withRank);
@@ -63,10 +87,10 @@ export function toStructured(query, response) {
       api_rank: r.api_rank,
     })),
     meta: {
-      total_returned: typeof response?.total === "number" ? response.total : apiResults.length,
-      quota: response?.meta?.quota ?? null,
-      restrictions: response?.meta?.restrictions ?? null,
-      query_hash: response?.meta?.query_hash ?? null,
+      total_returned: response.total,
+      quota: response.meta.quota,
+      restrictions: response.meta.restrictions ?? null,
+      query_hash: response.meta.query_hash ?? null,
     },
   };
 }