How a command becomes guidance

Request lifecycle

1. 01

   Resolve local context

   The selected environment, saved location, locally remembered selectors, conversation pointer, and requested profile scope are resolved before a service call is made.

2. 02

   Enter an authorized scope

   The client uses the selected context and an authenticated hello.food session. Refresh and retry events can be observed without exposing credentials or request content.

3. 03

   Plan the operation

   The service identifies the requested outcome and the operations required to reach it. Planning remains distinct from restaurant lookup, menu acquisition, and dietary evaluation.

4. 04

   Acquire evidence

   Restaurant identity, available menu evidence, recipe data, or prior conversation state is resolved as needed. Missing menu work is bounded and can return resumable guidance.

5. 05

   Evaluate dietary context

   The active dietary graph is applied to the requested item or menu. Household results preserve which member a concern applies to instead of flattening everyone into one answer.

6. 06

   Return a typed result

   The same service result is rendered for a human terminal or emitted as one ANSI-free JSON value for a program. Safety-bearing fields use a canonical vocabulary.

Safety has its own vocabulary

Recommendation rank and dietary safety are separate concepts. A good match is not automatically a safe choice; commands that evaluate safety use four canonical statuses.

generally_safer

A conservative relative conclusion, never a guarantee.

risky

A material concern exists or direct verification is needed.

avoid

The item conflicts with the evaluated dietary context.

unable_to_evaluate

The available evidence is insufficient for a conclusion.

Read the public schema guide

Failure is part of the interface

Invalid local input fails before a network request. Runtime failures use a machine-readable envelope. Menu acquisition that remains pending at the client ceiling returns pending state or human resume guidance instead of pretending the work completed.

{
  "ok": false,
  "error": {
    "type": "login_required",
    "message": "Run `heyfood login` first.",
    "hint": "Run `heyfood login` and retry."
  }
}