# Implementation Plan

> Written 2026-06-22. Turns `requirements.md` into concrete, sequenced work.
> Reflects the current priority order: **pantry polish → auth → MCP**, with the
> MCP being the highest-value piece (Claude reads *and updates* the pantry, so
> manual upkeep mostly goes away). Builds on the completed `/simplify` pass
> (shared `kitchen/helpers.py`, dead config removed).
>
> Altitude: file/model/endpoint level. Not code — decisions and steps.

## Sequencing at a glance

| Phase | Goal | Risk | Depends on |
|------|------|------|-----------|
| 0 | ✅ Commit the simplify baseline — **done** | none | — |
| 1 | ✅ Pantry: mobile-first, In/Low/Out, fast add — **done & deployed** | medium (model + UI) | 0 |
| 2 | ✅ Auth (login-once) + prod baseline — **done & deployed** | low | — |
| 3 | MCP server — read + update pantry from claude.ai (**specced → `mcp.md`**) | medium | 1, 2 |

Deferred (not in this plan): web what-can-i-cook rework, §4.1 substitutions,
shopping flow rethink, web cook-logging. They stay roughly working but are not
invested in here.

---

## Phase 0 — Commit the baseline ✅ done

Tom has committed the simplify baseline. Starting point is clean.

---

## Phase 1 — Pantry polish (mobile-first)

The heart of the friction problem. Move from "spreadsheet of decimals" to
"glance into the fridge", and rebuild the screen phone-first.

### 1.1 Model change — add presence state

`PantryItem` today: `quantity` (required Decimal), `unit`, `location`,
`expiry_date`, `is_staple`.

- [ ] Add `state` to `PantryItem`: `CharField(choices=IN/LOW/OUT, default="in")`.
      New `TextChoices` like the existing `Location`.
- [ ] Change `quantity` from `DecimalField` to an **optional integer**
      (`PositiveIntegerField(null=True, blank=True)`) — never going to have
      1.234 pieces of toast. Keep `unit` too, but neither is required on add.
      (Migration handles the Decimal→Integer + nullable change plus the
      backfill below in one step.)
- [ ] Migration `0003_pantryitem_state_optional_quantity`. Data migration:
      backfill existing rows → `state = "out"` where `quantity == 0`, else `"in"`.
- [ ] Decide the In/Low/Out ↔ legacy `quantity==0` / `is_staple` mapping in one
      place (see 1.5 — it ripples into matcher + shopping queries).

> **Decided:** quantity becomes an optional **integer** (not a decimal, not
> free text). It's secondary metadata; In/Low/Out is the primary signal.

### 1.2 Presence filtering — stop relying on `quantity__gt=0`

Several queries use `quantity__gt=0` to mean "I have this". With optional
quantity that breaks (null ≯ 0). Replace presence checks with state.

- [ ] `_pantry_context` (`views_htmx.py`): show **all** items, don't filter out
      depleted ones — "Out" rows render greyed (requirements §2.1). Annotate
      `is_expired` / `expiring_soon` as today.
- [ ] `helpers.get_pantry_total` and the matcher's presence logic
      (`what_can_i_cook`, `recipes_page`): treat `state != "out"` as "have it";
      tolerate `quantity = None`. Minimal change only — full presence-based
      matcher rework stays **deferred**. Goal here is just "don't crash / don't
      silently show everything as missing."

### 1.3 Pantry UI — mobile-first rebuild

> **Decided:** the current design is poor — do a proper rethink of the pantry
> screen (layout, interaction, hierarchy), but **keep the palette** (Tom likes
> it). Mockup goes first (1.3.0) before touching Django templates.

**1.3.0 Design mockup first.** Produce a self-contained HTML mockup of the
redesigned pantry (phone width, real palette) as an Artifact Tom can open on
his phone and react to. Only wire it into Django templates once the look is
agreed.

Replace the table-of-tiny-links (`partials/pantry_table.html`) with a
phone-first card list.

- [ ] Per-item **card** (single column): ingredient name, location badge, and a
      **3-way In / Low / Out button group** as the primary control — proper
      buttons, ≥44px tap targets, not inline links. Expiry shown only if set, as
      a soft "use soon" pill.
- [ ] Grouping: fridge / freezer / cupboard sections, collapsible or just
      stacked. Keep it one-column; no horizontal scroll.
- [ ] State change endpoint: `POST /app/pantry/<id>/state/` (`to=in|low|out`),
      re-renders the list partial via HTMX. Replaces the quantity-edit flow as
      the main interaction.
- [ ] Keep delete and fridge↔freezer move, but as secondary (smaller, maybe
      behind a tap). Expiry edit becomes optional, de-emphasised.

### 1.4 Fast add

- [ ] **Autocomplete**: `GET /app/pantry/search/?q=` returns matching
      `Ingredient`s (name + aliases), rendered as an HTMX dropdown under the add
      box. Tap a result → adds with sensible defaults (unit/location from the
      `Ingredient`, `state="in"`, no qty required).
- [ ] **Quick-add chips**: render a row of one-tap chips from staples +
      recently-used ingredients (recent = distinct ingredients from recent
      `PantryItem`/`CookLog`). One tap adds/sets to In.
- [ ] **Add bar placement**: sticky to the **bottom** of the viewport (thumb
      reach) on mobile, with the chips just above it. This is the make-or-break
      detail per requirements.
- [ ] `pantry_add` already auto-creates unknown ingredients and merges into an
      existing same-location row — keep that, but set `state="in"` on
      add/merge, and stop requiring quantity.

### 1.5 CSS / layout (base.html)

- [ ] Shift `base.html` to mobile-first: the current `max-width: 960px` desktop
      table styling becomes the *enhancement*; default styles target a narrow
      phone screen. Bigger touch targets, larger tap-friendly buttons, bottom
      nav or bottom add bar.
- [ ] Keep the existing dark palette (it's fine) — this is layout/sizing, not a
      re-theme.
- [ ] Verify on a real phone-width viewport (e.g. 390px) — no horizontal
      scroll, controls reachable one-handed.

### 1.6 Tests

`kitchen/tests.py` is empty. Add the first real tests here:

- [ ] Model: state defaults, optional quantity, backfill migration sanity.
- [ ] Views: add via autocomplete sets `state="in"`; state toggle endpoint;
      pantry context includes "Out" rows.

---

## Phase 2 — Auth (login once) + prod baseline

Low risk, can proceed alongside Phase 1. Closes the wide-open `/app/`.

### 2.1 Session auth, long-lived

- [ ] One real user account (document the `createsuperuser` / set-password
      step; don't commit credentials).
- [ ] Settings:
      - `SESSION_COOKIE_AGE = 60*60*24*365` (~1 year)
      - `SESSION_EXPIRE_AT_BROWSER_CLOSE = False`
      - `SESSION_SAVE_EVERY_REQUEST = True` (sliding expiry — each visit renews
        the year, so an active user is effectively never logged out)
      - `LOGIN_URL` / `LOGIN_REDIRECT_URL`
- [ ] Login page: `django.contrib.auth.views.LoginView` + a minimal template in
      the existing dark style. Logout link somewhere unobtrusive.
- [ ] Protect `/app/`: simplest is Django 5.x `LoginRequiredMiddleware`, but it
      hits *every* view — so exempt `/api/` (token auth keeps its own) and the
      login view. If exemptions get fiddly, fall back to wrapping the
      `urls_htmx` includes / decorating the page views with `login_required`.
      **Pick one approach; don't mix.**

### 2.2 Drop the CSRF hacks

- [ ] With a real session + CSRF token (already wired in `base.html`), remove
      every `@csrf_exempt` from `views_htmx.py`. Verify HTMX POST/DELETE still
      work (the `htmx:configRequest` handler already sends `X-CSRFToken`).

### 2.3 Production baseline (cheap, fold in here)

- [ ] `DEBUG` from env (default False in prod).
- [ ] `SECRET_KEY` from env; drop the committed `django-insecure-…` literal.
- [ ] Keep `ALLOWED_HOSTS` as-is.

---

## Phase 3 — MCP server (the goal)

Let claude.ai "cooking mode" read the pantry and write changes back, over the
existing `/api/` (token auth, `IsAuthenticated`). This is what kills the
"recite my whole pantry every time" chore.

### 3.1 Shape

- [ ] **Separate FastMCP service** (decided). Mirrors a pattern Tom already
      runs elsewhere: a standalone "ai service" FastMCP server that talks to the
      Django API with the `caine` token. Keeps concerns decoupled; the API is
      already the right interface and the `/simplify` pass left it clean.
- [ ] Tools to expose (map to existing endpoints):
      - `get_pantry` → `GET /api/pantry/` (+ state)
      - `add_to_pantry` → `POST /api/bulk-pantry-add/`
      - `set_pantry_state` → new tiny endpoint or `PATCH /api/pantry/<id>/`
        setting `state` (in/low/out) — the conversational update path
        ("used the last of the noodles" → set Out)
      - `what_can_i_cook` → `GET /api/what-can-i-cook/`
      - `log_cook` → `POST /api/log-cook/` (and make it accept `rating`, the
        one API gap from research §5)
- [ ] Add the `state` field to the pantry serializer so MCP reads/writes it.

### 3.2 Transport, hosting, auth — **decided**

- **Transport:** remote MCP over HTTP (streamable HTTP / SSE), reachable at
  **`food.jihakuz.xyz/mcp`**. Not stdio.
- **Hosting:** same box as Django, behind nginx at `/mcp`, as its own systemd
  service alongside `food.service`.
- **Auth:** **bearer token** — single user, so one long high-entropy token
  checked by the MCP service (and/or nginx) is enough. It must be tight: this
  endpoint is internet-exposed (unlike `/api/` and `/admin/`, which nginx
  blocks externally), so the token is the only thing protecting it. Strong
  token, kept out of git (env/secret), TLS only.

### 3.3 Why the cooking blocks still work (no action, just the rationale)

MCP only feeds data/tools into the claude.ai conversation; it doesn't change
how cooking mode renders. So Claude pulls real pantry contents *and* still
produces its formatted cooking blocks — grounded instead of guessed.

---

## Decisions (locked)

1. **Quantity** → optional **integer**, secondary to In/Low/Out. ✅
2. **MCP** → FastMCP "ai service" on the same box at `food.jihakuz.xyz/mcp`,
   bearer-token auth, talks to the Django API. ✅
3. **Design** → rethink the pantry screen, keep the palette; mockup first. ✅

Still just an implementation detail (not a blocker): **auth enforcement** —
`LoginRequiredMiddleware` + exemptions vs per-view `login_required`. Plan: try
middleware, fall back if exemptions get fiddly.

## Definition of done (per phase)

- **P1:** Tom can add an item and flip In/Low/Out on his phone in a couple of
  taps, one-handed, no horizontal scroll; pantry stays glanceable.
- **P2:** Visiting `/app/` requires login; logging in once sticks for ~a year;
  no `@csrf_exempt` left; `DEBUG=False` + env `SECRET_KEY` in prod.
- **P3:** In claude.ai cooking mode, Claude can list the pantry and mark items
  In/Low/Out (and log a cook) without Tom typing the inventory.