Forq

Tell Forq what you are eating; it works out what to buy; it helps you waste less.

See the value in 30 seconds: Open the instant demo — live at https://food-shopping-os.vercel.app/demo.

Why this is different

Most AI food tools show a recommendation or a score. Forq makes the whole loop inspectable:

1. Plan meals — 2. Buy exactly what you need — 3. Waste less.

It does not invent a pretend household or hide uncertainty behind a polished number. The demo is seeded, requires no account, and is isolated from real data so visitors can click through the plan, shopping list, pantry, receipts and cooking surfaces safely.

See it in 10 seconds

Visit /demo to see a seeded week with a plan, pantry-aware shopping, receipt history and the complete loop. Then choose Explore an example week first to enter the interactive sandbox. Nothing is saved, synced, or counted toward analytics. From the walkthrough you can Use this demo week as my starting plan: the sandbox closes, the dinners are rebased onto this week as your real plan, and Review plan navigates to it — adopting never carries demo pantry, receipts, or analytics with it.

Product loop

┌──────────────┐    ┌───────────────────┐    ┌──────────────┐
│ Plan meals   │ -> │ Subtract pantry   │ -> │ Shop list    │
└──────────────┘    └───────────────────┘    └──────┬───────┘
                                                     │
                                                     v
┌──────────────┐    ┌───────────────────┐    ┌──────────────┐
│ Waste less   │ <- │ Learn from reality│ <- │ Cook & log   │
└──────────────┘    └───────────────────┘    └──────────────┘

Demo media

/demo is the canonical visual walkthrough: the meal decision, the pantry-aware list, and the closed loop after cooking. To add a screen recording, put it at public/demo/forq-demo.gif and embed it above this line.

One app for the weekly food loop: plan meals, buy exactly what you need, waste less. Mobile-first PWA-style web app built with Next.js 16 + React 18 + Tailwind CSS 4, styled in a calm monochrome design language: ink-on-neutral surfaces, border-first cards, black-on-white CTAs, and monochrome stroke iconography (lucide-react) throughout — no emoji in the UI.

The app starts empty. There is no demo user, no pretend pantry, no invented spending history and no pre-earned achievements. A first run asks for your name, budget and targets, and from then on every number you see is computed from what you actually log, buy, cook and plan. Backups can be exported and restored, including from first-run setup. Invalid saved data opens a recovery screen instead of being silently replaced. Forq is local-first by default and no account is required.

Where your data lives. IndexedDB is the canonical store: one record, one writer, written asynchronously and transactionally, with no ceiling to hit. localStorage holds only what genuinely belongs there — a small pointer describing the canonical record, the encrypted health vault, and the cloud-sync metadata. A pre-existing localStorage install is migrated into IndexedDB on first load and the local copy is dropped after the new record is committed, so a failed upgrade loses nothing and the app keeps running from the old copy. A browser that cannot open IndexedDB falls back to the localStorage copy and says so rather than pretending. Two tabs agree through a BroadcastChannel that carries only a "something changed" signal — never the state itself — and each tab reads the canonical record, so localStorage is a signpost rather than the thing two tabs fight over. Every write carries a monotonic sequence, so a slow write can never land on top of a newer one. A record saved by a newer version of Forq is reported and left exactly as found, never rewritten.

Signing in is an opt-in to Upstash Redis household sync. When a user chooses a server-backed AI action, Forq relays that prompt and its relevant context to the configured free-tier model (NVIDIA NIM or OpenRouter), or to OpenAI when the free ladder cannot answer and a paid key is configured.

The only data that ships with the app is reference material, not user data: a recipe book, a food/barcode/restaurant nutrition catalogue, per-100 g nutrient tables and UK reference intakes.

Backend setup

Forq runs on Next.js and keeps its local-first store. The backend is optional: without environment variables it stays local-only; with them it offers opt-in Auth.js accounts, Upstash Redis household sync, Ably or Redis live updates, private receipt uploads, calendar reads and writes, open product observations and a free-tier AI ladder (NVIDIA NIM first, OpenRouter second) with an optional paid OpenAI relay.

1. Copy .env.example to .env.local.
2. Create an Upstash Redis database and set UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN.
3. Generate AUTH_SECRET with at least 32 random bytes.
4. Add Google, Apple and/or Microsoft OAuth credentials.
5. Run npm run db:migrate to record the current data-store migration.
6. Run npm run dev.

No credentials yet? node scripts/dev-preview.mjs runs the whole stack against a local in-memory Redis behind an Upstash-compatible bridge, with a preview-only sign-in (AUTH_DEV_LOGIN) that needs no OAuth account — the fastest way to see live prices, the market fallback and Open Prices populate in the app. Data is in-memory and disposable, and it is not a development mode for production.

npm run db:check verifies the connection and applied migrations. Production deployments should run npm run db:migrate as a controlled release step before the new application version receives traffic.

The first sign-in copies existing on-device data to the user's personal household. Later writes use optimistic versions: a concurrent change returns a conflict and does not overwrite either copy. Open browser tabs update immediately, and private Ably channels (or a Redis-backed stream when Ably is not configured) push new household versions to subscribed clients. Upstash Redis remains the source of truth. Receipt images require Vercel Blob. AI calls run only on the server and need a free-tier key (NVIDIA_API_KEY or OPENROUTER_API_KEY); the paid OpenAI relay additionally needs OPENAI_API_KEY. Optional product insights are off until enabled under Privacy & data. They record only coarse daily counts for the plan, shop and cook journey, and are uploaded only for a signed-in household; they never include food names, health values, recipe text or prices. AI_MONTHLY_TOKEN_LIMIT sets the hard monthly allowance per household; it defaults to 250,000 reserved-and-used tokens. Signed-in users can see the current month’s used, reserved and remaining allowance under Account & sync; prompts and responses are not included in that usage record.

Live shop prices come from /api/integrations/scrape-prices, which reads each retailer's public search page when you ask it to. It is not a retailer feed and not a quote: robots.txt is checked before every fetch, a shop that declines or blocks the request is reported as declining rather than dropped, and each price keeps the URL it was read from so you can check it. Prices published as schema.org data are taken verbatim; where a shop publishes none, the page text is read and the result is labelled as a lower-confidence reading. Many UK retailers only price after a store or postcode is chosen, so an empty result is a normal and honest outcome. The retailer hub still keeps your recorded receipt prices and saved offers, and still links to the official retailer site so you can confirm today's basket, stock and delivery or collection options yourself.

Every item on the list is checked, not a sample of it: a comparison that silently covers six of your twenty items is worse than useless, because it looks complete. The list goes up in batches, and the route stops starting new items when it nears its time budget and names the rest in remaining, which the client sends on — so a long list finishes across several requests rather than being cut off by a serverless timeout. Progress is shown while it runs and the run can be stopped.

A few shops are checked at once, but never the same shop twice at once: workers pull from a shared queue, so each retailer still receives strictly one request at a time with a gap after it. One request each at three different shops is three ordinary visitors; three at one shop is a burst.

The route is signed-in only, rate-limited to 60 requests an hour (up to 12 items each), and cached three hours on device.

The food catalogue

Around 510 foods, roughly 395 generic and 115 branded, split across files by what they are: core staples, the expanded generic list, the store cupboard, the deli/dessert/freezer counter, and two branded waves.

Every food can be graded. That is a deliberate invariant with a test behind it: the health grade refuses to score without sugar, saturated fat and salt, so a row missing them would silently lose its grade rather than fail loudly. Rows added after the original files state those three outright via src/data/food-row.js instead of hoping a micronutrient profile exists.

Two integrity checks guard the figures, because hand-entered nutrition data fails by typo rather than by design:

• Energy against macros — every row's stated kcal is checked against 4×protein + 4×carb + 9×fat + 2×fibre, the UK/EU calculation. Fibre at 2 kcal/g is not a detail: leave it out and every spice looks fabricated, because a third of ground cinnamon is fibre. Alcohol (7 kcal/g) is not modelled, so rows tagged alcohol are exempt.
• Sub-components against parents — sugar never exceeds carbohydrate, saturated fat never exceeds fat.

Naming follows the catalogue's own convention: qualifiers go after a comma ("Lentils, cooked", "Pesto, green"), because the matcher ignores anything after a comma or inside brackets. That is what lets a shopping list saying "pesto" find the entry while "milk" still refuses to match "Milk chocolate".

Branded products

The catalogue carries popular UK branded groceries — Heinz Baked Beans, Cathedral City, Warburtons, Quorn, Cadbury and so on — as entries in their own right alongside the generics. Two reasons, both practical:

• Nutrition differs by brand. Two tins of beans on the same shelf are not the same food, and a health grade built from a generic average is a grade for something nobody bought.
• A retailer search for a named product finds it. "Baked beans" comes back as a wall of results the scraper cannot confidently price; "Heinz Baked Beans" comes back as a product. Where a generic list item has named products behind it, the price panel offers them and can price one on the spot — without rewriting your list, because deciding that "beans" means Heinz is your call.

Every branded row states sugar, saturated fat and salt explicitly rather than inheriting a generic profile. Those three drive the health grade, and an unknown there used to be read as zero — which would quietly grade a chocolate bar better than a bag of lentils. The grade now declines to score at all when they are unknown.

Figures are typical published per-100g label values. Manufacturers reformulate: the pack in your hand is the authority.

Tags, filtering and sorting

Each priced item carries tags, drawn from four sources that are worth different amounts and kept apart rather than flattened into one confident list:

Source	Tags	Evidence
Nutrition	high protein, source of protein, high/source of fibre, high sugar/salt/saturated fat, a health grade A–E	A confident match against the food catalogue, then the UK/EU labelling thresholds — "high protein" means the regulated 20% of energy, not "quite a lot".
Diet	contains meat, contains fish, vegetarian, vegan (labelled), no animal ingredient named	The matched catalogue entry's own tags where there is one, the product name otherwise. A filter, never a certification.
Processing	minimally processed, culinary ingredient, processed, ultra-processed	The product name, and labelled "(est.)" because a name is weak evidence.
Value	good value somewhere, cheaper/dearer than usual, from £x/kg	This item's own prices across shops and over time. Never a judgement about a product from its price alone.
Availability	newly listed at a shop	A shop pricing it now that was not in the previous check.
You	bought before, you buy this often	Your own recorded shops.

The catalogue match is deliberately strict: searchFoods answers "milk" with "Milk chocolate", and a nutrition tag hung on the wrong food is worse than no tag, so a match only counts when every meaningful word of the catalogue name appears in what you typed. "Semi-skimmed milk" matches; bare "milk" gets no nutrition tags rather than the wrong ones.

Allergens only ever warn. They are matched on a product name, which is good enough to raise "may contain" and nowhere near good enough to promise that something is free of anything — so the tag exists in that direction only, and appears only for allergens the household has actually declared. In the filter row they are phrased as "hide items that may contain".

Filters combine with AND, so each tag you add narrows the list — selecting several and getting a longer list would be the opposite of filtering. Only tags something actually carries are offered, with counts, so no filter is a dead end. Sorting covers cheapest, best value per kg, healthiest, most bought, biggest gap between shops, and A–Z; anything unrankable (no readable pack size, no catalogue match) sorts last rather than being treated as zero.

Ranking and price history

Each item shows its shops ranked cheapest to dearest, with the gap to the cheapest in pounds and percent — "Asda is 3p (3.4%) dearer" is a decision where two bare prices are only two facts. Tied shops share a rank.

Every check is also kept on the device, one observation per item per shop per day, so asking repeatedly builds a price history: a timeline of the item's cheapest price, a small chart per shop, and which shop has been cheapest most often — which is a better guide than whoever happens to be cheapest today. History never leaves the device and is cleared with the cache.

A price for every item

The live scraper cannot have a 100% hit rate, and that is not a parser bug to fix. Several shops forbid their search pages in robots.txt; several more return 403 to anything that is not a browser; many UK grocers publish no price at all until a store is chosen. The ways round those are ignoring robots.txt and evading bot detection, and Forq does neither.

So the scraper is not the only source. Four already exist, each right about something slightly different, and every item is resolved through all of them:

Source	What it is	Worth
Live from the shop	read from a shop's page just now	most current, least certain it is the product you meant
You paid this	your own receipt	certainly the right product, possibly months old
From an earlier check	a previous live check, kept on this device	dated, and it was a search result
Community observed	a dated Open Prices report	often another town

Each candidate is scored as source weight × freshness, where freshness halves roughly every three months rather than falling off a cliff. That is why a three-day-old receipt beats a 200-day-old community report, and why a two-day-old check beats a year-old receipt — a fixed ranking could not express either.

Every row shows which source answered and how old it is, and the basket total says what share of it is live, so it never quietly borrows the authority of its freshest row. Where two sources disagree by more than half, that is flagged: it usually means a search matched a different product rather than the price moving.

Nothing is ever invented to fill a gap. An item no source knows about says so. A made-up number would look exactly like a real one at a glance, which is the failure this design exists to prevent.

Why a plain fetch is not enough

Most UK grocery search pages render their products in the browser. The HTML that arrives from a plain fetch is an empty shell, and no amount of better parsing finds a price that was never in the document. So fetching escalates through a ladder, and a page is only "done" when it actually yields prices — HTTP 200 on a shell is a miss, not a hit:

Strategy	Needs	Returns	Notes
monid	MONID_API_KEY	whatever the configured endpoint returns	Leads the ladder when configured. Runs one scraping endpoint through Monid's API (MONID_SCRAPE_PROVIDER / MONID_SCRAPE_ENDPOINT); free on this workspace's plan. Renders JavaScript, and HTML keeps the structured passes — plain text drops to the text pass. A run takes seconds to minutes.
direct	nothing	raw HTML	Free and instant. Works on server-rendered shops. Leads when no Monid key is set.
firecrawl	FIRECRAWL_API_KEY	rendered HTML + markdown	Headless render. Costs credits, so it is only reached when the rungs before it found nothing. Asks for rawHtml, so structured parsing still applies.
jina	nothing	markdown	r.jina.ai, keyless, renders JavaScript. Markdown only, so just the text pass can read it — hence last.

Escalation is what raises the hit rate: a shop that returns a shell to direct gets retried through a renderer before it is written off as having no prices. Each row records which strategy produced it, and the UI says "page rendered to load prices" where a renderer was needed.

robots.txt still governs everything. A renderer is not a way around a shop that declined — the permission check runs before any strategy, and a refusal means no fetch by any route.

When the shops stay silent

Several UK grocers never show a headless renderer their prices: some gate the grid behind a postcode, some refuse every route, one forbids the crawl in robots.txt. So when every checked shop came back without a price, the scraper runs one Google Shopping query through Monid (apify /burbn/google-shopping-scraper) and folds the market's answers in: a listing for a checked shop fills that shop's empty result, and listings from shops not being checked land in an "Other shops" group so nothing is thrown away. Market rows are labelled with their provenance (Google Shopping (Asda) listing) and carry medium confidence — they are the store's own listing, but not a price read from its page. Set PRICE_SCRAPER_MARKET=off to disable, or on to run it even when the shops answered.

Environment variables

Variable	Default	What it does
NVIDIA_API_KEY	unset	Free NVIDIA NIM catalogue (first on the ladder). Powers the AI assistant and the scraper's fallback extraction. No credential ships with the app — set this to enable NVIDIA, or to an empty string to turn it off explicitly.
OPENROUTER_API_KEY	unset	Free OpenRouter catalogue (second on the ladder). Used when NVIDIA is not configured.
OPENROUTER_BASE_URL	https://openrouter.ai/api/v1	Override the OpenRouter endpoint (tests, self-hosted gateways).
NVIDIA_BASE_URL	https://integrate.api.nvidia.com/v1	Override the NVIDIA NIM endpoint (tests, self-hosted gateways).
OPENAI_API_KEY	unset	Paid OpenAI relay for requests the free ladder cannot answer. Free-tier models are unmetered; OpenAI calls draw on the household monthly budget (AI_MONTHLY_TOKEN_LIMIT).
OPENAI_MODEL	gpt-5-mini	Model used by the paid OpenAI relay.
FIRECRAWL_API_KEY	unset	Enables the Firecrawl render strategy. Without it the ladder skips Firecrawl.
FIRECRAWL_BASE_URL	https://api.firecrawl.dev/v2	Pin an API version or point at a self-hosted Firecrawl.
FIRECRAWL_WAIT_MS	2500	How long Firecrawl waits after load before capturing — raise it for slow shops.
MONID_API_KEY	unset	Enables the Monid strategy and puts it at the front of the ladder. Generate a key at app.monid.ai/access/api-keys.
MONID_SCRAPE_PROVIDER	context.dev	Which Monid provider the strategy runs. Pick one with monid discover -q "uk grocery prices".
MONID_SCRAPE_ENDPOINT	/web/scrape/html	Which Monid endpoint to run. Confirm its input schema with monid inspect before changing it.

On credentials. No credential ships with the app — a key in a public repository can be spent by anyone, cannot be rotated without a release, and is blocked by secret scanning. Deployments bring their own: NVIDIA_API_KEY and/or OPENROUTER_API_KEY for the free AI ladder, OPENAI_API_KEY for the paid relay. Every other secret belongs in .env.local (gitignored) locally and in your hosting provider's environment settings for a deployment. Responses from the free ladder carry the actual provider (nvidia or openrouter) and model, and the /api/ai route propagates both — NVIDIA answers are never labelled as OpenRouter.

Barcode lookups can optionally use the public Open Food Facts API through the authenticated /api/integrations/products route. It returns product identity, ingredients, allergens, nutrition, labels and scores when the barcode is in that catalogue. /api/integrations/prices can query Open Prices for GBP observations by barcode or exact product name — the same route powers the Shop list's "Check community prices" action and the Prices dashboard. Open Prices is a community dataset: its observations can be old, incomplete or from a different shop, so Forq labels them as observed with the date and a staleness tag (fresh <7d · ageing 7–30d · old >30d) and never treats them as a live supermarket quote. Observed rows are fetched only after an explicit tap, cached 24h on device for a list of up to 12 items, and rate-limited at 120/h. Both lookups run only after an explicit user action and require a signed-in backend household.

The UK supermarkets do not expose one common public third-party price API, so the live check reads the same public search pages a shopper would open, subject to robots.txt. Forq does not query undocumented private retailer endpoints and does not attempt to bypass a shop that blocks automated requests. Scheduled reminders use the authenticated /api/jobs/reminders endpoint and Vercel Cron. Trigger.dev can invoke the same endpoint once its current vulnerable SDK dependency chain is patched.

Pulse connection

Forq can be read by Pulse, the personal evidence engine in this ecosystem, when both apps are served from one origin. Sharing is opt-in and controlled here, where the data originates: Settings → Privacy has a "Share with Pulse" switch. Pulse reads Forq's own state (forq-state-v2) directly — it never receives or stores a copy — and its connector refuses to read anything unless this flag (forq-pulse-opt-in) is on. Turning the switch off clears only the flag; Forq's own data is never deleted or moved.

Features

• First-run setup — name, household size, weekly budget, how you eat, and what you're aiming at. It also asks for weight, height, age and sex, because together they let Forq estimate your maintenance calories instead of asking you to already know the number — sex is in there because Mifflin-St Jeor's constants differ by 166 kcal, which after the activity multiplier is a couple of hundred a day, and "rather not say" takes the midpoint rather than picking one for you. The weight you give starts your body series rather than sitting apart from it. Cycle tracking is a yes/no at setup, off by default, offered to everyone rather than inferred from an answer. Every one of them is editable afterwards. Age is asked on the context step rather than inside the optional nutrition block, because it decides which app the rest of setup builds

• Under-18 mode — automatic from that age, not a switch anyone has to find, and on for a household child profile too. It sets targets at maintenance and will not apply a weight-loss or body-recomposition multiplier; drops the weekly calorie budget, so a bigger day is never a debt to pay back; hides fasting and alcohol targets; reads caffeine against age and weight (EFSA's 3 mg/kg for children and adolescents) rather than the adult 400 mg; never converts exercise into calories to eat back; stops scoring exact calorie adherence in streaks, XP and challenges; shows no BMI band, because the NHS reads child weight against age- and sex-specific centiles; and makes no body prediction or comparison between people. What it says instead is balanced meals, regular eating and variety, with a plain pointer to a parent or carer, a GP, a school nurse or a registered dietitian for anything about weight, growth or eating. Setup asks its own consent question before it will start, product insights stay off, health never joins a coach link, and a child profile's permissions start closed. This follows NICE NG246 on age-appropriate dietary approaches for children and young people

• Goals & targets — a body goal (weight loss · weight gain · maintenance · muscle gain · body recomposition) sets the energy delta and protein priority; dietary patterns (keto · low-carb · high-protein · Mediterranean · vegan · vegetarian · pescatarian · gluten-free · dairy-free) cap or floor macros and rule ingredients in or out. Maintenance comes from Mifflin-St Jeor when you give body stats, or a figure you type. Custom macro goals hand the numbers over entirely, daily calorie targets drive the diary, and a weekly target reads the week as one budget — what you've eaten, what's left, and what that leaves per day

• Home dashboard — today's planned meals, budget and calorie rings, water, cooking streak and XP, pantry snapshot with what's about to go off, and suggestions derived from your own kitchen (never generic marketing copy). Empty states explain what each surface will do once you feed it

Run

Requires Node 22–24 (pinned in engines). Node 26 is not supported: jsdom does not expose localStorage there, so every component test fails with Cannot read properties of undefined (reading 'clear') — an environment problem that looks like a catastrophic suite failure. CI runs Node 22.

npm install
npm run dev      # local dev server
npm run build    # production build to .next/ (installable PWA with service worker)
npm test         # vitest suite

Release gates and branch protection

The quality workflow runs the same gates as npm run verify, plus Playwright E2E, accessibility, security audit and gitleaks:

1. lint
2. typecheck
3. unit and integration tests
4. production build
5. production dependency audit (npm audit --omit=dev --audit-level=high)
6. performance budgets
7. Playwright E2E and accessibility
8. gitleaks secret scan

Protect main on GitHub with:

• Require a pull request before merging
• Require approvals: 1 for a normal repository, 2 for a public production repository
• Dismiss stale pull request approvals when new commits are pushed
• Require review from Code Owners once a CODEOWNERS file is added
• Require status checks to pass: Forq / quality
• Require branches to be up to date before merging
• Require linear history
• Restrict pushes that create matching branches to maintainers only

After the first protected PR, pin the workflow to a protected Git ref (or use a pinned commit SHA) so future workflow changes cannot silently alter the release gate.

Structure

src/
  App.jsx              # shell: 5-tab bottom nav, overlays, onboarding gate
  components/AppHeader.jsx     # the one header: title, Guidance, profile avatar
  components/GuidancePanel.jsx # Next, Review, Tools and Ask in one lazy surface
  components/PrimaryAction.jsx # each screen's main action, in the thumb zone
  lib/setup.js         # what's still switched off, read from the same state
  lib/guidance.js      # ranks one next action and attaches its evidence
  index.css            # theme tokens (light/dark + 5 accents), animations
  lib/state.js         # what an install is: empty state + pure state helpers
  lib/store.jsx        # the provider: actions, the clock, persistence
  lib/derive.js        # every number the screens read, computed from state
  lib/youth.js         # under-18 mode: one rule, and everything it decides
  lib/health-actions.js # the store's body/training actions, bounded on the way in
  lib/reminder-actions.js # the store's reminder actions, validated on the way in
  lib/reminders.js     # when one is due, what came due while you were away,
                       # and the line it arrives carrying from your own data
  lib/reminder-suggest.js # reminders your records support, and the .ics export
  lib/notify.js        # the browser's notification API, and its real limits
  lib/reports.js       # day/week/month reports, trends, timing, adherence,
                       # shortfalls — each carrying its own sample size
  lib/report-export.js # quoted CSV, and the printable page the browser PDFs
  lib/preferences.js   # hard lines (allergens, observance) vs soft ones
  lib/preference-actions.js # the store's preference actions, validated in
  lib/units.js         # display-only conversions; the maths stays metric
  lib/footprint.js     # CO₂e and water from published per-kg category means
  lib/micro-optimise.js # greedy set-cover closing your nutrient gaps
  lib/fasting.js       # eating windows and overnight fasts, off the diary
  lib/receipt.js       # a real parser for pasted supermarket receipts
  lib/cgm.js           # CGM export parsing, and meals lined up with the trace
  lib/shopping.js      # aisles that learn, store routes, price comparison,
                       # offers, budget projection, expiry buckets, restock
  lib/kitchen.js       # pantry/shop/plan/achievement maths derived from your data
  lib/utils.js         # currency/date/expiry helpers
  lib/planner.js       # pure plan generation (hard constraints + soft preferences)
  lib/waste-planner.js # ingredient fragmentation, pack fit, expiry and waste scoring
  lib/mealplan.js      # calendar maths, moves/swaps, batch groups, leftovers,
                       # and the shopping list for any range
  lib/recipe-tools.js  # scaling, substitutions, full nutrition, search, sharing
  lib/recipe-ai.js     # invents a dish from your pantry, on-device
  lib/coach.js         # adherence, trends, habits, progress, the day summarised
  lib/advice.js        # meal feedback, swaps, groceries, targets, tips, eating out
  lib/label.js         # a real parser for UK/EU nutrition panels
  lib/health.js        # measurement series and trends, BMI, waist banding,
                       # vitals, sleep, stress, cycles from your own starts
  lib/exercise.js      # METs, the burn estimate, the training week, and the
                       # importer for a health app's CSV export
  lib/photos.js        # thumbnail sizing and the storage a photo set costs
  lib/progress.js      # XP, levels, streaks, goals, challenges, missions,
                       # seasonal events and achievements — all counted
  lib/goals.js         # maintenance energy, macro splits, weekly budget, diet fit
  lib/nutrition.js     # portion scaling, day/meal totals, timing & snack insights
  lib/foodlog.js       # search, barcode, voice parsing, photo demo, recipe import
  data/                # reference only: recipes (signature dishes + the parts
                       # and per-meal templates the rest are composed from), foods
                       # (catalogue + barcodes + menus), nutrients
                       # (units/targets), micronutrients (per-100 g table),
                       # goals (body goals + dietary patterns), seasons (the UK
                       # growing calendar), quests (what earns XP and what the
                       # goals are), health (published reference ranges),
                       # workouts (METs per activity and how each health app
                       # exports), reminders (the kinds one can be, and the
                       # plain truth about notifications), preferences
                       # (allergens, observance, cuisines, units, widgets),
                       # sustainability (published CO₂e/water factors),
                       # capabilities (what's built, what a browser can't do,
                       # and what's deliberately refused), and taxonomy for
                       # aisles/locations
  components/          # one file per surface + shared ui.jsx primitives
  components/icons.jsx # data-glyph → lucide icon map (data keeps emoji keys)
tests/                 # vitest suite

State notes: nothing is stored twice. The diary (log, keyed by date) is the single source of truth for nutrition; the pantry, shopping list, recorded shops, plan and cooked history are the source for everything else. Budget headroom is your weekly budget minus the shops you recorded this week; streaks count consecutive days you actually cooked; badge progress reads real counters; price trends come from prices you typed as you shopped; XP, levels and every quest bar are counted from those same records rather than stored, so nothing can be earned twice or kept after the thing that earned it is deleted. Body readings, vitals, sleep, stress, cycles and workouts are stored as dated records and every figure drawn from them — BMI, a trend, a cycle average, the training week, the day's burn — is computed on read. A new calendar day resets only water — everything else is date-keyed and carries over.

Charts use a monochrome ink ramp (every series is directly labeled, so identity never depends on colour); status colours (good/warn/danger) are muted and always paired with a label. All tokens live as CSS custom properties in index.css, with the accent defaulting to mono (ink) plus four restrained alternatives.

Cheap labels before expensive models

Labelling work — which aisle a product belongs in, which slot a dish fits, what a line of imported recipe text is — does not need a chat model. It runs through three passes in cost order: deterministic keyword rules, one batched classifier.dev request for whatever the rules could not place, and the general assistant only where a real answer needs one. Every label carries its provenance (deterministic, classifier, cache or fallback), a low-confidence answer degrades to other rather than guessing, and the running count of general LLM calls avoided is exposed at GET /api/classify.

The classifier is never the authority on allergies, medical nutrition, food safety or health interpretation: those requests are routed straight to the assistant's constraint-aware prompt and never to a classifier. Full contract, boundaries and variables: docs/CLASSIFIER.md.

Variable	Default	What it does
CLASSIFIER_API_URL	https://classifier.dev/v1/classify	Endpoint for the batched classifier. Set to an empty string to disable it — labels then come from the rules and other only.
CLASSIFIER_API_KEY	unset	Pro bearer key. The free tier needs none.
CLASSIFIER_DISABLED	unset	true turns the adapter off entirely.
CLASSIFIER_TIER	fast	fast or smart (re-asks items the fast tier was unsure about).
CLASSIFIER_CONFIDENCE_FLOOR	0.6	Below this, a label is discarded and the item falls back.
CLASSIFIER_TIMEOUT_MS	3000	Per-request deadline; a timeout costs a batch of fallbacks, never a failed request.

External product data

Forq keeps the source visible for every external result:

• Open Food Facts — barcode identity, ingredients, allergens, nutrition, labels and product imagery. It is open catalogue data, not a supermarket stock or price feed.
• Open Prices — GBP price observations contributed by shoppers. A row can be old, incomplete or from another location, so it is useful for context and history rather than checkout decisions.
• Firecrawl / Jina Reader — optional headless renderers used only when a shop's search page needs JavaScript to show its prices. They fetch the same public page the scraper would, and are never used to reach a page robots.txt declined.
• Retailer search pages — read live, on request, by the price scraper. Each row names the shop, the URL it came from, and how the number was obtained: the shop's own structured product data, its page markup, its page text, or an AI reading of that text where the shop publishes nothing machine-readable. The last of those is marked "read by AI" wherever it appears.

Forq does not query undocumented retailer website endpoints and does not work around shops that decline automated requests. The official retailer links remain the authority for the current basket, stock, offers, delivery fees and slots.

The AI extraction ladder

Where a page has no structured price data, extraction falls to a language model through the free NVIDIA NIM catalogue (NVIDIA_API_KEY), with OpenRouter as a second provider. Models are tried strongest first — Nemotron 3 Ultra 550B, DeepSeek V4 Pro, GLM-5.2, Kimi K2.6, DeepSeek V4 Flash, MiniMax M3, Nemotron 3.5 Lightning, Mistral Medium 3.5, GPT-OSS-120B, Poolside Laguna — and a rate-limited or withdrawn model costs one retry down the ladder rather than the lookup. Whatever the model returns is checked against the page text before it is shown: a price that does not appear on the page is discarded, not displayed.