diff --git a/diigo-cache/src/query.ts b/diigo-cache/src/query.ts
index 596cb1c..67767d7 100644
--- a/diigo-cache/src/query.ts
+++ b/diigo-cache/src/query.ts
@@ -1,30 +1,6 @@
 /**
- * @file the public page's filters — goal 1d, **not yet implemented**: the
- * design is pinned by the skipped suites in tests/query.test.ts and
- * tests/caches.test.ts ("public page filters").
- *
- * One filter, two spellings: devs pass a {@link FilterSpec} object
- * (`{ days: 7, q: "#weekly" }`); URLs carry the same fields as params
- * (`?days=7&q=%23weekly`, empty fields = absent). `q` also takes the
- * search operators large audiences already know — gmail's `after:`,
- * `before:`, `newer_than:7d`; Slack's `during:` (alias `in:`); GitHub's
- * `created:`/`updated:` — plus words, `"phrases"`, `#tag`/`tag:tag`, and
- * `-` negation.
- *
- * Time is UTC (Z) throughout; weeks are ISO 8601 (Monday first, so a
- * weekend stays together). Every window is half-open: `after` inclusive
- * from 00:00Z, `before` exclusive at 00:00Z — so GitHub's inclusive
- * `a..b` ranges are deliberately not offered.
- *
- * Applied while walking diigo's pages (updated-desc). `by=updated` finds
- * an old window by binary search over the sorted pages; `by=created`
- * walks from page 1 (an old bookmark edited lately sits near page 1).
- * Either way a request spends at most {@link FETCH_BUDGET} diigo fetches
- * (cached pages are free) and says so when results are incomplete.
- *
- * @see https://mailmeteor.com/blog/search-gmail-by-date
- * @see https://slack.com/help/articles/202528808
- * @see https://docs.github.com/en/search-github/searching-on-github/searching-for-repositories
+ * @file the public page's filters: date windows and search (goal 1d, **not
+ * yet implemented**; the design is the skipped specs in tests/query.test.ts).
  */
 
 import type { Item } from "./items.js";
@@ -38,10 +14,11 @@ import type { Item } from "./items.js";
 export const FETCH_BUDGET = 40;
 
 /**
- * a filter as devs write it; URL params map onto these fields one-to-one
- * (strings, with "" meaning absent). Dates are `yyyy-mm-dd` (gmail's
- * `yyyy/mm/dd` too); periods are `2025`, `2025-03`, `2025-Q1`, or ISO week
- * `2025-W01`.
+ * a filter as devs write it (`{ days: 7, q: "#weekly" }`); URL params map
+ * onto these fields one-to-one (strings, with "" meaning absent). Dates
+ * are `yyyy-mm-dd` (gmail's `yyyy/mm/dd` too); periods are `2025`,
+ * `2025-03`, `2025-Q1`, or ISO week `2025-W01`. Time is UTC throughout;
+ * ISO weeks start Monday, keeping a weekend together.
  */
 export type FilterSpec = {
 	/** the last N days, counted back from now (1–3650) */
@@ -83,6 +60,17 @@ export type QueryError = { error: string };
  * resolve a filter: fields and `q` operators combine; a bound given twice
  * (by fields, operators, or both) is refused, as is an empty window.
  *
+ * `q` takes the operators large audiences know: gmail's `after:`,
+ * `before:`, `newer_than:7d`; Slack's `during:` (alias `in:`); GitHub's
+ * `created:`/`updated:` with a period; plus words, `"phrases"`,
+ * `#tag`/`tag:tag`, and `-` negation. Every window is half-open: `after`
+ * inclusive from 00:00Z, `before` exclusive at 00:00Z (so no inclusive
+ * GitHub `a..b` ranges).
+ *
+ * @see https://mailmeteor.com/blog/search-gmail-by-date
+ * @see https://slack.com/help/articles/202528808
+ * @see https://docs.github.com/en/search-github/searching-on-github/searching-for-repositories
+ *
  * @param now the clock `days`/`newer_than` count back from (passed in,
  * not read ambiently, so tests pin it)
  */