No-key base mode: USDA is optional coverage upgrade, not setup prerequisite

[maxjustships]

Problem

USDA is currently presented too much like a prerequisite. That is bad agent-first consumer UX: a user who refuses API credentials should still have a useful, safe nutrition tool.

The product must never resolve food by taking the first search result. Existing safety incident: unrelated OFF cheese result was returned for pine nuts. No-key mode must be safe, not merely convenient.

Product decision

USDA becomes an optional coverage upgrade, not installation completion.

A fresh no-token install is installed_base_ready, not installed_needs_provider_setup, when the user-level CLI/path verification succeeds.

No-key base mode

Works without any credential:

1. Existing user cache / aliases.
2. Exact OFF barcode product lookup.
3. User-sent package photo → agent OCR → local capture label pin.
4. OFF full-text only when current endpoint is reachable and candidate passes strict matching:
   • required core nutrients;
   • token/name and food-type/category sanity;
   • confidence threshold;
   • explicit source identity/barcode;
   • output labels exact product vs source-backed generic_proxy truthfully.
5. If confidence is weak or provider unavailable: return a short actionable photo/barcode/local-cache path. No silent substitution, no generic first-result behavior.

USDA upgrade

• nomnom setup copy: "Optional: connect USDA for broader no-photo generic/raw-food coverage."
• setup --status --json reports a capability model rather than failure:
  • status: base_ready if OFF/cache/photo paths available but USDA absent;
  • generic_coverage: base|enhanced;
  • USDA next_action must be explicitly optional.
• Agent skill/install docs must say base tracking is ready without key; offer setup only when the user wants better generic/raw-food coverage or when the no-key resolver cannot safely resolve an item.

Installer statuses

• installed_base_ready — executable verified, base no-key paths available, optional USDA absent.
• installed_and_ready — executable verified, USDA configured/reachable, enhanced coverage.
• installed_path_repair_needed — executable installed but not in login PATH; still include base/enhanced capability and optional setup information.
• error — real install/verification failure only.

No provider credential may make an otherwise healthy base install appear incomplete or failed.

Tests / acceptance

• Fresh no-token install returns installed_base_ready, no error.
• setup --status --json without key says base_ready, generic_coverage=base, and optional next action.
• With configured/reachable USDA: enhanced / installed_and_ready.
• A high-confidence OFF exact/full-text candidate can resolve in no-key mode and saves provenance.
• Low-confidence OFF wrong-type candidate cannot log/cache; returned action is photo/barcode, not a key requirement.
• OFF unavailable + no USDA leads to actionable no-key alternatives, no raw usda_key_required first-screen UX.
• Agent skill gives no-token installation a successful completion message; no request for a token until coverage limits are actually hit.
• Full pytest, ruff, clean user-level installer smoke.

Constraints

• No bundled food catalogues, aliases or nutrition facts in the repo.
• No shared paid proxy, no telemetry, no secret collection in chat.
• No model-generated macros.