{
  "markdown": "# Alchm.kitchen — v3.3.0\n\n[![Bun](https://img.shields.io/badge/Bun-v1.3.13-black?logo=bun&logoColor=white)](https://bun.sh)\n[![Next.js](https://img.shields.io/badge/Next.js-v15-black?logo=next.js)](https://nextjs.org)\n[![React](https://img.shields.io/badge/React-v19-blue?logo=react)](https://react.dev)\n[![TypeScript](https://img.shields.io/badge/TypeScript-v5.7-blue?logo=typescript)](https://www.typescriptlang.org)\n[![Railway](https://img.shields.io/badge/Backend-Railway-6962e0)](https://railway.app)\n[![Vercel](https://img.shields.io/badge/Frontend-Vercel-000)](https://vercel.com)\n\n**The world's first astrological meal-planning system.** Alchm.kitchen bridges ancient alchemical wisdom with modern AI to deliver personalized food recommendations based on natal charts, live planetary positions, elemental harmony, and thermodynamic resonance.\n\nProduction: **[alchm.kitchen](https://alchm.kitchen)**\n\n---\n\n## What's new in 3.3 — Data Authenticity & Live Economy\n\n- **Data-authenticity campaign**: a multi-PR push to drive the ingredient and recipe catalogs to **REAL** values — no fabricated nutrition, no placeholder/default templates, no hollow recipes. On the ingredient side: a shared free-text matching resolver now adopted by `UnifiedIngredientService` (#559), removal of the fabricated nutrition template (#560), coverage-set cleanup of non-ingredient junk (#561), placeholder coverage entries no longer leaking into recommendations (#562), missing cooking staples added — stocks, broths, fish sauce (#563), real-vs-default scoring in the ingredient audit (#565), and real nutrition for the 21 specialty oils (#566). On the recipe side: per-serving nutrition backfill (#555), an improved ESMS ingredient matcher (match rate 0.56 → 0.64, #556), description/season cleanup (#557), de-publish of 14 fully-fabricated hollow recipes (#558), and nutrition reconciliation + elemental-signature recompute after staples (#564).\n- **Dashboard honesty**: Practitioner Cohorts now read canonical sources rather than vestigial JSONB (#552), the Cost Burndown stops fabricating and shows an honest \"no billing source\" (#553), and a real Railway resource-usage panel replaces it (#554). Plus Live Network Feed poller caching + jitter to cut DB pressure (#550) and a resilient, detectable new-user signup grant (#551).\n- **Agent Daily Cosmic Yield cron** *(in flight on `feat/agent-daily-yield-cron`)*: a Vercel cron at `/api/cron/agents-daily-yield` (schedule `30 0 * * *`, `CRON_SECRET`-gated) mints each active, chart-bearing agent's personalized daily Cosmic Yield via `DailyYieldService.claimDailyYield` with `site=\"agents\"`, keeping the Live Network economy surfaces alive for visitors. It reuses the human-claim engine verbatim (same economics + per-day idempotency) and is purely additive — no formula or human-claim path changes.\n\n---\n\n## What's new in 3.2 — Planetary Agents & Live State\n\n- **Planetary Agents Integration**: End-to-end telemetry and integration with `agents.alchm.kitchen`. Unified agent profiles featuring live natal chart overlays, viewer↔agent synastry, and consciousness sigils. Agents actively publish weekly menus and share activities (chat, recipe generation) directly into the public `feed_events` via authenticated internal bridges.\n- **Cosmic Recipe Generation Offload**: Full decoupling of LLM-generated recipes to the PA Python backend via a first-class `/api/generate-recipe` endpoint, ensuring strictly structured JSON responses via the shared `CosmicRecipe` schema.\n- **SpacetimeDB v4 Live Layer**: Complete websocket-driven synchronization for meal plans, commensal lobbies, and grocery carts. Fallbacks gracefully if the connection drops.\n- **Elemental Signatures**: Introduced adaptive co-dominant framing (\"leans water & earth\" or \"balanced\") across the entire display layer, replacing the inconsistent single-dominant element reduction.\n- **Automated Image Generation**: Scripts powered by Cloudflare Workers AI SDXL pipeline to backfill and regenerate beautiful dish and ingredient images to R2 storage.\n\n---\n\n## What's new in 3.1 — MCP release\n\n- **MCP server**: a Bun-powered Model Context Protocol tool surface — connect Claude Desktop / Cursor / Cline, mint a per-user API key at `/profile/api-keys`, and buy ESMS top-ups via Stripe. Tier-aware per-key rate limiting + full telemetry.\n- **Operational admin console** at `/admin`: per-flow system status, live activity stream, onboarding funnel watch, today's highlights, and API-route health — all from existing signals, each panel degrading independently. Hourly health snapshots + Slack/email/DB alerting, plus 5 synthetic probes.\n- **Tracked, auto-applied migrations**: a `_migrations` table + `scripts/migrate.ts` run on every Railway deploy, closing the schema-drift gap that caused prior signup/dashboard outages.\n- **Production-readiness hardening**: PgBouncer transaction-mode compatibility ([ADR-007](docs/adr/007-database-connection-pooling.md)), internal-URL centralization (`src/lib/serviceUrls.ts`), and DB/calc/security guards.\n- **Calc observability**: a `degraded` flag surfaces silent astronomy fallbacks and degenerate calculations on `/quantities` instead of letting them masquerade as live data.\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full 3.1 detail.\n\n---\n\n## What's new in 3.0 — The Modern Alchemist\n\n- **New navigation IA**: 5-slot primary nav (Kitchen / Discover / Plan / Commensal / Lab) with mega-menus and ⌘K Command Palette\n- **New auth flows**: AuthHandshake 6-step checklist, WelcomeBack, two-tier UpgradeGate, device session management\n- **Dark alchm chrome**: all app-surface pages now live inside the `(alchm)` route group with the dark `#07060B` shell\n- **MenuPlannerContext split**: 2182-line monolith → 5 focused modules in `src/contexts/menu-planner/`\n- **Onboarding skip**: \"Skip for now\" CTA with `?prompt=natal` soft-prompt banner\n- **Vercel Analytics funnel events**: CommandPalette, UpgradeGate, AuthHandshake tracked\n- **Production bug fix**: `_aspects` array no longer contaminates planet positions dict (three-layer defense)\n\nSee [CHANGELOG.md](CHANGELOG.md) for the full history.\n\n---\n\n## Tech stack\n\n| Layer | Technology |\n|---|---|\n| **Frontend** | Next.js 15 (App Router), React 19, Tailwind CSS, Framer Motion |\n| **Toolchain** | **Bun 1.3.13** (package manager + runtime) |\n| **Backend** | Python FastAPI + `pyswisseph` (Swiss Ephemeris) on Railway |\n| **Database** | PostgreSQL on Railway (internal: `postgres.railway.internal`) |\n| **Auth** | NextAuth.js v5 (Auth.js) — Google OAuth, JWT, device sessions |\n| **Payments** | Stripe Checkout + Connect (card, stablecoins, ESMS reserve settlement) |\n| **Email** | Resend |\n| **Analytics** | Vercel Analytics + OpenTelemetry |\n| **Frontend hosting** | Vercel (`alchm-kitchen-pro` project) |\n| **Backend hosting** | Railway |\n\n---\n\n## Quick start\n\n> **Requirement**: [Bun 1.3.13+](https://bun.sh). Never use `npm` or `yarn` in this repo.\n\n```bash\n# 1. Clone\ngit clone https://github.com/gregcastro23/WhatToEatNext.git\ncd WhatToEatNext\n\n# 2. Install (fast — Bun lockfile committed)\nbun install\n\n# 3. Copy env template and fill in values\ncp .env.example .env.local\n\n# 4. Start dev server\nbun run dev\n# → http://localhost:3000\n\n# 5. Run tests\nbun run test\n\n# 6. Build for production (must pass before every PR)\nbun run build\n\n# 7. Lint (must be zero warnings)\nbun run lint\n```\n\n---\n\n## Project structure\n\n```\nsrc/\n├── app/                         # Next.js App Router pages\n│   ├── (alchm)/                 # Dark-shell app pages (auth-gated)\n│   │   ├── layout.tsx           # Dark #07060B chrome, hides public header\n│   │   ├── page.tsx             # Home feed (/)\n│   │   ├── lab/                 # /lab — Alchemical Laboratory\n│   │   ├── ingredients/[id]/    # /ingredients/:id — ingredient detail\n│   │   ├── profile/             # /profile/* — all profile sub-pages\n│   │   ├── commensal/           # /commensal — group recommendations\n│   │   ├── feed/                # /feed — activity feed\n│   │   ├── birth-chart/         # /birth-chart\n│   │   ├── current-chart/       # /current-chart\n│   │   ├── recipe-generator/    # /recipe-generator\n│   │   ├── planetary-chart/     # /planetary-chart\n│   │   ├── restaurant-creator/  # /restaurant-creator\n│   │   ├── cosmic-recipe/       # /cosmic-recipe\n│   │   ├── generated-recipe/    # /generated-recipe + /generated-recipe/[id]\n│   │   └── food-tracking/       # /food-tracking\n│   ├── api/                     # API route handlers\n│   ├── login/                   # /login (chromeless)\n│   ├── upgrade/                 # /upgrade (chromeless)\n│   ├── onboarding/              # /onboarding (chromeless)\n│   ├── auth/                    # /auth/* — NextAuth callbacks + establishing\n│   ├── premium/                 # /premium — marketing pricing page\n│   └── layout.tsx               # Root layout: RedesignedHeader + AppChrome\n│\n├── components/\n│   ├── nav/\n│   │   ├── AppChrome.tsx        # AppChromeFooter + AppChromeTabBar gates\n│   │   ├── CommandPalette.tsx   # ⌘K global palette\n│   │   ├── RedesignedHeader.tsx # 5-slot primary nav with mega-menus\n│   │   ├── MobileGlassTabBar.tsx\n│   │   └── RedesignedFooter.tsx\n│   └── auth/\n│       └── AuthFollowups.tsx    # AuthHandshake, WelcomeBack, UpgradeGate, AccountSessions\n│\n├── config/\n│   └── navigation.ts            # NAV_IA — single source of truth for all nav surfaces\n│\n├── contexts/\n│   ├── MenuPlannerContext.tsx   # Barrel re-export (28 lines)\n│   └── menu-planner/            # Split modules\n│       ├── types.ts             # All interfaces (244 lines)\n│       ├── useMealSlots.ts      # Slot CRUD hook (498 lines)\n│       ├── useWeekNavigation.ts # Week cursor hook (65 lines)\n│       └── MenuPlannerProvider.tsx # Composes above (1280 lines)\n│\n├── lib/\n│   ├── auth/\n│   │   ├── auth.ts              # NextAuth v5 full config (Node.js runtime)\n│   │   └── auth.config.ts       # Edge-safe auth config (middleware)\n│   ├── validation/\n│   │   └── railway.ts           # Zod schemas for Railway API responses\n│   └── rateLimit.ts             # Sliding-window rate limiter\n│\n├── services/\n│   ├── subscriptionService.ts   # Tier management, feature gates\n│   ├── TokenEconomyService.ts   # Spirit/Essence/Matter/Substance economy\n│   ├── HistoricalStatsService.ts\n│   └── ...\n│\n├── types/\n│   ├── subscription.ts          # TIER_LIMITS, SubscriptionTier\n│   └── next-auth.d.ts           # JWT augmentation (sessionId, deviceSessionId)\n│\n└── database/\n    └── init/                    # SQL migrations (01 – 54)\n        └── 33-device-sessions.sql\n```\n\n---\n\n## Environment variables\n\nCopy `.env.example` to `.env.local` and fill in values. All secrets are in Vercel (frontend) and Railway (backend).\n\n```bash\n# Database (Railway internal — used in production, not local dev)\nDATABASE_URL=postgresql://postgres:<pw>@postgres.railway.internal:5432/railway\n\n# Auth\nAUTH_SECRET=<32-char-random>\nAUTH_GOOGLE_ID=<google-oauth-client-id>\nAUTH_GOOGLE_SECRET=<google-oauth-client-secret>\nAUTH_ADMIN_EMAIL=<your-email>\nAUTH_URL=https://alchm.kitchen        # production\nAUTH_TRUST_HOST=true\n\n# APIs\nAPI_BASE_URL=https://whattoeatnext-production.up.railway.app\nNEXT_PUBLIC_BACKEND_URL=https://whattoeatnext-production.up.railway.app\nINTERNAL_API_SECRET=<shared-secret-with-fastapi>\nGALILEO_API_KEY=<galileo-key>\n\n# Payments & Email\nSTRIPE_SECRET_KEY=sk_live_...\nNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...\nRESEND_API_KEY=re_...\n```\n\n---\n\n### SpacetimeDB live layer (v4.0, optional)\n\nThe `spacetime-module/` Rust module owns the live culinary catalog plus\nper-user real-time state (meal plans, grocery carts, feed events, commensal\nsessions). The frontend connects through `SpacetimeProvider`\n(`src/contexts/SpacetimeContext.tsx`) only when `NEXT_PUBLIC_SPACETIME_URI`\nis set; five `NEXT_PUBLIC_SPACETIME_LIVE_*` flags gate each consumer surface\n(see `.env.example`). Every surface falls back silently to its legacy\nlocalStorage/REST path when the flag is off or the connection drops. Seed the\nculinary catalog with `bun scripts/spacetime/seedCulinary.ts`; regenerate TS\nbindings after module changes with\n`spacetime generate --lang typescript --module-path spacetime-module --out-dir src/lib/spacetime/generated`.\n\n## Key architecture decisions\n\nSee [docs/adr/](docs/adr/) for full Architecture Decision Records.\n\n| ADR | Decision |\n|---|---|\n| [ADR-001](docs/adr/001-five-slot-nav-ia.md) | 5-slot primary nav IA |\n| [ADR-002](docs/adr/002-two-tier-pricing.md) | Two-tier pricing (Apprentice / Alchemist) |\n| [ADR-003](docs/adr/003-token-economy-throttle.md) | Token economy as the primary AI throttle |\n| [ADR-004](docs/adr/004-device-sessions.md) | Device sessions via DB + JWT `jti` |\n| [ADR-005](docs/adr/005-denormalized-read-model.md) | Denormalized `read_model` JSONB for sub-100ms recipe loads |\n| [ADR-008](docs/adr/008-spacetimedb-live-state.md) | SpacetimeDB live-state layer (flag-gated, silent legacy fallback) |\n\n---\n\n## Deployment\n\n### Frontend (Vercel)\n\nAutomatic on merge to `master`. Project: `alchm-kitchen-pro`, team: `cookingwithcastro-llc`.\n\n```bash\n# Manual deploy (if needed)\nvercel --prod\n```\n\n### Backend (Railway)\n\nAuto-deploys from `master` if Railway is connected. Manual:\n\n```bash\ncd backend\nrailway login\nrailway up\n```\n\n### Database migrations\n\nMigrations live in `database/init/`. Apply in sequence (01 → 54). Railway runs them on first boot via the `db_init.py` script.\n\n---\n\n## Scripts\n\n```bash\nbun run dev          # Start dev server (localhost:3000)\nbun run build        # Production build (must pass before PR)\nbun run lint         # ESLint (must be zero warnings)\nbun run typecheck    # TypeScript typecheck\nbun run test         # Jest unit tests\nbun run storybook    # Component dev (dev only, excluded from prod build)\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Branch off `master`; never target `main` (stale). Always use Bun.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n**[alchm.kitchen](https://alchm.kitchen)** 🌙\n",
  "bytes": 14004,
  "sha": "f88dadf2ce519a667adde4278bca22bb8eb223762d21bb3cfc76efaf741008b5",
  "repo_slug": "gregcastro23/whattoeatnext",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_gregcastro23_alchm_kitchen_b426b63f/readme"
}