FlixCooks Project Brain

This document summarizes the architectural knowledge, conventions, and learnings accumulated during our session.

1. Project Architecture & Stack

Backend: Vanilla PHP. The project intentionally avoids heavy frameworks.
Database: Flat-file JSON database (data/recipes.json). Data is loaded and saved via utility functions in helpers.php.
Admin Panel (admin.php): Acts as a lightweight CMS. It uses simple textareas where each line maps to an array element (e.g., for ingredients, steps, step_videos, step_timers). This keeps the JSON structure clean and parsing straightforward.
Frontend: Server-rendered PHP templates (index.php, recipe.php) with Vanilla JavaScript and Vanilla CSS. No Tailwind or heavy component libraries.

CSS: Highly customized CSS with modern design tokens (e.g., var(--ease-out-expo), var(--surface-1)).
Animations: Employs sophisticated micro-animations, glassmorphism (backdrop-filter: blur), and dynamic layouts (e.g., clip-path for overlays).
Smooth Scrolling: Uses Lenis (LenisSmoothScroll).
- Crucial Rule: Whenever a fullscreen overlay (like the Cooking Mode) is opened, lenis.stop() must be called to prevent background scrolling. When closed, call lenis.start().
Preloader: A custom CapitoliumPreloader runs on the homepage. It is cached in sessionStorage('flixcooks_preloader_seen') so it only fires once per browsing session.

Workspace Rules: Best placed in .agents/rules/ (e.g., AGENT.md). To ensure they are always active, the frontmatter must include:
```
always_on: true
glob: "*"
```
Custom Skills: Can be defined as JSON files in .agents/skills/. We successfully created close_feature.json to automate the Git workflow of checking out main, merging a feature branch, verifying functionality, and deleting the branch.

Gemini Code Review Automation: We integrated petarzarkov/gemini-code-review-action to automatically review PRs.
- Secrets: Must be passed using env: instead of with: (e.g., GEMINI_API_KEY, GITHUB_TOKEN), otherwise the action fails with unexpected input errors. NEVER hardcode API keys in workflow files.
- Model Naming: Google's v1beta API is very strict. gemini-1.5-flash often fails. You must use the fully-qualified name like gemini-1.5-flash-latest or gemini-2.0-flash-lite.
- Pinning Versions: Always pin GitHub Actions to a specific version tag (e.g., @v1.0.4) rather than @latest to prevent unexpected breaking changes.

Phase 3 (Nutrition): Implemented. Recipes now store calories, protein, carbs, and fat. Admin panel handles inputs, and the UI displays them beautifully.
Phase 4 (Interactive Cooking Mode): Implemented. Recipes now support step-by-step looping background videos and interactive timers (step_videos, step_timers). The UI utilizes a fullscreen overlay slider with Vanilla JS logic.

Phase 2 (commit 21833fa) and Phase 4 (commit a4a2d83) were committed directly to main, bypassing the required feature branch → PR flow. This is the correct diagnosis when someone says "Phase X wasn't saved properly" — the code exists, but the audit trail does not.
Recovery strategy (retroactive feature branch): Branch from current main, clean up / improve the work on that branch, then open a PR. This produces the audit trail without rewriting history. Do not force-push or attempt to amend merged commits in main.

Auth CSS location: All auth/profile/favorites styles live in assets/style.css under the PHASE 2 section header. login.php should have no inline <style> block.
Firebase SDK version: Using the v10 compat SDK (loaded via gstatic.com). The compat layer allows legacy v8-style API calls (window.auth.signInWithEmailAndPassword). This is intentional.
Firebase v10 error code change: auth/wrong-password and auth/user-not-found were consolidated into auth/invalid-credential in Firebase v10. All three must be handled for backwards compatibility.
Session sync flow: head.php → onAuthStateChanged fires → XHR POST to api/session.php with uid/email/token → PHP sets $_SESSION['fc_user'] → page reloads to show auth state.
Token is NOT verified server-side: api/session.php trusts the client-sent UID and email. The ID Token is stored but not validated cryptographically. Acceptable for a food blog; would need Firebase Admin SDK for sensitive apps.
Dark mode is forced: The site is dark-only by design. head.php sets data-theme="dark" unconditionally to prevent FOUC. There is no light mode toggle and this is intentional.

According to TODO.md, all 5 phases are complete. The next work will be new features or bug fixes as directed by the user.