Discover posts via an XML sitemap (POSTS_SITEMAP_URL or the sitemap_url arg), a JSON override list (POSTS_LIST), or - if configured - the Ghost Admin API. Pass an explicit urls[] to skip discovery entirely.

Returns metadata: url, title, published_at, age_days, tags. Filter by minimum age or published-after date.

When to use: discover which URLs are eligible for snapshot / verdict / cohort analysis. Works with any CMS that exposes a sitemap.

Pull a 30/60/90-day snapshot across every configured signal source for one post: GSC clicks/impressions/CTR/position + top queries, Matomo visits + dwell, GA4 pageviews, Clarity scroll/rage clicks, AI-citation counts.

Each source is best-effort: if its env vars are missing the field is omitted. Returns whatever is available.

Read-only. No third-party writes. Optionally persists to the local DuckDB cache when persist=true.

Bucket GSC clicks/impressions/avg-position into ~weekly windows for the last N weeks (default 12) and classify the trend: decay / plateau / growth.

Underpins the verdict engine's decay rules. Read-only GSC query.

Run the rule-based verdict engine on a single post: combine snapshot + decay curve and emit a verdict with reason codes and a 0-1 confidence score.

Reason codes are deterministic. The mapping reasons -> verdict lives in src/verdict/rules.ts and can be inspected.

Reporting only - does NOT mutate anything. To act on the verdict, hand the brief to a writer or to an AI rewrite tool.

Produce a markdown brief for a human (or downstream LLM) editor: verdict + reasons + raw numbers + top queries + suggested actions.

Use this as the hand-off artefact when verdict is refresh / expand / merge / double_down.

Run the verdict engine across a cohort (filtered by tag and/or min-age) and return a ranked table sorted by verdict priority then confidence.

Practical use: 'which three posts should I refresh this week?' - the top three rows with verdict=refresh and highest confidence are the answer.

Return the list of LLMs that previously cited this URL but no longer do, with the prior query and last-seen date. Optionally includes the URL that replaced ours.

Requires a configured citation-intelligence MCP endpoint (CITATION_INTELLIGENCE_URL). Otherwise returns an empty list.

Scan GSC for (page, query) pairs sitting in positions 5-15 with non-trivial impressions and a CTR below their position-expected curve. These are the fastest title-rewrite wins.

Returns top results sorted by impressions desc. Pure GSC pull - platform-agnostic.