askaipods 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # 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"
@@ -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 results are a randomized subset and the rank is not a true semantic-relevance signal).
 
 ## Usage
 
@@ -94,7 +94,7 @@ 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 a randomized subset of the top 20 and showing a "Top Relevant" view would be misleading. No CLI knowledge required from the user either way.
 
 ## Tier comparison
 
@@ -125,7 +125,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
 
@@ -158,12 +158,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/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.1.1",
+  "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; without it the skill works on the 10/day anonymous tier (per-IP).
 ---
 
 # 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,11 +40,7 @@ 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:
-
-```bash
-node <path-to-askaipods-repo>/bin/askaipods.js search "<USER QUERY>" --format json
-```
+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` (the API caps anonymous tier at 7 days; member tier accepts any value):
 
@@ -80,7 +76,7 @@ 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.
+- **`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 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.
 - **`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.
@@ -114,7 +110,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
 
@@ -178,8 +174,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.
 

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.1.1";
 
 const HELP_TEXT = `askaipods ${VERSION} — search AI podcast quotes by topic
 
@@ -37,8 +37,9 @@ ENVIRONMENT:
 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.1.1 (+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: 10/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

@@ -15,18 +15,35 @@ 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.";
 
-// 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;
   });
 }
 
@@ -37,15 +54,22 @@ export function sortByDateDesc(items) {
 // only the relative order within a randomized subset, not the corpus
 // rank — `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,
     },
   };
 }