untappd-mcp 2.3.2 → 2.5.0

package/dist/tools/user.js

@@ -16,6 +16,27 @@ function resolveUser(username, loginName) {
     }
     return encodeURIComponent(u);
 }
+/**
+ * user/venues sort values. Untappd silently IGNORES a value it doesn't know
+ * (the old 'name' / 'checkin' / 'highest_rated' never sorted anything), so the
+ * friendly aliases map onto the real keys. There is no rating sort for venues:
+ * 'highest_rated' is kept only so pre-existing callers don't start failing
+ * validation, as a DEPRECATED alias of highest_checkin.
+ */
+export const USER_VENUE_SORT_KEYS = {
+    date: 'date',
+    recent: 'recent',
+    date_asc: 'date_asc',
+    venue_name_asc: 'venue_name_asc',
+    venue_name_desc: 'venue_name_desc',
+    highest_checkin: 'highest_checkin',
+    lowest_checkin: 'lowest_checkin',
+    name: 'venue_name_asc',
+    checkin: 'highest_checkin',
+    /** @deprecated Untappd has no venue rating sort; kept for old callers. */
+    highest_rated: 'highest_checkin',
+};
+const USER_VENUE_SORTS = Object.keys(USER_VENUE_SORT_KEYS);
 export function registerUserTools(server, client) {
     server.registerTool('untappd_user_info', {
         title: 'Get Untappd user profile',
@@ -34,7 +55,9 @@ export function registerUserTools(server, client) {
     server.registerTool('untappd_user_checkins', {
         title: 'Get Untappd user check-ins',
         description: "Get a user's recent check-ins (most recent first): the beer, rating, comment, venue, and toasts/comments. " +
-            'Page backwards with max_id (the pagination.max_id from a prior call). Omit username for your own. Read-only.',
+            'Page backwards with max_id (the pagination.max_id from a prior call). Only your OWN history pages fully: for ' +
+            'any other user Untappd returns just the ~50 most recent check-ins and ignores max_id — use untappd_user_beers ' +
+            '(has had) or untappd_user_venues (has been) for their full history. Omit username for your own. Read-only.',
         annotations: toolAnnotations({ title: 'Get Untappd user check-ins', readOnly: true, idempotent: true, openWorld: true }),
         inputSchema: z.object({
             username: UsernameArg,
@@ -114,20 +137,28 @@ export function registerUserTools(server, client) {
     });
     server.registerTool('untappd_user_venues', {
         title: 'Get venues a user has checked in at',
-        description: "Get the venues a user has checked in at, most recent first, with per-venue check-in counts. Supports " +
-            'sorting and paging. Omit username for your own account. Read-only.',
+        description: "Get the venues a user has checked in at, most recent first, with per-venue first/recent visit and " +
+            'check-in counts. Pages fully for any public/friend account (unlike user check-ins, which stop at ~50 for ' +
+            'other users). Untappd returns at most 25 venues per page whatever limit you ask for — advance by the ' +
+            "returned pagination offset. Omit username for your own account. Read-only.",
         annotations: toolAnnotations({ title: 'Get venues a user has checked in at', readOnly: true, idempotent: true, openWorld: true }),
         inputSchema: z.object({
             username: UsernameArg,
-            limit: z.number().int().min(1).max(50).optional().describe('Max venues (1–50, default 25)'),
+            limit: z.number().int().min(1).max(50).optional().describe('Max venues (1–50; Untappd caps a page at 25)'),
             offset: z.number().int().min(0).optional().describe('Result offset for paging (default 0)'),
             sort: z
-                .enum(['date', 'name', 'checkin', 'highest_rated'])
+                .enum(USER_VENUE_SORTS)
                 .optional()
-                .describe('Sort order (default most recent)'),
+                .describe('Sort order (default most recent). Untappd keys: date, recent, date_asc, venue_name_asc, venue_name_desc, ' +
+                'highest_checkin, lowest_checkin. Aliases: name = venue_name_asc, checkin = highest_checkin. ' +
+                'highest_rated is deprecated (Untappd has no venue rating sort) and is sent as highest_checkin.'),
         }),
     }, async ({ username, limit, offset, sort }) => {
-        const data = await client.get(`/user/venues/${resolveUser(username, client.loginName)}`, { limit, offset, sort });
+        const data = await client.get(`/user/venues/${resolveUser(username, client.loginName)}`, {
+            limit,
+            offset,
+            sort: sort === undefined ? undefined : USER_VENUE_SORT_KEYS[sort],
+        });
         return minifiedResult(data);
     });
     server.registerTool('untappd_pending_friends', {

package/dist/tools/venue.js

@@ -1,7 +1,19 @@
 import { z } from 'zod';
 import { minifiedResult, resolveView, toolAnnotations, viewParam, viewResult } from '@chrischall/mcp-utils';
 import { compactCheckins, UNTAPPD_VIEWS, upstreamCompact } from '../compact.js';
-export function registerVenueTools(server, client) {
+import { walkVenueMenu } from '../menu/venue-menu.js';
+import { cachedResponse, VENUE_RESPONSE_TTL_MS } from '../cache/response-cache.js';
+import { optionalCache } from './cache-optional.js';
+import { favoriteLookup } from '../cache/favorites.js';
+const TTL_HOURS = VENUE_RESPONSE_TTL_MS / 3_600_000;
+const RefreshArg = z
+    .boolean()
+    .optional()
+    .describe(`Bypass the ${TTL_HOURS}-hour local cache and call Untappd (default false)`);
+export function registerVenueTools(server, client, cacheProvider) {
+    const cacheOrNone = optionalCache(cacheProvider);
+    /** The `cache` block a cached result carries (only when a cache is in use). */
+    const cacheBlock = (r) => r.expires_at === null ? {} : { cache: { hit: r.hit, fetched_at: r.fetched_at, expires_at: r.expires_at } };
     server.registerTool('untappd_search_venue', {
         title: 'Search Untappd venues',
         description: 'Search Untappd for venues (bars, breweries, restaurants) by name. Returns matches with their venue id, ' +
@@ -36,10 +48,15 @@ export function registerVenueTools(server, client) {
             'spans multiple sections — e.g. a 23-beer wall that comes back with 2 items. This tool forwards the ' +
             'section_limit / section_offset paging params venue/info echoes back but never receives, walks sections up to a ' +
             'per-call max_pages budget (respecting the ~100 calls/hour limit — it does NOT loop to completion in one call), and ' +
-            'flattens to [{bid, name, brewery, style, abv, price, serving_type, menu, section}]. Like the sync tools it is ' +
+            'flattens to [{bid, name, brewery, brewery_id, style, abv, price, serving_type, menu, section}]. Like the sync tools it is ' +
             'resumable: when the budget runs out before full coverage it returns another_run_needed:true plus next_section_offset ' +
             'to pass back on the next call. truncated:true means the upstream returned no more sections short of total_count ' +
-            '(e.g. it ignored the paging params) — not resumable. Get an id from untappd_search_venue. Read-only.',
+            '(e.g. it ignored the paging params) — not resumable. Results are cached locally for ' + TTL_HOURS + ' hours per ' +
+            'venue + paging params (cache.hit, fetched_at, expires_at) so repeated trip planning does not re-spend calls; ' +
+            'refresh:true re-fetches. With the cache, the result also carries favorite {is_favorite, sources, reason} for the ' +
+            'venue, and favorite / brewery_favorite on each beer that is one (derived from username\'s history or added ' +
+            'with untappd_favorite_add; default your account) — applied on read, so never stale. Get an id from ' +
+            'untappd_search_venue. Read-only.',
         annotations: toolAnnotations({ title: "Get a venue's verified beer menu (section-paged)", readOnly: true, idempotent: true, openWorld: true }),
         inputSchema: z.object({
             venue_id: z.number().int().positive().describe('Untappd venue id'),
@@ -48,119 +65,72 @@ export function registerVenueTools(server, client) {
             section_offset: z.number().int().min(0).optional().describe('Section offset to start from; pass a prior next_section_offset to resume (default 0).'),
             max_pages: z.number().int().min(1).max(10).optional().describe('API calls to spend THIS run — page budget, not page size (default 3). Resume with next_section_offset if another_run_needed.'),
             sort: z.string().optional().describe("Menu sort key (e.g. 'publish_order', 'highest_rated'). Optional."),
+            refresh: RefreshArg,
+            username: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Whose favorites to mark (cache only; default your configured account)'),
         }),
-    }, async ({ venue_id, menu_id, section_limit, section_offset, max_pages, sort }) => {
-        // venue/info pages its MENUS with limit/offset, but caps each menu's SECTION
-        // list — echoing `section_limit`/`section_offset` back as accepted params
-        // (the response even carries a `section_offset ` key with a stray trailing
-        // space; the real param name is the clean one the web menu UI sends). We
-        // forward them and walk sections, deduping by menu+section+bid so overlapping
-        // or param-ignoring pages can't double-count. Per CLAUDE.md's rate-limit
-        // design this spends at most `max_pages` API calls per run and hands the
-        // caller next_section_offset to resume, rather than looping to completion.
-        //
-        // Termination is driven by SECTION availability, not a running beer count:
-        // a page that returns fewer sections than we asked for is the end of the
-        // list. That's what makes resuming correct — this tool is stateless across
-        // calls, so on a resumed tail (section_offset > 0) `beers.length` covers
-        // only this run and can never equal the whole-menu total, which would
-        // otherwise mislabel a finished tail as truncated.
-        const pageSize = section_limit ?? 50;
-        const budget = max_pages ?? 3;
-        const startOffset = section_offset ?? 0;
-        let offset = startOffset;
-        const seen = new Set();
-        const beers = [];
-        let totalCount = 0;
-        let sawMenu = false;
-        let pagesFetched = 0;
-        let reachedEnd = false; // hit full coverage, or the section list ran out
-        for (let page = 0; page < budget; page++) {
-            const data = await client.get(`/venue/info/${venue_id}`, {
-                section_limit: pageSize,
-                section_offset: offset,
-                menu_id,
+    }, async ({ venue_id, menu_id, section_limit, section_offset, max_pages, sort, refresh, username }) => {
+        const key = `venue_menu:${venue_id}:${JSON.stringify([menu_id ?? null, section_limit ?? null, section_offset ?? 0, max_pages ?? 3, sort ?? null])}`;
+        const cache = cacheOrNone();
+        const r = await cachedResponse(cache, key, 'venue_menu', () => fetchMenu(), { refresh });
+        // Favorites are applied on read (not cached), so a change shows even on a cache hit.
+        const user = username ?? client.loginName;
+        if (!cache || !user)
+            return minifiedResult({ ...r.data, ...cacheBlock(r) });
+        const beers = (Array.isArray(r.data.beers) ? r.data.beers : []);
+        const ids = (k) => beers.map((b) => b[k]).filter((x) => typeof x === 'number');
+        const favs = await favoriteLookup(cache, [user], { venue: [venue_id], beer: ids('bid'), brewery: ids('brewery_id') });
+        return minifiedResult({
+            ...r.data,
+            favorite: favs.get('venue', venue_id),
+            beers: beers.map((b) => {
+                const beerFav = favs.get('beer', b.bid);
+                const breweryFav = favs.get('brewery', b.brewery_id);
+                return {
+                    ...b,
+                    ...(beerFav.is_favorite ? { favorite: beerFav } : {}),
+                    ...(breweryFav.is_favorite ? { brewery_favorite: breweryFav } : {}),
+                };
+            }),
+            ...cacheBlock(r),
+        });
+        async function fetchMenu() {
+            // Per CLAUDE.md's rate-limit design this spends at most `max_pages` API
+            // calls per run and hands the caller next_section_offset to resume, rather
+            // than looping to completion. The walk itself lives in walkVenueMenu.
+            const startOffset = section_offset ?? 0;
+            const walk = await walkVenueMenu(client, venue_id, {
+                menuId: menu_id,
+                sectionLimit: section_limit,
+                sectionOffset: startOffset,
+                maxPages: max_pages ?? 3,
                 sort,
             });
-            pagesFetched++;
-            const vb = data?.venue?.verfied_beers;
-            if (!vb) {
-                reachedEnd = true; // no menu payload — nothing more to page
-                break;
-            }
-            sawMenu = true;
-            let added = 0;
-            let matchedItemCount = 0;
-            let sectionsReturned = 0;
-            for (const wrap of vb.items ?? []) {
-                const menu = wrap?.menu;
-                if (!menu)
-                    continue;
-                if (menu_id && menu.menu_id !== menu_id)
-                    continue;
-                if (typeof menu.total_item_count === 'number')
-                    matchedItemCount += menu.total_item_count;
-                const sections = menu.sections?.items ?? [];
-                for (const section of sections) {
-                    sectionsReturned++;
-                    for (const it of section.items ?? []) {
-                        const beer = it?.beer;
-                        if (!beer || typeof beer.bid !== 'number')
-                            continue;
-                        const key = `${String(menu.menu_id)}:${String(section.section_id)}:${beer.bid}`;
-                        if (seen.has(key))
-                            continue;
-                        seen.add(key);
-                        const sectionName = section.section_name;
-                        beers.push({
-                            bid: beer.bid,
-                            name: beer.beer_name,
-                            brewery: it.brewery?.brewery_name,
-                            style: beer.beer_style,
-                            abv: beer.beer_abv,
-                            price: it.price?.value,
-                            serving_type: it.serving_type,
-                            menu: menu.menu_name,
-                            section: typeof sectionName === 'string' ? sectionName.trim() : sectionName,
-                        });
-                        added++;
-                    }
-                }
-            }
-            // Coverage target: with a menu_id filter, aim for THAT menu's own item
-            // count — verfied_beers.total_count spans every menu, so a single-menu
-            // slice could never reach it (it would burn the whole page budget and
-            // wrongly report a shortfall). Without a filter, the venue-wide total.
-            totalCount = menu_id ? matchedItemCount : typeof vb.total_count === 'number' ? vb.total_count : totalCount;
-            offset += pageSize;
-            if (totalCount > 0 && beers.length >= totalCount) {
-                reachedEnd = true; // full coverage from this walk
-                break;
+            const { totalCount, sawMenu, pagesFetched, reachedEnd } = walk;
+            const beers = walk.beers.map(({ rawBeer: _b, rawBrewery: w, ...b }) => typeof w?.brewery_id === 'number' ? { ...b, brewery_id: w.brewery_id } : b);
+            if (!sawMenu) {
+                return { venue_id, total_count: 0, returned: 0, pages_fetched: pagesFetched, another_run_needed: false, truncated: false, beers: [], note: 'No verified menu on this venue.' };
             }
-            if (sectionsReturned < pageSize || added === 0) {
-                reachedEnd = true; // a short (or all-duplicate) page is the end of the section list
-                break;
-            }
-        }
-        if (!sawMenu) {
-            return minifiedResult({ venue_id, total_count: 0, returned: 0, pages_fetched: pagesFetched, another_run_needed: false, truncated: false, beers: [], note: 'No verified menu on this venue.' });
+            const covered = totalCount > 0 && beers.length >= totalCount;
+            const another_run_needed = !reachedEnd; // stopped only because the page budget ran out mid-list
+            // Only a walk that started at the top of the list can judge a genuine
+            // shortfall as truncated; a resumed tail legitimately returns fewer than
+            // the whole-menu total_count and is not truncated.
+            const truncated = reachedEnd && !covered && startOffset === 0 && totalCount > 0;
+            return {
+                venue_id,
+                total_count: totalCount,
+                returned: beers.length,
+                pages_fetched: pagesFetched,
+                another_run_needed,
+                ...(another_run_needed ? { next_section_offset: walk.nextOffset } : {}),
+                truncated,
+                beers,
+            };
         }
-        const covered = totalCount > 0 && beers.length >= totalCount;
-        const another_run_needed = !reachedEnd; // stopped only because the page budget ran out mid-list
-        // Only a walk that started at the top of the list can judge a genuine
-        // shortfall as truncated; a resumed tail legitimately returns fewer than
-        // the whole-menu total_count and is not truncated.
-        const truncated = reachedEnd && !covered && startOffset === 0 && totalCount > 0;
-        return minifiedResult({
-            venue_id,
-            total_count: totalCount,
-            returned: beers.length,
-            pages_fetched: pagesFetched,
-            another_run_needed,
-            ...(another_run_needed ? { next_section_offset: offset } : {}),
-            truncated,
-            beers,
-        });
     });
     server.registerTool('untappd_venue_by_foursquare', {
         title: 'Look up an Untappd venue by Foursquare id',
@@ -177,17 +147,23 @@ export function registerVenueTools(server, client) {
     server.registerTool('untappd_venue_activity', {
         title: 'Get recent check-ins at a venue',
         description: 'Get the recent public check-ins at a venue by its id — who was there, what they drank, and their ratings. ' +
-            'Page backwards with max_id (the pagination.max_id from a prior call). Read-only.',
+            'Page backwards with max_id (the pagination.max_id from a prior call). Cached locally for ' + TTL_HOURS + ' hours ' +
+            'per venue + limit + max_id (cache.hit, fetched_at, expires_at); refresh:true re-fetches. Read-only.',
         annotations: toolAnnotations({ title: 'Get recent check-ins at a venue', readOnly: true, idempotent: false, openWorld: true }),
         inputSchema: z.object({
             venue_id: z.number().int().positive().describe('Untappd venue id'),
             limit: z.number().int().min(1).max(50).optional().describe('Max check-ins (1–50, default 25)'),
             max_id: z.number().int().positive().optional().describe('Return check-ins older than this id (for paging)'),
+            refresh: RefreshArg,
             view: viewParam(UNTAPPD_VIEWS, { note: 'compact projects each check-in to {id, user, beer, brewery, venue, rating, comment, toast/comment counts}; "full" returns Untappd\'s whole ~5 KB record.' }),
         }),
-    }, async ({ venue_id, limit, max_id, view }) => {
-        const data = await client.get(`/venue/checkins/${venue_id}`, { limit, max_id });
+    }, async ({ venue_id, limit, max_id, refresh, view }) => {
+        // The RAW response is cached, so either view can be served from one entry.
+        const key = `venue_activity:${venue_id}:${limit ?? ''}:${max_id ?? ''}`;
+        const r = await cachedResponse(cacheOrNone(), key, 'venue_activity', () => client.get(`/venue/checkins/${venue_id}`, { limit, max_id }), { refresh });
         const v = resolveView(view, UNTAPPD_VIEWS);
-        return viewResult(v, v === 'compact' ? compactCheckins(data) : data);
+        const shaped = v === 'compact' ? compactCheckins(r.data) : r.data;
+        const extra = cacheBlock(r);
+        return viewResult(v, Object.keys(extra).length && shaped && typeof shaped === 'object' ? { ...shaped, ...extra } : shaped);
     });
 }

package/dist/version.js

@@ -3,4 +3,4 @@
 // json's `extra-files`), and `versionSyncTest` guards that it stays equal to
 // package.json. Import VERSION wherever the version is needed rather than
 // re-declaring it.
-export const VERSION = '2.3.2'; // x-release-please-version
+export const VERSION = '2.5.0'; // x-release-please-version

package/mint.yaml

@@ -5,6 +5,18 @@ summary: >-
   Search Untappd beers, breweries, and venues; read profiles, check-ins,
   wishlists, and your friend feed; and post check-ins, toasts, and comments
   to your account
+examples:
+  - prompt: >-
+      What's trending on Untappd right now? Split it into the big macro beers
+      and the smaller craft ones.
+    note: Read-only; uses the trending beers list.
+  - prompt: >-
+      Look up Tree House Brewing on Untappd and list their highest-rated beers.
+    note: Read-only; brewery search, then its beer list sorted by rating.
+  - prompt: >-
+      Here's the tap list at the bar I'm at. Which two of these have I not had
+      yet, ranked by rating?
+    note: Checks your synced check-in history; nothing is posted.
 env:
   - name: UNTAPPD_USERNAME
     required: true
@@ -31,6 +43,11 @@ env:
     help: >-
       IANA timezone (e.g. America/New_York) that check-ins are stamped with
       when a call passes no timezone. Defaults to the server's own zone.
+  - name: UNTAPPD_RATE_LIMIT_PER_HOUR
+    required: false
+    help: >-
+      Hourly Untappd API call limit the syncs' stop-before-429 guard enforces
+      (default 100, Untappd's documented per-token limit).
   - name: UNTAPPD_PHOTO_DIR
     required: false
     help: >-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "untappd-mcp",
-  "version": "2.3.2",
+  "version": "2.5.0",
   "mcpName": "io.github.chrischall/untappd-mcp",
   "description": "Untappd MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -58,5 +58,9 @@
     "typescript": "^7.0.2",
     "vite": "^8.2.2",
     "vitest": "^5.0.0"
+  },
+  "allowScripts": {
+    "esbuild": false,
+    "fsevents": false
   }
 }

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/untappd-mcp",
     "source": "github"
   },
-  "version": "2.3.2",
+  "version": "2.5.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "untappd-mcp",
-      "version": "2.3.2",
+      "version": "2.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -79,6 +79,13 @@
           "format": "string",
           "isSecret": false
         },
+        {
+          "name": "UNTAPPD_RATE_LIMIT_PER_HOUR",
+          "description": "Hourly Untappd API call limit the syncs' stop-before-429 guard enforces (default 100, Untappd's documented per-token limit). Only change it if Untappd gives your token a different limit.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
         {
           "name": "UNTAPPD_PHOTO_DIR",
           "description": "The directory untappd_checkin's photo_path must be inside (several allowed, separated by :). Defaults to ~/Downloads/untappd-mcp — put a photo there to attach it. Any other file is refused, so a prompt-injected shout or comment can't publish an arbitrary image from your disk.",
@@ -92,6 +99,13 @@
           "isRequired": false,
           "format": "string",
           "isSecret": false
+        },
+        {
+          "name": "UNTAPPD_CACHE_DIR",
+          "description": "Directory for the cache instead of ~/.untappd-mcp (the file is checkins.db inside it). UNTAPPD_CACHE_DB wins if both are set. Local/stdio only.",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
         }
       ]
     }

package/skills/untappd-mcp/SKILL.md

@@ -205,6 +205,36 @@ Query tools (has-had ones consult BOTH sources — a hit in either = had):
   capped at `api_budget` per run (partial/another_run_needed when exceeded).
 - `untappd_cache_query` — filter cached check-ins by brewery, style, `min_rating`,
   venue, and date range.
+- **Groups:** `untappd_cache_has_had_many` and `untappd_top_not_had` take
+  `usernames` (instead of `username`) plus `mode`: `none_had` (default — new to
+  everyone) or `any_not_had` (at least one of them still needs it). Each beer
+  lists `had_by` / `not_had_by`; freshness is reported per user.
+- `untappd_sync_venue_drinks` — opt-in, costs one call per check-in: fetches the
+  beer from each cached venue's first/recent visit (`checkin/view`), budgeted by
+  `max_calls`; `untappd_cache_has_visited` then shows them as `drinks`. Partial
+  by design (two check-ins per venue at most).
+- **Favorites** (local, no API): `untappd_favorites_list` (filter `kind`
+  beer|brewery|venue, `source` derived|manual|untappd, override `thresholds`),
+  `untappd_favorite_add` / `untappd_favorite_remove` (manual, with a note —
+  never written to Untappd). Derived defaults: venue ≥5 check-ins or ≥3 distinct
+  months; brewery ≥5 beers with avg ≥3.75, or ≥15 beers; beer rated ≥4.25 or
+  had ≥3 times. has_had / has_had_many / has_visited / brewery_beers / venue_menu /
+  top_not_had results carry `favorite` {is_favorite, sources, reason};
+  `untappd_top_not_had` boosts wishlisted (+0.5) and favorite-brewery (+0.25)
+  beers unless `prefer_favorites: false`. `untappd_sync_brewery_likes` mirrors
+  the breweries a user likes/follows on Untappd (resumable, rate-guarded); they
+  carry the source `untappd` (merged with derived/manual) and count for the boost.
+  Untappd has no followed-venue list, so venue favorites are derived + manual.
+  `brewery_info`'s `follow_status` is the signed-in account's, never another user's.
+- `untappd_trip_check` — a whole trip in one call: per stop (`venue_id`, `name`
+  + `city`/`state`, `lat`/`lng`, and/or `brewery_id`) → visited with dates,
+  beers had from that brewery, and the top N (default 4) not-had beers by global
+  rating (`style` filter). Cache only, except `brewery/beer_list` for a missing or
+  >7-day-old list (`api_budget`, default 5; 0 = cache only). Flags favorite
+  venues/breweries, boosts wishlist/favorite-brewery beers (`prefer_favorites`),
+  and hints when a favorite venue is within `near_favorite_radius_m` (2 km).
+  Sync first: `untappd_sync_user_venues`, `untappd_sync_user_beers`,
+  `untappd_sync_wishlist`, `untappd_sync_brewery_likes`.
 
 **Retention.** The cache keeps what you sync until you remove it — including
 friends' dated check-ins, comments and venues. `untappd_cache_forget` (confirmation-gated)