wellness-nourish 0.6.7 → 0.6.8

package/CHANGELOG.md

@@ -6,6 +6,21 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.6.8] - 2026-06-27
+
+### Changed
+
+- Rework the README as a shorter agent-first front door with quickstart,
+  copy-paste prompts, privacy boundaries, Telegram/Hermes proof path and
+  Delx Living Body demo handoff above the fold.
+- Move the full CLI reference, MCP client config examples and ChatGPT dashboard
+  notes into `docs/cli.md`.
+- Move provider attribution, Open Food Facts ODbL notes, photo-estimation
+  boundaries and local-storage privacy details into `docs/providers.md`.
+- Move the Hermes/Telegram personal setup flow into `docs/telegram.md` so
+  nutrition bot builders can follow one stable runbook without scanning the
+  whole README.
+
 ## [0.6.7] - 2026-06-27
 
 ### Security

package/README.md

@@ -12,6 +12,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/wellness-nourish"><img src="https://img.shields.io/npm/v/wellness-nourish?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white" alt="npm version" /></a>
+  <a href="https://github.com/davidmosiah/wellness-nourish/releases/latest"><img src="https://img.shields.io/github/v/release/davidmosiah/wellness-nourish?style=for-the-badge&labelColor=0F172A&color=2563EB&logo=github" alt="GitHub release" /></a>
   <a href="https://www.npmjs.com/package/wellness-nourish"><img src="https://img.shields.io/npm/dm/wellness-nourish?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white" alt="npm downloads" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A" alt="License MIT" /></a>
   <a href="https://wellness.delx.ai/nutrition"><img src="https://img.shields.io/badge/SITE-wellness.delx.ai-0EA5A3?style=for-the-badge&labelColor=0F172A" alt="Site" /></a>
@@ -20,6 +21,7 @@
 <p align="center">
   <a href="https://github.com/davidmosiah/wellness-nourish/stargazers"><img src="https://img.shields.io/github/stars/davidmosiah/wellness-nourish?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github" alt="GitHub stars" /></a>
   <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A" alt="Built for MCP" /></a>
+  <a href="https://github.com/davidmosiah/delx-wellness/blob/main/docs/release-index.md"><img src="https://img.shields.io/badge/VERIFIED-release_index-0EA5A3?style=for-the-badge&labelColor=0F172A" alt="Verified release index" /></a>
   <a href="https://github.com/davidmosiah/delx-wellness-hermes"><img src="https://img.shields.io/badge/HERMES-one--command_setup-10B981?style=for-the-badge&labelColor=0F172A" alt="Hermes one-command setup" /></a>
   <a href="https://github.com/davidmosiah/delx-wellness-openclaw"><img src="https://img.shields.io/badge/OPENCLAW-one--command_setup-FB923C?style=for-the-badge&labelColor=0F172A" alt="OpenClaw one-command setup" /></a>
   <a href="https://github.com/davidmosiah/delx-wellness"><img src="https://img.shields.io/badge/Nourish-10B981?style=for-the-badge&labelColor=0F172A&logoColor=white" alt="Nourish" /></a>
@@ -38,23 +40,22 @@
 >
 > Want runnable agent examples? Use the [Delx Agent Workbench](https://github.com/davidmosiah/delx-agent-workbench) for prompt packs, MCP client configs and local-first workflow templates.
 
+> **Public proof:** Nourish is tracked in the Delx [Open Source Growth Snapshot](https://github.com/davidmosiah/delx-wellness/blob/main/docs/open-source-growth-snapshot.md) alongside downloads, stars and next-action priorities. If this saves you setup time, star this repo so other agent builders can find the local-first nutrition path faster.
+
 ---
 
 <!-- /delx-wellness header v2 -->
 
-## Overview
-
-Wellness Nourish is a local MCP server for nutrition search, barcode lookup, barcode photo lookup, photo-assisted meal estimation, intake logging, hydration, goals, exports, daily or weekly summaries, personal meal memory, and coach-style nutrition workflows. It runs over stdio by default for MCP clients and can also run a Streamable HTTP endpoint at `POST /mcp`.
+Local-first nutrition MCP for AI agents — food search, barcode lookup, photo-assisted meal estimation, intake logging, hydration, goals and coach-style workflows. No OAuth, no hosted account.
 
-> If this nutrition layer helps your agent workflow, please star the repo. Stars make the project easier for other AI builders to discover and help Delx keep shipping local-first wellness infrastructure.
+## Front door
 
-<p align="center">
-  <img src="assets/telegram-nourish-demo.svg" alt="Wellness Nourish Telegram and Hermes nutrition workflow demo" width="92%" />
-</p>
+- **Install one connector** — `npx -y wellness-nourish setup --client claude`
+- **Run it in** Claude · Cursor · ChatGPT · Hermes · OpenClaw — see the [client examples](https://github.com/davidmosiah/delx-wellness#run-it-in-your-agent).
+- **Local-first** — your tokens and food logs never leave your machine ([privacy](#privacy--what-runs-offline)).
+- **Which connector should I use?** — see the [front-door guide](https://github.com/davidmosiah/delx-wellness#which-connector-should-i-use).
 
-Field guide: [Why local-first wellness agents need MCP](https://github.com/davidmosiah/davidmosiah/blob/main/docs/local-first-wellness-agents.md).
-
-## Try It In 60 Seconds
+## Quickstart (60 seconds)
 
 ```bash
 npx -y wellness-nourish doctor
@@ -63,12 +64,11 @@ npx -y wellness-nourish barcode 0000000000000
 npx -y wellness-nourish log --preview "2 ovos, banana e café preto"
 ```
 
-### Demo (offline, no API key)
+`doctor` checks readiness, `search`/`barcode` hit the food providers, and `log --preview` estimates a meal locally without writing anything.
+
+### Zero-secret demo (offline, no API key)
 
-`NOURISH_FIXTURE_MODE=1` serves the bundled `fixtures/` instead of calling
-USDA or Open Food Facts, so you can see the exact shape of every response with
-zero network access or keys. The outputs below are captured verbatim from this
-mode:
+`NOURISH_FIXTURE_MODE=1` serves the bundled `fixtures/` instead of calling USDA or Open Food Facts, so you can see the exact shape of every response with zero network access or keys:
 
 ```bash
 $ NOURISH_FIXTURE_MODE=1 wellness-nourish search banana
@@ -76,238 +76,43 @@ Bananas, raw	usda	89 kcal/100g
 BANANA	usda	312 kcal/100g
 ```
 
-```bash
-$ NOURISH_FIXTURE_MODE=1 NOURISH_OFF_ENABLED=1 wellness-nourish barcode 737628064502
-```
-```jsonc
-{
-  "name": "Peanut Butter",
-  "barcode": "737628064502",
-  "brand": "Fixture Foods",
-  "serving": { "quantity": 1, "unit": "serving", "grams": 32 },
-  "nutrients_per_serving": {
-    "calories_kcal": 188.16,
-    "protein_g": 8,
-    "carbohydrates_g": 6.4,
-    "fat_g": 16,
-    "fiber_g": 1.92,
-    "sugar_g": 2.88,
-    "saturated_fat_g": 3.2,
-    "sodium_mg": 128
-  },
-  "license": { "name": "Open Food Facts ODbL" },
-  "data_quality": { "completeness": "high", "confidence": 0.75, "warnings": [] }
-  // ...full record also includes nutrients_per_100g, available_portions, carbon
-}
-```
-
-`log --preview` estimates a meal locally without writing anything:
-
-```bash
-$ wellness-nourish log --preview "2 eggs and a banana"
-```
-```jsonc
-{
-  "would_write": false,
-  "total_nutrients": {
-    "calories_kcal": 248.02,
-    "protein_g": 13.89,
-    "carbohydrates_g": 27.65,
-    "fat_g": 9.89,
-    "fiber_g": 3.07,
-    "sugar_g": 14.43
-  },
-  "confidence": 0.7,
-  "warnings": ["Nutrition values are estimates from simple food defaults."]
-  // ...full record also includes per-item breakdown and entry_preview
-}
-```
-
-For the full Telegram/Hermes flow:
-
-```bash
-npx -y delx-wellness-hermes setup
-hermes -p delx-wellness
-```
-
-The connector uses USDA FoodData Central as the primary food search provider. Open Food Facts is used for packaged-food barcode lookup and product-name search when enabled. Local barcode image decoding is supported with ZXing. Meal photos are estimated only from an agent-provided visual observation and always require confirmation before logging. The local estimator includes a pt-BR/Brazilian-food catalog for common meals, kitchen units, and shortcuts such as arroz, feijão, frango, ovos, banana, tapioca, picanha, feijoada and salada. It does not provide hosted sync, autonomous photo upload, recipe generation, or medical advice.
-
-## Install
-
-```bash
-npm install
-npm run build
-```
-
-Run the MCP server over stdio:
-
-```bash
-npm start
-```
-
-Run Streamable HTTP locally:
-
-```bash
-node dist/index.js --http
-```
+## Try it with your agent
 
-### ChatGPT App / MCP Apps UI
+Three copy-paste prompts, all backed by existing tools:
 
-Nourish also exposes a compact MCP Apps-compatible dashboard for ChatGPT and other compatible hosts:
+- "Estimate the calories and protein in 2 eggs, a banana and black coffee." → `nourish_estimate_meal`
+- "Look up the barcode 737628064502 and tell me what it is." → `nourish_lookup_barcode`
+- "What should I eat next today, given my goals?" → `nourish_daily_coach` / `nourish_suggest_next_meal`
 
-- Tool: `nourish_chatgpt_dashboard`
-- UI resource: `ui://widget/nourish-dashboard-v1.html`
-- MIME type: `text/html;profile=mcp-app`
+Mutating tools (log intake, water, goals, clear-day) never run without explicit user save intent — they return `USER_ACTION_REQUIRED` until the agent passes `explicit_user_intent: true`.
 
-The dashboard shows the daily nutrition summary, hydration progress, profile gaps and next-meal coaching, and it can call `nourish_estimate_meal` from the embedded UI for preview-only estimates. It does not write intake, water or goals; mutating tools still require explicit user confirmation through the normal MCP tools.
-
-Optional environment:
-
-```bash
-FDC_API_KEY=your_usda_key
-NOURISH_OFF_ENABLED=1
-NOURISH_LOCAL_DIR=~/.wellness-nourish
-NOURISH_MCP_PORT=3000
-```
+## Tools
 
-Agents should never ask users to paste API keys, tokens, raw health exports, or private food logs into chat. Configure secrets through environment variables or local files.
+Nourish exposes food search, barcode lookup (text + image), photo-assisted meal estimation, intake logging, hydration, goals, exports, daily/weekly summaries, personal meal memory, and coach-style workflows over stdio (default) or Streamable HTTP (`POST /mcp`).
 
-## CLI Commands
+- **Full CLI (20+ commands), install, client configs & ChatGPT dashboard** → [`docs/cli.md`](docs/cli.md)
+- **Hermes / Telegram personal setup (10-step flow)** → [`docs/telegram.md`](docs/telegram.md)
+- **Data providers & attribution (USDA, Open Food Facts, ZXing)** → [`docs/providers.md`](docs/providers.md)
 
-```bash
-wellness-nourish status
-wellness-nourish doctor
-wellness-nourish setup --client claude
-wellness-nourish search banana
-wellness-nourish barcode 0000000000000
-wellness-nourish log --preview --meal breakfast "2 eggs and banana"
-wellness-nourish log "2 eggs and banana"
-wellness-nourish list 2026-05-05
-wellness-nourish edit --entry intake_id --meal snack --notes "corrected"
-wellness-nourish today --format markdown
-wellness-nourish weekly --format markdown
-wellness-nourish goals --set-calories 2200 --set-protein 120 --set-water 2500
-wellness-nourish water 500 --date 2026-05-05
-wellness-nourish water today --date 2026-05-05
-wellness-nourish export --format csv
-wellness-nourish clear-day 2026-05-05 --yes
-wellness-nourish delete --entry intake_id
-```
-
-No arguments start the stdio MCP server. `--http` starts HTTP transport, `--version` prints the package version, and `--help` prints usage.
-
-`log --preview` estimates without writing. Mutating MCP tools require explicit user intent; CLI commands are treated as explicit user actions, while destructive clear-day requires `--yes`.
-
-The local estimator understands common lightweight portions such as `g`, `oz`, `cup`, `tbsp`, `tsp`, `slice`, `piece`, and `serving`. It still reports confidence and warnings because these are conservative tracking estimates, not lab-grade nutrition facts.
-
-## MCP Client Config Examples
-
-Ready-to-use examples live in `examples/`:
-
-- `examples/claude-desktop.json`
-- `examples/codex.json`
-- `examples/cursor.json`
-- `examples/windsurf.json`
-- `examples/hermes.md`
-- `examples/hermes-skill.md`
-- `examples/openclaw.md`
-
-Claude Desktop style:
-
-```json
-{
-  "mcpServers": {
-    "nourish": {
-      "command": "npx",
-      "args": ["-y", "wellness-nourish"],
-      "env": {
-        "FDC_API_KEY": "${FDC_API_KEY}",
-        "NOURISH_OFF_ENABLED": "1"
-      }
-    }
-  }
-}
-```
-
-## Hermes / Telegram Personal Setup
-
-For a personal Hermes server connected to your Telegram bot, let the package write the Hermes config and skill:
-
-```bash
-npx -y wellness-nourish setup --client hermes --profile david --local-dir /root/.hermes/nourish/david
-npx -y wellness-nourish doctor --client hermes --json
-hermes mcp test nourish
-```
-
-This adds a `nourish` MCP server block to `~/.hermes/config.yaml`, installs `~/.hermes/skills/nourish-mcp/SKILL.md`, and pins the npm package version. After config changes, use `/reload-mcp` or `hermes mcp test nourish`.
-
-Hermes setup also writes `~/.hermes/scripts/nourish-mcp-wrapper.sh`. The wrapper sources `~/.hermes/secrets/nourish.env` when present, so `FDC_API_KEY` can be managed as a server-side secret without pasting it into chat or relying on a stale shell session.
-
-Recommended Telegram flow:
-
-1. User says what they ate.
-2. Hermes calls `nourish_estimate_meal` and replies with calories, protein, confidence and warnings.
-3. For barcode photos, Hermes calls `nourish_lookup_barcode_image` when it has an image path, base64 image, or data URI.
-4. For mixed food photos, Hermes calls `nourish_analyze_food_image` with barcode observations, label OCR, detected items, or image description.
-5. For meal photos, Hermes describes visible food and portions, calls `nourish_estimate_meal_photo`, and asks for portion confirmation.
-6. For "what should I eat now?" questions, Hermes calls `nourish_daily_coach` or `nourish_suggest_next_meal`, optionally passing wearable context from WHOOP/Garmin/Oura.
-7. For repeated meals, Hermes can call `nourish_remember_meal` after explicit user intent so future phrases like "meu café normal" expand locally.
-8. User confirms saving.
-9. Hermes calls `nourish_log_intake` with `explicit_user_intent: true`.
-10. User can ask for `today`, weekly summaries, goals, hydration, edits, deletes or exports.
-
-Local build:
-
-```json
-{
-  "mcpServers": {
-    "nourish": {
-      "command": "node",
-      "args": ["/absolute/path/to/wellness-nourish/dist/index.js"],
-      "env": {
-        "NOURISH_LOCAL_DIR": "/absolute/path/to/.wellness-nourish"
-      }
-    }
-  }
-}
-```
-
-## Provider Attribution
-
-USDA FoodData Central is the primary provider for generic food search and nutrient data. USDA data is public domain or otherwise provided by USDA FoodData Central terms; keep provider attribution with derived results.
-
-Open Food Facts barcode data is licensed under the Open Database License (ODbL). Open Food Facts metadata has share-alike obligations, so agents and downstream tools should preserve attribution and license metadata when exporting or reusing packaged-food records.
-
-## Privacy
+<p align="center">
+  <img src="assets/telegram-nourish-demo.svg" alt="Wellness Nourish Telegram and Hermes nutrition workflow demo" width="92%" />
+</p>
 
-Intake data is stored locally under `~/.wellness-nourish/intake.jsonl` unless `NOURISH_LOCAL_DIR` is set. Hydration is stored in `hydration.jsonl`, and goals are stored in `goals.json` in the same local directory. The connector does not require hosted accounts and does not send local intake logs to Delx Wellness. Provider lookups may contact USDA FoodData Central or Open Food Facts unless fixture mode is enabled.
+## Privacy & what runs offline
 
-Use `nourish-mcp export` to print the local JSONL export, `nourish-mcp export --format csv` for CSV, `nourish-mcp delete --entry <id>` to delete a specific intake entry, or `nourish-mcp clear-day <date> --yes` to delete all intake entries for a day.
+Intake, hydration and goals are stored locally under `~/.wellness-nourish/` (override with `NOURISH_LOCAL_DIR`). The connector does not require hosted accounts and does not send local intake logs to Delx Wellness. Provider lookups may contact USDA FoodData Central or Open Food Facts — unless `NOURISH_FIXTURE_MODE=1` keeps everything offline against the bundled fixtures.
 
-## Not Medical Advice
+Agents should never ask users to paste API keys, tokens, raw health exports, or private food logs into chat — configure secrets through environment variables or local files. Full detail in [`docs/providers.md`](docs/providers.md).
 
-Nutrition estimates are approximate and intended for personal tracking and agent workflow context. They are not diagnosis, treatment, or medical advice. Confirm important nutrition decisions with a qualified professional.
+## See the full agent demo →
 
-## Development And Tests
+Watch Nourish work alongside the other connectors in one reproducible run:
 
 ```bash
-npm run typecheck
-npm run build
-npm run smoke:http
-npm run test:cli-ux
-npm run test:agent-readiness
-npm test
+npx -y delx-living-body demo
 ```
 
-Fixture mode:
-
-```bash
-NOURISH_FIXTURE_MODE=1 NOURISH_FIXTURE_DIR=fixtures npm run test:cli-ux
-```
-
-## Delx Wellness
-
-Project page: <https://wellness.delx.ai/nutrition>
+Anchor question: **"Should I train hard today?"** — the demo combines wearable recovery signals with nutrition context to answer it. This is the shared, reproducible proof for the whole Delx Wellness stack.
 
 <!-- delx-wellness see-also -->
 
@@ -319,7 +124,7 @@ The full [Delx Wellness](https://wellness.delx.ai) connector library:
 |---|---|---|
 | WHOOP | [`whoop-mcp-unofficial`](https://www.npmjs.com/package/whoop-mcp-unofficial) | [whoop-mcp](https://github.com/davidmosiah/whoop-mcp) |
 | Oura | [`oura-mcp-unofficial`](https://www.npmjs.com/package/oura-mcp-unofficial) | [ouramcp](https://github.com/davidmosiah/ouramcp) |
-| Garmin | [`garmin-mcp-unofficial`](https://www.npmjs.com/package/garmin-mcp-unofficial) | [garminmcp](https://github.com/davidmosiah/garminmcp) |
+| Garmin | [`garmin-mcp-unofficial`](https://www.npmjs.com/package/garmin-mcp-unofficial) | [garmin-mcp](https://github.com/davidmosiah/garmin-mcp) |
 | Strava | [`strava-mcp-unofficial`](https://www.npmjs.com/package/strava-mcp-unofficial) | [strava-mcp](https://github.com/davidmosiah/strava-mcp) |
 | Fitbit | [`fitbit-mcp-unofficial`](https://www.npmjs.com/package/fitbit-mcp-unofficial) | [fitbitmcp](https://github.com/davidmosiah/fitbitmcp) |
 | Google Health | [`google-health-mcp-unofficial`](https://www.npmjs.com/package/google-health-mcp-unofficial) | [google-health-mcp](https://github.com/davidmosiah/google-health-mcp) |
@@ -335,6 +140,12 @@ The full [Delx Wellness](https://wellness.delx.ai) connector library:
 
 ---
 
+## Not medical advice
+
+Nutrition estimates are approximate and intended for personal tracking and agent workflow context. They are not diagnosis, treatment, or medical advice. Confirm important nutrition decisions with a qualified professional.
+
+**Unofficial.** Not affiliated with, endorsed by, or sponsored by USDA, Open Food Facts, or any third party. All trademarks belong to their respective owners.
+
 ## 📧 Contact & Support
 
 - 📨 **support@delx.ai** — general questions, integration help, partnerships

package/dist/constants.d.ts

@@ -1,10 +1,10 @@
 export declare const SERVER_NAME = "nourish-mcp";
-export declare const SERVER_VERSION = "0.6.7";
+export declare const SERVER_VERSION = "0.6.8";
 export declare const NPM_PACKAGE_NAME = "wellness-nourish";
-export declare const PINNED_NPM_PACKAGE = "wellness-nourish@0.6.7";
+export declare const PINNED_NPM_PACKAGE = "wellness-nourish@0.6.8";
 export declare const DEFAULT_HOST = "127.0.0.1";
 export declare const DEFAULT_PORT = 3000;
 export declare const LOCAL_DIR_NAME = ".wellness-nourish";
-export declare const USER_AGENT = "wellness-nourish/0.6.7 (https://wellness.delx.ai; contact: david@delx.ai)";
+export declare const USER_AGENT = "wellness-nourish/0.6.8 (https://wellness.delx.ai; contact: david@delx.ai)";
 export declare const USDA_BASE_URL = "https://api.nal.usda.gov/fdc/v1";
 export declare const OFF_BASE_URL = "https://world.openfoodfacts.org";

package/dist/constants.js

@@ -1,5 +1,5 @@
 export const SERVER_NAME = "nourish-mcp";
-export const SERVER_VERSION = "0.6.7";
+export const SERVER_VERSION = "0.6.8";
 export const NPM_PACKAGE_NAME = "wellness-nourish";
 export const PINNED_NPM_PACKAGE = `${NPM_PACKAGE_NAME}@${SERVER_VERSION}`;
 export const DEFAULT_HOST = "127.0.0.1";

package/docs/cli.md

@@ -0,0 +1,125 @@
+# Wellness Nourish — CLI reference
+
+Full command-line interface for [`wellness-nourish`](https://www.npmjs.com/package/wellness-nourish). Both `wellness-nourish` and `nourish-mcp` are valid binary names.
+
+With no arguments the binary starts the stdio MCP server. `--http` starts the Streamable HTTP transport (`POST /mcp`), `--version` prints the package version, and `--help` prints usage.
+
+## Commands
+
+```bash
+wellness-nourish status
+wellness-nourish doctor
+wellness-nourish setup --client claude
+wellness-nourish search banana
+wellness-nourish barcode 0000000000000
+wellness-nourish log --preview --meal breakfast "2 eggs and banana"
+wellness-nourish log "2 eggs and banana"
+wellness-nourish list 2026-05-05
+wellness-nourish edit --entry intake_id --meal snack --notes "corrected"
+wellness-nourish today --format markdown
+wellness-nourish weekly --format markdown
+wellness-nourish goals --set-calories 2200 --set-protein 120 --set-water 2500
+wellness-nourish water 500 --date 2026-05-05
+wellness-nourish water today --date 2026-05-05
+wellness-nourish export --format csv
+wellness-nourish clear-day 2026-05-05 --yes
+wellness-nourish delete --entry intake_id
+```
+
+## Behavior notes
+
+- `log --preview` estimates a meal locally **without writing anything**.
+- Mutating MCP tools require explicit user intent; CLI commands are treated as explicit user actions, while destructive `clear-day` requires `--yes`.
+- The local estimator understands common lightweight portions such as `g`, `oz`, `cup`, `tbsp`, `tsp`, `slice`, `piece`, and `serving`. It still reports confidence and warnings because these are conservative tracking estimates, not lab-grade nutrition facts.
+
+## Install / build / run
+
+```bash
+npm install
+npm run build
+npm start                 # stdio MCP server
+node dist/index.js --http # Streamable HTTP locally
+```
+
+## Optional environment
+
+```bash
+FDC_API_KEY=your_usda_key
+NOURISH_OFF_ENABLED=1
+NOURISH_LOCAL_DIR=~/.wellness-nourish
+NOURISH_MCP_PORT=3000
+```
+
+Agents should never ask users to paste API keys, tokens, raw health exports, or private food logs into chat. Configure secrets through environment variables or local files.
+
+## ChatGPT App / MCP Apps UI
+
+Nourish also exposes a compact MCP Apps-compatible dashboard for ChatGPT and other compatible hosts:
+
+- Tool: `nourish_chatgpt_dashboard`
+- UI resource: `ui://widget/nourish-dashboard-v1.html`
+- MIME type: `text/html;profile=mcp-app`
+
+The dashboard shows the daily nutrition summary, hydration progress, profile gaps and next-meal coaching, and it can call `nourish_estimate_meal` from the embedded UI for preview-only estimates. It does not write intake, water or goals; mutating tools still require explicit user confirmation through the normal MCP tools.
+
+## MCP client config examples
+
+Ready-to-use examples live in [`examples/`](../examples):
+
+- `examples/claude-desktop.json`
+- `examples/codex.json`
+- `examples/cursor.json`
+- `examples/windsurf.json`
+- `examples/hermes.md`
+- `examples/hermes-skill.md`
+- `examples/openclaw.md`
+
+Claude Desktop style:
+
+```json
+{
+  "mcpServers": {
+    "nourish": {
+      "command": "npx",
+      "args": ["-y", "wellness-nourish"],
+      "env": {
+        "FDC_API_KEY": "${FDC_API_KEY}",
+        "NOURISH_OFF_ENABLED": "1"
+      }
+    }
+  }
+}
+```
+
+Local build:
+
+```json
+{
+  "mcpServers": {
+    "nourish": {
+      "command": "node",
+      "args": ["/absolute/path/to/wellness-nourish/dist/index.js"],
+      "env": {
+        "NOURISH_LOCAL_DIR": "/absolute/path/to/.wellness-nourish"
+      }
+    }
+  }
+}
+```
+
+## Development and tests
+
+```bash
+npm run typecheck
+npm run build
+npm run smoke:http
+npm run test:cli-ux
+npm run test:agent-readiness
+npm test
+```
+
+Fixture mode:
+
+```bash
+NOURISH_FIXTURE_MODE=1 NOURISH_FIXTURE_DIR=fixtures npm run test:cli-ux
+```

package/docs/providers.md

@@ -0,0 +1,21 @@
+# Wellness Nourish — providers & attribution
+
+## Data providers
+
+The connector uses **USDA FoodData Central** as the primary food search provider. **Open Food Facts** is used for packaged-food barcode lookup and product-name search when enabled (`NOURISH_OFF_ENABLED=1`). Local barcode image decoding is supported with **ZXing**.
+
+Meal photos are estimated only from an agent-provided visual observation and always require confirmation before logging. The local estimator includes a pt-BR/Brazilian-food catalog for common meals, kitchen units, and shortcuts such as arroz, feijão, frango, ovos, banana, tapioca, picanha, feijoada and salada.
+
+The connector does **not** provide hosted sync, autonomous photo upload, recipe generation, or medical advice.
+
+## Attribution requirements
+
+USDA FoodData Central is the primary provider for generic food search and nutrient data. USDA data is public domain or otherwise provided by USDA FoodData Central terms; keep provider attribution with derived results.
+
+Open Food Facts barcode data is licensed under the Open Database License (ODbL). Open Food Facts metadata has share-alike obligations, so agents and downstream tools should preserve attribution and license metadata when exporting or reusing packaged-food records.
+
+## Privacy (full detail)
+
+Intake data is stored locally under `~/.wellness-nourish/intake.jsonl` unless `NOURISH_LOCAL_DIR` is set. Hydration is stored in `hydration.jsonl`, and goals are stored in `goals.json` in the same local directory. The connector does not require hosted accounts and does not send local intake logs to Delx Wellness. Provider lookups may contact USDA FoodData Central or Open Food Facts unless fixture mode is enabled.
+
+Use `nourish-mcp export` to print the local JSONL export, `nourish-mcp export --format csv` for CSV, `nourish-mcp delete --entry <id>` to delete a specific intake entry, or `nourish-mcp clear-day <date> --yes` to delete all intake entries for a day.

package/docs/telegram.md

@@ -0,0 +1,37 @@
+# Wellness Nourish — Hermes / Telegram personal setup
+
+For a personal Hermes server connected to your Telegram bot, let the package write the Hermes config and skill:
+
+```bash
+npx -y wellness-nourish setup --client hermes --profile david --local-dir /root/.hermes/nourish/david
+npx -y wellness-nourish doctor --client hermes --json
+hermes mcp test nourish
+```
+
+This adds a `nourish` MCP server block to `~/.hermes/config.yaml`, installs `~/.hermes/skills/nourish-mcp/SKILL.md`, and pins the npm package version. After config changes, use `/reload-mcp` or `hermes mcp test nourish`.
+
+Hermes setup also writes `~/.hermes/scripts/nourish-mcp-wrapper.sh`. The wrapper sources `~/.hermes/secrets/nourish.env` when present, so `FDC_API_KEY` can be managed as a server-side secret without pasting it into chat or relying on a stale shell session.
+
+## Recommended Telegram flow
+
+1. User says what they ate.
+2. Hermes calls `nourish_estimate_meal` and replies with calories, protein, confidence and warnings.
+3. For barcode photos, Hermes calls `nourish_lookup_barcode_image` when it has an image path, base64 image, or data URI.
+4. For mixed food photos, Hermes calls `nourish_analyze_food_image` with barcode observations, label OCR, detected items, or image description.
+5. For meal photos, Hermes describes visible food and portions, calls `nourish_estimate_meal_photo`, and asks for portion confirmation.
+6. For "what should I eat now?" questions, Hermes calls `nourish_daily_coach` or `nourish_suggest_next_meal`, optionally passing wearable context from WHOOP/Garmin/Oura.
+7. For repeated meals, Hermes can call `nourish_remember_meal` after explicit user intent so future phrases like "meu café normal" expand locally.
+8. User confirms saving.
+9. Hermes calls `nourish_log_intake` with `explicit_user_intent: true`.
+10. User can ask for `today`, weekly summaries, goals, hydration, edits, deletes or exports.
+
+## One-command alternative
+
+Both runtime bundles preconfigure this connector plus the full Delx Wellness stack into a dedicated profile:
+
+```bash
+npx -y delx-wellness-hermes setup
+hermes -p delx-wellness
+```
+
+See [`delx-wellness-hermes`](https://github.com/davidmosiah/delx-wellness-hermes) and [`delx-wellness-openclaw`](https://github.com/davidmosiah/delx-wellness-openclaw).

package/llms.txt

@@ -12,6 +12,7 @@ Agent surfaces:
 - For Telegram/Hermes meal logging, estimate first, show calories/protein/confidence/warnings, then call mutating tools only after explicit user confirmation.
 - Use nourish_analyze_food_image for routed image observations; use nourish_lookup_barcode_image when the image is likely a barcode.
 - Prefer JSON responses for automation and markdown responses for human summaries.
+- Detailed docs: docs/cli.md for CLI/client config, docs/providers.md for attribution/privacy, docs/telegram.md for Hermes/Telegram setup.
 - Link human users to https://github.com/davidmosiah/wellness-nourish when they want source, issues, examples, or to star the project.
 Safety:
 - Do not paste credentials, OAuth tokens, refresh tokens, API keys or raw private exports into chat.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wellness-nourish",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "Local-first nutrition MCP server for AI agents: food search, barcode lookup, meal photos, hydration, goals and safe intake logging.",
   "license": "MIT",
   "funding": {
@@ -91,7 +91,8 @@
     "qs": "6.15.2",
     "hono": "4.12.27",
     "fast-uri": "3.1.2",
-    "ip-address": "10.2.0"
+    "ip-address": "10.2.0",
+    "esbuild": "0.28.1"
   },
   "publishConfig": {
     "access": "public"

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/davidmosiah/wellness-nourish",
     "source": "github"
   },
-  "version": "0.6.7",
+  "version": "0.6.8",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "wellness-nourish",
-      "version": "0.6.7",
+      "version": "0.6.8",
       "transport": {
         "type": "stdio"
       }