# 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.

## 2. Design & Aesthetics
- **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.

## 3. Antigravity Agent Configuration
- **Workspace Rules:** Best placed in `.agents/rules/` (e.g., `AGENT.md`). To ensure they are always active, the frontmatter must include:
  ```yaml
  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.

## 4. GitHub Actions & CI/CD
- **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.

## 5. Completed Milestones
- **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.

## 6. Git Workflow Violations & Recovery

- **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`.

## 7. Phase 2 Architecture Details

- **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.

## 8. Next Steps

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