# Cellar Labels -- Claude Code Context > This file is the single source of truth for this project. > Claude Code must read this file at the start of every session. > Claude Code must update the Phase Tracker and Session Log sections after completing work. --- ## Project Overview **Site:** cellarlabels.com (replacing community.cellarlabels.com) **Owner:** Brandon **What it is:** A locked community platform for pipe tobacco enthusiasts to upload, share, download, and print round jar labels. Users must register to access any labels. The site also serves as the public-facing blog for guides and printing templates. **Core value proposition:** The only place that combines a community label library with a browser-based print sheet builder designed specifically for Avery round label formats. --- ## Brand Guide | Token | Value | |---|---| | Primary | `#D03A00` Deep Terracotta | | Charcoal | `#111111` Text, outlines | | Gold | `#D8A03D` Antique Gold -- accents, Cellar Choice award, botanical elements | | Warm White | `#F8F5F0` Card surfaces | | Cream | `#F5F2EC` Page background | | Heading font | Cormorant Garamond (Google Fonts) -- everyday content headings | | Body font | Inter (Google Fonts) | | Style | Vintage print, botanical tobacco leaves, paper texture (CSS noise, no image file), serif headlines + clean sans body | **Dark mode:** Site-wide light/dark theming, default follows OS/browser `prefers-color-scheme`, user can override via a Light/Dark/System toggle in the header (persisted in `localStorage`, powered by `next-themes`, `attribute="class"` on ``). `charcoal`/`cream`/`warm-white` are semantic tokens (ink / page background / card surface), not literal colors -- each is a CSS variable (`src/styles/globals.css`, `:root` vs `.dark`) referenced via `rgb(var(--x) / )` in `tailwind.config.ts` so existing utility classes like `bg-cream` or `text-charcoal/60` automatically flip. Terracotta stays `#D03A00` in both modes (Brandon's call -- a brightened dark-mode variant tested better for small-text contrast but read as too orange/off-brand; the standard color dips under WCAG AA for small text on near-black, ~3.8:1, but is fine for the logo/heading use it's mostly used for). Gold is unchanged (reads well on both). Plain `text-white` (not a token) is used for text sitting on the always-orange terracotta button fill, and modal scrims use `bg-black/70` (not `bg-charcoal`) -- both are literal, theme-invariant colors, not part of the semantic system. **Logo:** Round, deep terracotta, serif CELLAR LABELS text, tobacco leaf botanical art in antique gold. `/public/logo.png` -- real asset in place as of Phase 2, used in the Header. **Wordmark / display lettering:** `/public/wordmark.png` -- "Cellar Labels" set in Sacred Bridge (Bombastype), a licensed font. **Not loaded as a live webfont** -- the license only covers rendered-image use, not embedding. Used for large brand-forward moments (hero H1, age gate, footer) as a pre-rendered transparent PNG via plain ``. The source font file lives at `/src/fonts/SacredBridge.ttf` for regenerating the image if the wording ever needs to change -- it must never be loaded via `next/font/local` or any `@font-face`/CSS embedding again. **Other brand images:** `/public/images/` -- jar mockups, blank label templates, misc article imagery (legacy WordPress assets, not yet wired into any page). --- ## Tech Stack | Layer | Choice | Notes | |---|---|---| | Framework | Next.js (App Router) | SSR for public pages and SEO; client components for auth app | | Database | PostgreSQL | Hosted on ShockHosting | | ORM | Prisma | Schema in `/prisma/schema.prisma` | | Auth | Auth.js v5 | Role-based sessions; no WP hash migration -- forced password reset on import | | File Storage | ShockHosting filesystem | `/storage/labels/`, `/storage/avatars/`, `/storage/sheets/` | | CDN | Cloudflare (free plan) | In front of cellarlabels.com | | CMS | Sanity | Articles, printing templates. Studio hosted standalone at Sanity's free `*.sanity.studio` domain, not part of this app (see `studio/`) | | PDF Generation | pdf-lib | Sheet Builder output -- Avery 94512 (2.75") and 94501 (2.00") | | Email | Resend | Flag alerts, rejection notices, password resets | | Hosting | ShockHosting | Node.js + PostgreSQL confirmed | | Process Manager | LiteSpeed (cPanel Node.js Selector) | Keeps Next.js running on ShockHosting -- not PM2, see Deployment section. Confirmed directly by ShockHosting support on 2026-07-21; this app's `.htaccess` uses `Passenger*`-named directives for compatibility, but the actual web server/process manager is LiteSpeed, not Phusion Passenger | | CI/CD | GitHub Actions | Push to `main` triggers deploy to ShockHosting via SSH | --- ## Roles | Role | Access | |---|---| | `admin` | Full access including admin panel and all settings | | `moderator` | Flags queue, fix queue, label approve/reject, user management (ban, not role changes) -- no dashboard, brands, blocklist, badges, Cellar Choice, moderation log, admin settings, or API keys | | `member` | Standard registered user | Contributor status is a `contributor_flag: bool` on the user record. Automatically set to `true` when `upload_count >= 10`. Not a role. --- ## Database Schema Summary Full schema is in `/prisma/schema.prisma`. Tables by domain: **Users & Auth:** `users`, `sessions` (Auth.js managed) **Content:** `brands`, `brand_aliases`, `blends`, `labels`, `label_versions` **Community:** `label_votes`, `label_flags`, `label_fix_suggestions`, `label_requests` **Social:** `follows`, `notifications`, `saved_folders`, `saved_labels` **Gamification:** `badges`, `user_badges`, `cellar_choice_awards` **Admin:** `settings`, `moderation_log` ### Key field notes - `labels.status` enum: `pending | active | rejected | unverified` - `labels.rejection_reason` enum: `black_background | non_round | min_size | duplicate | brand_blend_mismatch | custom` - `users.role` enum: `admin | moderator | member` - `follows.watch_uploads` bool: simple follow vs. watched follow (triggers notification) - `saved_labels.folder_id` is nullable -- null means general Favorites - `user_badges.label_id` is nullable -- only populated for request-fulfilled badges - `settings` is a key-value table -- all admin-configurable thresholds live here - `label_versions.is_current` -- gallery always shows current version; detail page shows all ### Admin-configurable settings keys | Key | Default | Description | |---|---|---| | `contributor_upload_threshold` | `10` | Uploads required for contributor status | | `thumbs_down_flag_threshold` | `5` | Thumbs down before auto-flag to moderation | | `label_min_dimension` | `825` | Minimum px for label upload (width and height) -- calculated for 300dpi print quality at the largest Avery label size (2.75") | | `label_max_dimension` | `2000` | Maximum px for label upload (width and height) -- anything larger has no printing benefit for this use case, kept tight given constrained storage/bandwidth on this host | | `sheet_builder_avery_wide` | `94512` | Wide mouth Avery SKU (2.75") | | `sheet_builder_avery_regular` | `94501` | Regular mouth Avery SKU (2.00") | --- ## Feature Checklist ### Label System - [ ] Brand/blend smart autocomplete (dropdown filtered by brand then blend) - [ ] Upload with circular live preview before submission - [ ] Min 825x825px enforcement + format validation (PNG/JPG only) - [ ] Label versioning (version number on detail page, view older versions) - [ ] Rejected labels hidden from gallery, visible to uploader with reason - [ ] Uploader can edit brand/blend tags on own labels - [ ] Uploader can replace/add new version of own label - [ ] Banned brand/blend blocklist enforced on upload form - [ ] Community flagging (report a label) -- triggers email to admin - [ ] Thumbs up (public count) / thumbs down (private, moderation signal only) - [ ] Moderation log for all admin/moderator actions ### Gallery - [ ] Grid gallery with circular label preview - [ ] Filter: brand, blend, uploader, badge tier - [ ] Sort: newest, most downloaded, most favorited, trending (this week) - [ ] Quick-preview on hover without leaving gallery - [ ] Following feed tab (uploads from followed/watched users) - [ ] Cellar Choice award indicator on label cards ### Label Detail Page - [ ] Full-size circular preview - [ ] Version history (side-by-side comparison) - [ ] Uploader card with badge, follow/watch buttons - [ ] Related labels (same brand, same uploader) - [ ] Download button - [ ] Add to Sheet button - [ ] Add to Folder quick action - [ ] Thumbs up button (public) / thumbs down (private to voter) - [ ] Report/flag button - [ ] "Created in response to a community request" tag where applicable ### Sheet Builder - [ ] Select jar type: Wide Mouth (Avery 94512, 2.75") or Regular Mouth (Avery 94501, 2.00") - [ ] Interactive Avery grid with label slots - [ ] Fill slots from gallery search, saved folders, brand/blend browse - [ ] Duplicate slot fill ("fill remaining with this") - [ ] Multiple sheets - [ ] Pixel-perfect PDF export via pdf-lib - [ ] Saved sheets on user profile for reprinting ### User Profiles & Social - [ ] Profile page with avatar (upload or initials fallback) - [ ] My Labels: Uploads, Favorites, Ledger Labels, Custom Folders - [ ] Private profile option (hides folders and Pipe Tool cellar, not uploaded labels) - [ ] One-way follow (Twitter model) - [ ] Watch toggle per user (separate from follow -- triggers in-app notification) - [ ] In-app notifications only (no email) - [ ] Notification settings independent of follow state - [ ] Following feed on main gallery ### Community Features - [ ] Label request system (tied to blend) - [ ] Request subscriptions for contributor-eligible users - [ ] In-app notification when subscribed request is fulfilled - [ ] Label fix suggestion system (community fixes unverified labels) - [ ] Two-confirmation auto-flag for fix suggestions - [ ] Community flagging with reason selection - [ ] Unverified labels show "Fix This Label" button - [ ] Missing blends page (Pipe Tool data -- blends with no labels) ### Brand & Blend Pages - [ ] Brand page: all labels grouped by blend, count with/without labels - [ ] Blend page: all label versions, open request status - [ ] Trending indicator (from Pipe Tool data) - [ ] SEO meta tags on brand/blend pages ### Badge System Three tracks, all independent: - [ ] Labels Uploaded track: 1, 5, 10, 25, 50, 100, 250, 500 - [ ] Requests Fulfilled track: 1, 5, 10, 25, 50 (confirmed by Brandon in Phase 9) - [ ] Badge display on label cards (highest badge, beside username) - [ ] Badge display on profile page (all earned badges) - [ ] Cellar Choice award (admin-issued, per label not per user) - [ ] Admin panel badge threshold management ### Pipe Tool Integration - [ ] Outbound API: search labels, label detail, brand labels, blend labels - [ ] API key management in admin panel - [ ] Inbound sync: user cellar blend list for profile display - [ ] Inbound push: trending/most-cellared/newly-added blends - [ ] Missing blends page fed by Pipe Tool data - [ ] "Find a Label" button flow from Pipe Tool cellar context ### Blog / CMS (Sanity) - [ ] Sanity Studio setup, standalone deploy at `*.sanity.studio` - [ ] Articles index and individual article pages (renamed from "Guides" on 2026-07-14) - [ ] Printing templates page - [ ] Homepage content block - [ ] WordPress article migration ### Admin Panel - [ ] Dashboard: recent flags, recent uploads, key stats - [ ] Label management: filter, reject, delete, Cellar Choice - [ ] Flags queue with email notification on new flag - [ ] Fix suggestion queue (brand/blend reconciliation tool) - [ ] User management: role promotion, contributor flag, bans - [ ] Brand/blend management with canonical names and aliases - [ ] Blocklist: banned brands and blends with admin notes - [ ] Settings panel: all threshold keys - [ ] Moderation log with full audit trail - [ ] API key management (Pipe Tool) ### Migration - [ ] WordPress user export and import (forced password reset flow) - [ ] Legacy label file migration to new storage structure - [ ] Legacy brand/blend data import with confidence matching - [ ] Unverified label queue for labels that could not be auto-matched - [ ] community.cellarlabels.com 301 redirect to cellarlabels.com - [ ] Age verification gate on public pages --- ## Avery Sheet Specs | Product | Diameter | Jar Type | Labels per sheet | |---|---|---|---| | Avery 94512 | 2.75 in (198px @ 72dpi / 825px @ 300dpi) | Wide mouth | 6 | | Avery 94501 | 2.00 in (144px @ 72dpi / 600px @ 300dpi) | Regular mouth | 12 | Corrected from an earlier "4 per sheet" for 94512 that was never verified against the real product (Sheet Builder wasn't built until Phase 8) -- Avery's own product pages consistently list 6, confirmed by Brandon. PDF generation must use exact Avery bleed and margin values. Reference: `/lib/avery-specs.ts` --- ## File Structure (target) ``` cellar-labels/ .github/ workflows/ deploy.yml -- GitHub Actions CI/CD studio/ -- Standalone Sanity Studio (own package.json, deployed to *.sanity.studio, not part of the Next.js app or its build) prisma/ schema.prisma -- Full database schema seed.ts -- Seed canonical brands, badges, settings public/ logo.png src/ app/ -- Next.js App Router (public)/ -- Public routes (no auth required) (auth)/ -- Authenticated routes admin/ -- Admin/moderator routes api/ -- API routes (internal + Pipe Tool) components/ ui/ -- Base UI components labels/ -- Label-specific components gallery/ -- Gallery components sheet-builder/ -- Sheet Builder components admin/ -- Admin panel components lib/ auth.ts -- Auth.js config db.ts -- Prisma client avery-specs.ts -- Avery sheet dimensions for pdf-lib upload.ts -- File upload and validation utilities badges.ts -- Badge award logic notifications.ts -- In-app notification helpers email.ts -- Resend email helpers styles/ globals.css -- Brand tokens, fonts, paper texture CLAUDE.md -- This file ROADMAP.md -- Phase breakdown .env.local -- Never committed (see .env.example) .env.example -- Committed template ``` --- ## Environment Variables See `.env.example` for full list. Key vars: ``` DATABASE_URL= NEXTAUTH_SECRET= NEXTAUTH_URL= RESEND_API_KEY= SANITY_PROJECT_ID= -- also needed in studio/.env.local for local `sanity dev` (not secret, safe to duplicate) SANITY_DATASET= -- also needed in studio/.env.local for local `sanity dev` (not secret, safe to duplicate) SANITY_API_TOKEN= -- only used by one-off migration scripts, never by the running app or Studio (Studio auths interactively via the editor's own Sanity account login) PIPE_TOOL_API_KEY= STORAGE_PATH= -- Absolute path to file storage on ShockHosting ``` > **Temporary override:** the `NEXTAUTH_URL` GitHub secret is currently set to `https://staging.cellarlabels.com`, not the production value shown above. See "Staging Environment" below -- it must be changed back to `https://cellarlabels.com` at cutover. --- ## Deployment **Trigger:** Push to `main` branch on GitHub **Process:** 1. GitHub Actions SSHes into ShockHosting 2. Pulls latest from `main` 3. Runs `npm ci` (using the Node binary from the cPanel Node.js Selector's venv) 4. Runs `npx prisma migrate deploy` 5. Runs `npm run build` 6. Restarts app by touching `tmp/restart.txt` in the app root -- LiteSpeed (cPanel's Node.js Selector process manager) detects the touched file and reloads the app on the next request. No PM2 involved. See `.github/workflows/deploy.yml` for full workflow. **Why LiteSpeed, not PM2:** ShockHosting's cPanel "Setup Node.js App" wires the app up via auto-generated `.htaccess` directives (`PassengerAppRoot`, `PassengerNodejs`, `PassengerAppType`, `PassengerStartupFile`) that this host's LiteSpeed web server reads for Phusion Passenger compatibility -- LiteSpeed itself is the actual process manager here, not genuine Passenger (confirmed directly by ShockHosting support on 2026-07-21, after support traced a process-limit outage to "multiple LiteSpeed Node.js instances"; this file previously said Passenger based only on the `.htaccess` directive names). LiteSpeed spawns and supervises the Node process itself. Running PM2 alongside it would mean two process managers competing for the same port -- not a supported pattern on this host. Discovered while setting up staging in Phase 1; see "Staging Environment" above. **ShockHosting setup required before first deploy:** - Node.js enabled on hosting account via cPanel's "Setup Node.js App" (this also wires up LiteSpeed's app process management -- no separate process manager install needed) - PostgreSQL database created and `DATABASE_URL` configured - SSH key from GitHub Actions added to ShockHosting authorized_keys - Repo cloned to hosting directory - `.env.local` created on server (never deployed via GitHub) --- ## Staging Environment (Phases 1-12) The old WordPress site is still live at `cellarlabels.com`. To avoid taking it down before the new site is ready, Phases 1-12 are built and deployed to a staging subdomain instead of the production domain. `cellarlabels.com` itself is left untouched until cutover. - **Staging URL:** `https://staging.cellarlabels.com` - **ShockHosting:** subdomain `staging.cellarlabels.com` created in cPanel Domains, with its own Node.js app (cPanel Setup Node.js App) bound to it -- not to `cellarlabels.com` - **`NEXTAUTH_URL`** GitHub secret is temporarily set to `https://staging.cellarlabels.com` ### Cutover checklist (before pointing `cellarlabels.com` at the new app) - [x] Phase 2 Sanity article migration complete - [ ] Phase 12 full WordPress migration complete (users, labels, brand/blend data) - [ ] Update `NEXTAUTH_URL` GitHub secret back to `https://cellarlabels.com` - [ ] Re-point deploy target (Node.js app / `DEPLOY_PATH`) from `staging.cellarlabels.com` to `cellarlabels.com` - [ ] Update DNS so the root domain serves the new app instead of the current live WordPress hosting - [ ] Confirm `community.cellarlabels.com` 301 redirect still works post-cutover - [ ] Take the old live WordPress site offline / archive it --- ## Important Decisions Log - No forum -- Speak Easy (speak-easy.club) already owns that community - No built-in Cellar Ledger -- Pipe Tool API integration instead - No *automated* moderation queue -- flagged labels still require a human report, no algorithmic auto-flagging beyond the existing thumbs-down email alert. Community flagging originally shipped as email-alert-only (Phase 5); Phase 10 added the actual `/admin/flags` review queue the emails point to, since "email alert is sufficient" was about not needing automation, not about not needing a queue at all. - Thumbs down count is never shown publicly -- only used for internal moderation threshold - "Claim a request" was explicitly rejected -- multiple labels per blend is the goal - Label requests never close -- new labels for a blend can always be contributed - Contributor status is activity-gated (10 uploads), not role-based - Password reset required for all migrated WordPress users -- no hash migration - Profile photos stored at max 400x400px, resized server-side on upload - Paper texture is CSS-only (no image file) - Cellar Choice is admin-issued per label, not algorithmic - Building on a `staging.cellarlabels.com` subdomain through Phase 12 instead of the production domain, since the old WordPress site is still live at `cellarlabels.com` and content migration (Phases 2 and 12) hasn't happened yet -- see "Staging Environment" above for the cutover checklist - No `--` (double hyphen) or em dash (`—`/`—`) in any text rendered on the site -- use periods, parentheses, commas, or `/` instead. Applies to all user-facing copy: headings, labels, messages, notifications. Does not apply to code comments, commit messages, or this file. - Rejection reason messages (shown to uploaders) are admin-editable at `/admin/settings`, stored in the `settings` table keyed `rejection_message_{reason}` -- not hardcoded from the `RejectionReason` enum. Editing a message applies retroactively to already-rejected labels, since the message is looked up at render time rather than snapshotted onto the `Label` row. - Brand/blend display format is `Brand - Blend` (single hyphen, spaced) everywhere on the site, not `Brand / Blend`. Applies to label cards, headings, notification text, admin queues, everywhere the pair is shown together. - Label requests are one row per (blend, requester) with no repeat-counting: re-requesting a blend you've already requested (or clicking "+1" on the Requests page) is a no-op, not an error and not an incrementing count. "Most requested" is the number of unique requesters. (A brief earlier version let re-requests increment a `count` field -- reverted after Brandon flagged it as a spam vector, since a single user could otherwise inflate a blend's ranking by repeat-clicking.) - Watch is presented to users as a bell icon, not a second button -- it's hidden until Follow is active, defaults on the moment you follow someone, and toggling it swaps between a bell and a muted/slashed bell rather than "Watch"/"Watching" text. Same underlying `Follow.watchUploads` data as before, UI-only change (Brandon's call: "Follow and Watch" as two buttons read as confusing; a notification bell is a more familiar pattern). - Contributors (`contributor_flag`, 10+ uploads) can opt in to a "notify me when a blend gets its first-ever request" alert (`User.notifyNewRequests`, toggle on `/requests`) so prolific uploaders can go fulfill fresh demand. This replaced an earlier "subscribe to be notified when a request you're watching is fulfilled" design that didn't make sense for contributors specifically (why would the person capable of filling a request want to know when someone *else* filled it?) -- fulfillment notifications now go automatically to every requester of a blend instead, no subscribe step needed, since requesting a blend already is the expression of wanting to know when it exists. - Moderators can access exactly `/admin/flags`, `/admin/labels`, `/admin/fixes`, `/admin/users` -- a literal reading of ROADMAP's Phase 10 wording ("moderators see flags, fixes, labels, users only"). Everything else in the admin panel (dashboard, brands, blocklist, badges, Cellar Choice, moderation log, settings, API keys) is admin-only. Within the shared pages, moderators can ban/unban users but not change roles or the contributor flag (privilege-escalation risk), and cannot award/revoke Cellar Choice even though that control lives inline on the Labels page they can otherwise fully use. - API keys (Pipe Tool integration, `/admin/api-keys`) are stored as a SHA-256 hash plus a short prefix for display, never the raw key -- the raw value is returned once from the generate action and shown in the UI exactly once, matching how the site already handles passwords (bcrypt, no plaintext storage) rather than treating API keys as a lesser secret. - The old WordPress "Printing Templates" page (static Word/Pages download templates for home printing) was deliberately not migrated during the Phase 2 article migration. Its 6-label content is fully superseded by Sheet Builder (Phase 8); its 4-label variant was for two-up shipping label paper specifically to avoid a label straddling the sheet's middle gap, a paper type/layout Sheet Builder doesn't support (it only knows Avery 94512/94501). Brandon's call: skip both, not worth migrating a manual workaround Sheet Builder already replaces, or building out support for a paper type the tool doesn't handle. `/templates` stays empty until there's real template content worth putting there. - Sanity Studio is not part of the deployed Next.js app -- it lives in `studio/` as its own standalone project, deployed to Sanity's free `*.sanity.studio` hosting instead of `/studio` on the production domain. Done in response to a real weekend-long ShockHosting outage (200/200 process ceiling hit with low CPU/memory, a shared-host resource pattern that had already occurred once before in Phase 1/3) -- running a full separate CMS admin app inside the same 24/7 production process for an editor who uses it occasionally was unnecessary weight on an account with no headroom to spare. The main app keeps `next-sanity`/`@sanity/image-url` for reading published content; it has zero dependency on the `sanity`/`@sanity/vision` packages that Studio itself needs. --- ## Session Log > Claude Code: append a new entry after each working session. Include date, phase worked, and what was completed or left in progress. | Date | Phase | Completed | In Progress / Blockers | |---|---|---|---| | -- | -- | Project initialized | -- | | 2026-07-12 | 1 | **Phase 1 complete.** All 9 infra setup steps (GitHub repo, secrets, ShockHosting Node.js/PostgreSQL/SSH, `.env.local`, Sanity project). Next.js app scaffolded, dependencies installed, Prisma schema + initial migration + seed script written and applied, `.github/workflows/deploy.yml` written and passing end to end. Discovered and fixed: Prisma 7's config/driver-adapter changes, npm lockfile cross-platform issues, cPanel's symlinked `node_modules` breaking Turbopack and npm postinstall scripts, this host's `npm` defaulting to `omit=dev`, Tailwind v4's native Rust engine incompatible with this host's resource limits (downgraded to v3). The `SIGABRT`/thread-limit failures that blocked the first several deploy attempts turned out to be caused by ShockHosting's IL-S1 server migration (in progress this same day) rather than a permanent account limit -- the `experimental.cpus: 1` build cap was kept anyway since it's harmless and lighter-weight. Deploy check passed: `staging.cellarlabels.com` loads the placeholder page via the automated pipeline. | -- | | 2026-07-12 | 2 | **Phase 2 complete** (except two deferred items, see below). Restructured into `src/` to match CLAUDE.md's documented layout (Phase 1 was scaffolded with `--no-src-dir`). Brand fonts/colors/paper-texture, shared Header/Footer, server-checked age gate, embedded Sanity Studio at `/studio` with an `article` schema (guide/template categories), `/guides` + `/guides/:slug` + `/templates` pages querying Sanity, homepage, and full Auth.js v5 credentials auth (login/register/forgot-password/reset-password, bcryptjs hashing, Resend for reset emails). Verified end to end against the real deployed site and database, not just locally -- registration, login, and Studio all confirmed working on `staging.cellarlabels.com`. Found and fixed a real bug this way: Auth.js needs `trustHost: true` for any non-Vercel deployment, or every login/register fails with `UntrustedHost` (local dev doesn't enforce this check, so it only surfaced against the real server). | **Deferred, need input:** WordPress article migration into Sanity needs Brandon's export/access. `community.cellarlabels.com` → `cellarlabels.com` redirect deferred to cutover -- that site is still live. `/public/logo.png` still needs the real illustrated file; header uses a text wordmark for now. | | 2026-07-12 | 3 | **Phase 3 complete, fully verified live** including the admin/blocklist paths that were initially blocked. Added `brands`/`blends`/`brand_aliases` relational tables, `BlockedEntry` model + migration, `/api/brands/search` and `/api/blends/search` endpoints (brand-scoped, blocklist-aware), reusable debounced `BrandBlendAutocomplete` component, `/brands/[slug]` and `/brands/[slug]/[blendSlug]` page shells, `requireAdmin()`-gated `/admin/brands` and `/admin/blocklist` management pages. Seeded a small **bootstrap list** of 15 real brands/blends (explicitly non-canonical test data, not scraped -- Brandon chose this over scraping third-party sources) instead of the full canonical brand/blend list, which needs Brandon's input later. Live-verified on `staging.cellarlabels.com/brand-blend-test`: brand search ("Dun" -> Dunhill), brand-scoped blend search (Dunhill -> Early Morning Pipe / Nightcap), full selection state, both brand/blend page shells, and end-to-end blocklist add/reject-message/remove via the real admin panel. **Registration simplified:** dropped the separate Display Name field (defaults to username at signup, editable later in profile settings once that exists) and added a honeypot field to `registerUser` for basic bot-signup prevention. **Admin-promotion blocker resolved:** rather than fighting infra access (phpPgAdmin is SSO-locked to the wrong DB role; the DB port isn't reachable remotely from outside the server), `prisma/seed.ts` now promotes the site owner's account (`thedeadprophet@cellarlabels.com`) to `admin` on every seed run -- no-op if that account hasn't registered yet. Runs automatically as part of the existing deploy pipeline, so it needed no new infra access. **Real bug found and fixed this way:** the Auth.js `session` callback only ever copied `role` onto `session.user`, never `id`. `requireAdmin()` requires both, so every admin-gated server action (blocklist add/remove, brand management) was throwing "Not authorized" and surfacing as an opaque 500 for actual admins too -- the page-level role gate in `admin/layout.tsx` never exercised this because it only checks `role`. Fixed by setting `session.user.id = token.sub` in `src/lib/auth.ts`. This was a latent Phase 2 bug, invisible until an admin session actually tried to run a server action. | **Deploy infra saga -- fully resolved, site confirmed live.** Three stacked issues, each masking the next, found and fixed over the course of this session by finally getting shell access via cPanel's Terminal instead of only retrying the GitHub Actions pipeline blind. (1) `P1001: Can't reach database server at localhost:5432` -- Prisma's Rust query engine resolves `localhost` differently than `psql`/the app's own `pg.Pool` do on this host (`psql "$DATABASE_URL"` connected instantly, Prisma never did). Fixed by changing `DATABASE_URL` in the server's `.env.local` to `127.0.0.1` (server-only change, not in git). (2) Once past that, `migrate deploy` hung indefinitely after "2 migrations found" -- Prisma's default telemetry ping to `checkpoint.prisma.io` hanging rather than timing out. Fixed by adding `export CHECKPOINT_DISABLE=1` to `.github/workflows/deploy.yml` (commit `0a5c71f`). (3) The account also has a 200-process (NPROC) CloudLinux LVE cap shared across **everything** on the account, not just this app -- confirmed live via cPanel's Resource Usage page. This account runs 4 WordPress sites (down from 9 -- Brandon deleted 5 unused ones during this session) plus a second Node.js app (`websale.listertools`), all sharing the same 200-process pool. Repeated deploy retries during troubleshooting (~15-20 attempts before the real fixes were found) left orphaned `npm run build` process trees running on the server each time a GitHub Actions job was cancelled (cancelling the Actions job does **not** kill the remote SSH-spawned process), which is what drove NPROC to its ceiling and caused `lve_suwrapper: Unable to fork` errors, including at one point breaking `ps` itself. After WordPress cleanup + killing the orphaned trees, NPROC settled at a healthy ~60-65/200 baseline -- ruling out "this plan's limit is too tight" as the real problem; it was leftover mess from the troubleshooting itself. **Real lesson, not just a fix:** when a deploy fails, stop after 1-2 retries and diagnose (or get shell access) rather than continuing to `gh run rerun` -- each retry is a full `npm install` + build cycle, expensive on a shared account, and repeating a failing operation can turn a config bug into a genuine resource-exhaustion problem, which is exactly what happened here. **Final recovery:** two of the killed builds left the server's `.next` directory incomplete (Next.js clears it at the start of every build), which is what was actually causing the live site's 503s at the end -- not NPROC, not Prisma. Fixed by running `npm run build` to completion once directly in the terminal (with `CHECKPOINT_DISABLE=1` and the corrected `DATABASE_URL` now permanent in `.env.local`), then `touch tmp/restart.txt`. Site confirmed back to 200 on `/`, `/brands/dunhill`, `/login`; `/upload` correctly redirects unauthenticated visitors to `/login`. `npx prisma db seed` also run manually to populate the new `rejection_message_*` settings live. Both Node apps and all remaining WordPress sites were left running normally. **For future sessions:** if a deploy ever gets stuck again, check `ps -ef` in cPanel's Terminal for orphaned `npm run`/build trees (old `STIME`, `PPID 1`) before assuming it's a new bug -- this exact scenario is likely to recur since GitHub Actions cancellation still doesn't clean up the remote process. | | 2026-07-12 | 4 | **Phase 4 complete, verified live in local dev only** -- staging deploy is still blocked on the unresolved infra issue above, so this could not be verified on `staging.cellarlabels.com` this session. Built `/upload` (brand/blend autocomplete reused from Phase 3, canvas-based circular live preview), `src/lib/upload.ts` (server-side validation: PNG/JPG only, min-dimension check read from the `label_min_dimension` setting, 15MB size cap -- uses the pure-JS `image-size` package instead of `sharp`, deliberately avoiding this host's history of native-binding pain with Tailwind v4/Turbopack), `/api/storage/[...path]` route to serve uploaded files (path-traversal guarded), `src/lib/actions/labels.ts` (`uploadLabel`, `addLabelVersion`, `updateLabelBrandBlend`, `rejectLabel`, `deleteLabel`), a minimal `/labels/[id]` detail page stub (full gallery/detail UI is Phase 5) with owner-only replace-version and edit-brand/blend controls, and `/admin/labels` (status filter, reject with reason + note, delete). **Set up local Postgres for the first time this project** (`brew install postgresql@16`) since `staging` verification wasn't available -- registered a real test account, walked the entire flow end to end: upload with a too-small image (correctly rejected, "Image must be at least 825x825px (got 400x400)"), upload with a non-image file (correctly rejected, "File is not a valid image"), successful upload (900x900, file persisted to `/storage/labels/{id}/v1/`, served correctly), replace-version (v2 added, `isCurrent` toggled correctly, both versions listed with dimensions), edit-brand/blend (title updated live), promoted the test user to admin directly in the local DB and confirmed reject-with-reason (notification record created, correct message) and delete (cascade-deleted `label_versions` too). **Incident during testing:** clicking the native "Choose File" button at one point triggered a real OS file picker rather than staying sandboxed, and a real file from the local filesystem ("McClelland - Oldchurch.png", 1.8MB) ended up selected in the input -- caught before submission via a `file.size`/`file.name` check, cleared without uploading anywhere. Worth being cautious of in future sessions when testing file inputs via the browser tool. **Known gap, not fixed (kept scope tight):** `deleteLabel` removes the DB rows but not the physical files under `/storage/labels/{id}/` -- orphaned files accumulate on delete. **Deferred to later phases:** "rejected labels hidden from gallery" (Phase 5) and "visible on uploader's profile" (Phase 6) can't be fully verified since neither page exists yet -- the underlying data (status, rejection reason/note, notification) is all correctly in place for those pages to consume once built. **Follow-up same session, Brandon-requested:** rejection messages are now admin-editable at `/admin/settings` (stored in `settings`, applies retroactively to already-rejected labels) instead of being derived from the raw enum key, and all `--`/em-dash usage in user-facing text was replaced (periods, parentheses, `/`) per a new standing rule -- **no `--` or em dashes in any text rendered on the site, going forward.** Found and fixed a real bug this way: `src/lib/rejection-reasons.ts` mixed client-safe constants with a server-only DB-backed function, so importing it into a `"use client"` form broke the build ("Module not found: Can't resolve 'dns'") by pulling Prisma's `pg` dependency into the browser bundle. Split into a client-safe module (`rejection-reasons.ts`) and a server-only one (`rejection-message.ts`), and added the `server-only` package as a guard on `db.ts`/`settings.ts`/`upload.ts` so this class of mistake fails loudly instead of cryptically if it recurs. | **Needs a successful staging deploy** to verify Phase 4 against the real production-like environment (Passenger, ShockHosting file storage path, real `STORAGE_PATH`) -- local dev only proves the application logic, not host-specific concerns like file write permissions under Passenger's process user. | | 2026-07-12 | 4 | **Dark mode added (Brandon-requested, mid-Phase 4/5 gap).** Site-wide light/dark theming via `next-themes` (`attribute="class"`, `defaultTheme="system"`), a Light/Dark/System toggle in the header (desktop nav + mobile menu), default follows OS/browser `prefers-color-scheme`, override persisted in `localStorage`. Implemented by converting the existing `charcoal`/`cream`/`warm-white` Tailwind color tokens (already used semantically as ink/page-bg/card-bg across ~40 files) into CSS-variable-backed colors (`rgb(var(--x) / )` in `tailwind.config.ts`, values flipped between `:root` and `.dark` in `src/styles/globals.css`) instead of hand-editing every component -- existing classes like `bg-cream` or `text-charcoal/60` now flip automatically. Found and fixed two places where a token was being used as a literal color rather than semantically, which would have broken under the flip: `text-warm-white` (button label text sitting on the always-orange terracotta fill, 14 files) changed to plain `text-white`; the AgeGate modal scrim (`bg-charcoal/90`) changed to `bg-black/70`, since scrims should stay dark in both themes. Terracotta is brightened for dark mode (`#F1793E` vs `#D03A00`, original fails WCAG AA as text on near-black at ~3.8:1, brightened variant holds ~6.7:1); Gold (`#D8A03D`) is unchanged, reads well on both. Verified in local dev at desktop and mobile widths: system-detected dark on load, manual Light/Dark/System toggle, persistence across navigation, no hydration-mismatch console errors (`suppressHydrationWarning` on `` per next-themes' documented pattern, since it sets the class before React hydrates). AgeGate's own dark-mode rendering wasn't re-verified live this session (its cookie is httpOnly, couldn't easily re-trigger it from the browser tool) but the fix is a static, theme-invariant color so it doesn't depend on runtime state. | -- | | 2026-07-13 | 5 | **Phase 5 complete, verified end to end in local dev.** Built the main gallery (`/labels`, brand/blend/uploader/badge-tier filters and newest/most-downloaded/trending sort via URL search params, no client JS required), a full label detail page rebuild (linked brand/blend headings, version selector via `?v=`, thumbs up/down voting, download with count increment, report/flag modal, uploader card with badge + follow/watch, disabled Add to Sheet/Folder stubs for later phases), and real `/brands/:slug` and `/brands/:slug/:blend-slug` pages (label counts, grid of active labels) replacing the Phase 3 shells. Also wired up several pieces that Phase 5's UI needed but didn't exist yet: `src/lib/badges.ts` (awards all eligible upload-count badges retroactively on each upload, both single and batch), `src/lib/actions/votes.ts` (toggle/switch/untoggle thumbs up/down, thumbs-down count staying private per CLAUDE.md's decision), `src/lib/actions/flags.ts` and `src/lib/actions/social.ts` (follow/one-way, watch-implies-follow, watchers get notified on new uploads). Reused the existing `charcoal`/`cream`/`warm-white`/`bg-black/70` dark-mode-aware tokens throughout with no new theming work needed. **Simplified two ROADMAP items during build, documented inline:** "trending this week" sorts recent (7-day) uploads by all-time download count rather than a true rolling 7-day window, since there's no per-download event log yet; the thumbs-down auto-flag threshold sends an email to all admin/moderator accounts rather than creating a formal queue entry, since there's no "system" user to attribute an automated `label_flags` row to and CLAUDE.md's Important Decisions Log already establishes "no automated moderation queue -- email alert is sufficient." **Verified live in local dev**, not staging (everything since dark mode has been local-only per Brandon's standing instruction): registered two test accounts, uploaded a label (confirmed the "1 Labels Uploaded" badge auto-awarded), full vote toggle/switch/private-downvote behavior confirmed correct in the DB from both accounts' perspectives, download count increment, flag submission both with and without an admin/moderator present (Resend's placeholder local API key returns an error object rather than throwing, so it doesn't break the flow -- consistent with the existing forgot-password email code path), follow/watch toggle (watch correctly implies follow), all gallery filters and sorts, the quick-preview modal, and both brand/blend pages against real uploaded data. **Real bug found and fixed this way:** the flag report modal's `useActionState` lived on the outer `FlagButton` component, which never unmounts, so reopening the modal after a successful report (or to report a second time) showed the stale "Thanks for the report" screen instead of a fresh form -- fixed by extracting the modal body into its own component keyed on an incrementing counter that increments on every open, forcing a remount. **Known gap, not fixed (out of Phase 5 scope):** the Header still hardcodes "Log In"/"Register" regardless of session state -- it was never made session-aware in Phase 2 and doing so belongs with Phase 6's profile work (avatar, user menu). | Staging deploy still pending per the standing "keep working locally for now" instruction. | | 2026-07-13 | 6 | **Phase 6 complete, verified end to end in local dev.** Built the user profile page (`/profile/:username` -- avatar, all earned badges, upload/thumbs-up/follower/following stats, Uploads/Favorites/Folders tabs via URL search params, private-profile flag hiding Favorites+Folders from non-owners since Favorites is just the default folder in the same saved-labels system), avatar upload (`src/lib/avatar.ts`, new `jimp` dependency -- pure JS, no native bindings, consistent with this host's constraints -- `.cover()` crops-and-fills to 400x400px rather than distorting non-square sources), the saved folders system (create/rename/delete, a reusable `AddToFolderButton` modal wired into the label detail page's previously-stubbed button), the full follow/watch UI on profiles (reusing Phase 5's `FollowWatchButtons`), the in-app notification center and per-type settings page, and the following feed (`/feed`). Finally made the **Header session-aware** (Phase 5's known gap): it now receives session/unread-count data from `RootLayout` and shows an avatar+username+notification-bell menu instead of hardcoded Log In/Register when logged in. Also built `src/lib/notifications.ts` (a `createNotification`/`createNotifications` wrapper that checks the new `NotificationSetting` table before writing, defaulting to enabled with no row) and retrofitted the three existing Phase 5 notification call sites (badge-earned, label-rejected, watched-upload) to go through it instead of writing `db.notification.create` directly, so the new settings page actually has teeth. **Real gap found and fixed along the way:** `users.thumbs_up_received` (needed for the profile stats row) was declared in the Phase 1 schema but never incremented anywhere -- Phase 5's `voteLabel` action only updated the label's own `thumbsUpCount`. Fixed by extending `src/lib/actions/votes.ts`'s existing transaction to also adjust the uploader's `thumbsUpReceived` by the same delta on create/switch/untoggle. **Verified in local dev** with two test accounts end to end: avatar upload confirmed 400x400px on disk and in the DB from a non-square source, folder create/save-to-Favorites/save-to-custom-folder from the label detail modal, private-profile flag confirmed to hide Favorites+Folders for a logged-out viewer while staying visible to the owner, follow/watch and its counts, the following feed, and the complete notification lifecycle (watched-upload notification fires with unread dot + header badge count, mark-all-as-read clears both, and disabling "new label from watched user" in settings correctly suppressed that notification on a subsequent upload while the badge-earned notification from the same session still fired normally). | Staging deploy still pending per the standing "keep working locally for now" instruction. | | 2026-07-13 | 7 | **Phase 7 complete, verified end to end in local dev.** Built the label request system (`/requests`, "Request a label" on zero-label blend pages, contributor-gated subscriptions, `fulfilledRequestId` linking + subscriber notifications on upload, "Made by request" tag on cards/detail), the label fix suggestion system ("suggest a fix" wired into Phase 5's unverified-label banner stub, auto-confirm when two different members suggest the same brand/blend, admin fix queue at `/admin/fixes` with apply/reject), and the Missing Blends page (`/missing`, zero-label blends ordered by `pipeToolCellarRank` with an honest "not connected yet, alphabetical for now" note since Phase 11 hasn't happened). Added `initialBrand`/`initialBlend` pre-fill props to `BrandBlendAutocomplete` so Missing Blends' "Create a Label" link and the upload page's `?blend=` param actually skip retyping. **One real schema gap found and fixed:** `LabelRequest` had no unique constraint on `(blendId, requesterId)`, so a user could spam duplicate requests for the same blend and inflate its "most requested" count -- added one via a hand-written migration (`prisma migrate dev` refused to run in this non-interactive environment even via `--create-only`; worked around it by writing the migration SQL directly, matching Prisma's own naming convention, and applying with `prisma migrate deploy`, which is designed for non-interactive CI and is what this project's actual deploy pipeline already uses). **Scope call:** the admin fix queue is admin-only for now, not moderator-accessible, even though CLAUDE.md's Roles table lists "fix queue" under moderator access -- ROADMAP's own Phase 10 has an explicit "Moderator role gate" task covering exactly this distinction across all admin pages at once, so gating it piecemeal now would just get redone there. **Verified in local dev** with four test accounts end to end: request -> subscribe -> upload -> fulfillment notification and tag, two independent matching fix suggestions auto-confirming, admin applying one (confirmed the label's blend/status updated, the applied suggestion marked `applied`, the other account's matching suggestion auto-rejected, and a `ModerationLog` row written), and the Missing Blends page's pre-fill flowing correctly into the upload form. | Staging deploy still pending per the standing "keep working locally for now" instruction. | | 2026-07-14 | 7 | **Brandon-requested polish, mid-Phase 7/8 gap.** Changed the "Brand / Blend" display format to "Brand - Blend" across all 10 places it appeared (label cards, both label detail headings, admin labels/fixes queues, the requests/missing pages, notification message text, and the brand/blend autocomplete's "Selected:" line). Fixed 4 live violations of the standing no-`--`/em-dash rule found during this same sweep (the admin fix queue's intro copy and note interpolation, the Missing Blends page's Pipe Tool disclaimer, and a vote button tooltip) -- these had slipped through Phase 7 despite the rule being in place since Phase 4, so this doubled as an audit rather than just fixing the one instance Brandon spotted. **Bigger change:** redesigned how label request counts work. Previously a second request from the same user for the same blend was blocked outright (`"You already requested this blend."`, added in Phase 7 specifically to stop the count from being inflated by duplicates). Brandon wants the opposite: submitting a request that already exists, or clicking a new "+1" button while browsing, should always succeed and bump the count. Added a `count` field to `LabelRequest` (still one row per requester, but now incrementable) via a hand-written migration (same non-interactive `migrate deploy` workaround as Phase 7's first migration), replaced the single `createLabelRequest` form action with a simpler `requestLabel(blendId)` that upserts-and-increments, and changed the Requests page's "most requested" sort from counting rows to summing `count`. The blend page's request button no longer locks into a static "already requested" message -- it stays clickable as "+1 request" and shows a running "You've requested this N times" count. Also added a clickable A-Z alphabet filter (by brand's first letter, greyed out for letters with no requested blends) and a Most Requested / Brand A-Z sort toggle to the Requests page, both via URL search params. **Verified in local dev:** clicking +1 on both the Requests page and a blend page repeatedly, confirmed via direct DB query that the same user's row increments rather than erroring or duplicating, confirmed the displayed sum updates correctly across repeat clicks, and confirmed the alphabet filter correctly disables letters with zero matches while keeping others clickable. | -- | | 2026-07-14 | 7 | **Second round of Brandon-requested polish, same session.** Redesigned Follow/Watch on the label detail page: Watch is now a bell icon (not a second text button), hidden until Follow is active, auto-enabled the moment you follow someone, and click-to-mute shows a slashed bell instead of unfollowing anything -- same `Follow.watchUploads` data underneath, just a more familiar notification-bell pattern per Brandon's read that "Follow and Watch" as two buttons was confusing. Extracted the icon into a reusable `src/components/ui/BellIcon.tsx` (muted variant included) rather than inlining it, since the header's notification bell could reasonably switch to it too later. **Reworked contributor request notifications** after Brandon pointed out the Phase 7 design didn't make sense: contributors were only able to subscribe to "this specific request was fulfilled," which is backwards for the people actually capable of fulfilling requests -- they'd want to know about fresh demand, not their own follow-through. Replaced it with a global, contributor-gated opt-in (`User.notifyNewRequests`, toggle on `/requests`) that fires once when a blend gets its first-ever request across the whole catalog, and made fulfillment notifications automatic for every requester of a blend (no subscribe step -- requesting a blend already expresses wanting to know when it's fulfilled). This let the entire `LabelRequestSub` model and its subscribe UI be deleted rather than just rewired. **Also reverted the `count`-based request system from earlier this same session** after Brandon flagged it as a spam vector on sight ("This implies a single user can request a label multiple times... opens some spam where a user can manipulate the system to get their request to the top of the queue") -- re-requesting a blend is a no-op again, not an incrementing count; "most requested" is back to counting unique requesters. Two migrations this session: one adding `count` (now itself reverted by the second), and one removing it again alongside dropping `LabelRequestSub` and adding `notify_new_requests` + the `new_label_request` notification type -- both hand-written and applied via `migrate deploy` for the same non-interactive-environment reason as Phase 7's migrations. **Verified in local dev** with four accounts: follow auto-enables the bell, click-to-mute shows the slashed icon and persists, unfollow clears both; repeat-clicking a request (both the blend page button and the Requests page's +1) confirmed idempotent via direct DB query (no count inflation); a contributor who opted in received the new-request notification when a different user requested a never-before-requested blend, while non-opted-in users did not; and an older fulfillment notification from earlier in the session confirmed the automatic-for-all-requesters path still works. | -- | | 2026-07-14 | 8 | **Phase 8 complete, verified end to end in local dev.** Built the Sheet Builder: jar type toggle (Wide Mouth Avery 94512 / Regular Mouth Avery 94501) with a data-loss confirm when switching away from a filled sheet, a slot grid driven entirely by `src/lib/avery-specs.ts` (column count per jar type, so the wide layout renders 2 columns and the regular layout renders 3), per-slot fill/clear/"fill remaining", multi-page add/remove, a 3-tab label picker (search, brand-then-blend cascading browse, folder browse), PDF export via `pdf-lib`, and save/reprint/delete of named sheets on the profile's new Sheets tab. Also wired two folder-driven entry points from the profile's Folders tab: "Print this folder" (seeds the builder with every label in a folder, auto-spilling across multiple sheets via a `chunkIntoPages` helper if the folder holds more than one sheet's worth) and "Select labels to print" (a checkbox-select mode on the folder grid for a specific subset), plus a real "Add to Sheet" link from the label detail page replacing Phase 5's disabled stub. **Avery spec correction, caught before it shipped:** CLAUDE.md had documented 94512 as 4 labels per sheet, never verified since Sheet Builder didn't exist until now -- Avery's own product pages consistently say 6, which Brandon confirmed directly ("You are correct, it's 6. And 94501 is 12"). CLAUDE.md's Avery Sheet Specs table was corrected before building against it. **Exact print-alignment coordinates came from real proof PDFs, not estimation:** since Avery's public pages don't publish precise slot/margin coordinates and getting physical die-cut label placement wrong wastes real money, Brandon provided actual Avery WePrint proof PDFs for both 94512 and 94501 (blank sheets with trim/safe/bleed guide lines). Extracted exact vector coordinates from both using Python's `pdfplumber` (reading bezier-curve bounding boxes, cross-referenced against known label diameters to tell trim/safe/bleed circles apart from near-duplicate curve artifacts), converted from pdfplumber's top-down coordinate system to pdf-lib's bottom-left-origin system, and hand-verified the resulting `avery-specs.ts` constants by generating test PDFs and re-parsing them with `pdfplumber` to confirm pixel-exact slot centers and sizes for both jar types before wiring it into the real UI. **Design choices, not scope creep:** label images use CSS-`cover`-style scaling to fully cover each slot's bleed circle with no PDF-side circular clipping, since physical die-cutting handles the actual round cut at the trim line; `SavedSheet.pages` is a single `Json` column rather than relational slot tables, since sheets are always read/written as one unit and a relational model would add joins for no benefit; folder/multi-select seeding always chunks against the wide-mouth (94512) capacity regardless of what jar type the builder ends up using, since the seed happens before the user has necessarily picked a jar type. **Verified end to end in the browser**, not just via `tsc`/`eslint`: filled and cleared slots across both jar types, exercised all three label-picker tabs including a blend with zero labels correctly showing "No labels found", jar-type-switch data-loss confirm, multi-page add/remove, downloaded a PDF and independently confirmed via `pdfplumber`-style header/byte inspection that it's a genuine `%PDF-1.7` file (not an error page), created a folder with two labels and confirmed both "Print this folder" (correct auto-seed + message) and "Select labels to print" (correct single-label seed) route into the builder correctly, and confirmed the "Add to Sheet" link from a label detail page seeds a fresh sheet. **Real bug found and fixed during this verification pass:** "Save Sheet" used the browser's native `prompt()` to ask for a sheet name, which threw outright in the automated browser-verification tool ("prompt() is not supported") and is fragile in general (blocked by many real browsers' popup/extension settings, and inconsistent with the rest of the app, which already uses inline text inputs for this exact pattern, e.g. folder creation). Replaced with an inline name input + Save/Cancel that appears in place of the "Save Sheet" button, matching the folder-creation UI pattern already established in Phase 6. Re-verified save -> appears correctly on the profile's Sheets tab -> reprint produces a valid PDF via the `sheetId` lookup path -> delete removes it, all working after the fix. | -- | | 2026-07-14 | 8 | **Brandon-requested profile page cleanup, mid-Phase 8/9 gap.** The profile header was cluttered: a large "Choose File" input and "Update avatar" button sat directly under the avatar circle, crowding the username and stats. Replaced with a hover-to-edit pattern: the avatar (now a larger `xl` size added to `Avatar.tsx`) is a button that shows a camera icon overlay on hover (new `CameraIcon.tsx`), opening a modal (`AvatarEditModal.tsx`) with the upload-and-save flow that used to live inline; the username now sits directly to the right of the avatar instead of below the old upload form. Extracted this into a client component (`AvatarWithEdit.tsx`, owner-only, falls back to a plain `Avatar` for visitors) and deleted the old inline `AvatarUploadForm.tsx` it replaced. Also removed the redundant "1 Labels Uploaded" badge pill from the profile header, since the numeric "uploads" stat directly below it already conveys the same milestone (uploads-track badges specifically, not badges generally, are excluded from the profile's earned-badges pill row via a `badge: { track: { not: "uploads" } }` filter, so a future Requests Fulfilled or other track badge still shows there), and renamed the "thumbs up received" stat to "upvotes" per Brandon's read that the up-arrow icon used throughout the site is a voting mechanism, not a thumbs gesture. **Verified in local dev:** profile header renders with username beside the avatar, hovering the avatar shows the camera overlay, the modal opens/uploads/saves correctly, the badge pill is gone, and the stat reads "N upvotes". | -- | | 2026-07-14 | 9 | **Phase 9 complete, verified end to end in local dev.** Built the badge system's second track and its remaining UI: a `requests_fulfilled` badge track (thresholds 1, 5, 10, 25, 50, confirmed by Brandon after CLAUDE.md flagged them as still TBD) seeded alongside the existing `uploads` track, refactored `src/lib/badges.ts` to share one `awardEligibleBadges` helper between both tracks' award functions instead of duplicating the loop, and wired `maybeAwardRequestFulfilledBadges` into both the single-upload (`labels.ts`) and batch-upload (`batch-upload.ts`) actions right after `fulfillBlendRequests` runs, since a request is only fulfilled (and thus countable) at that point. Added `getHighestBadgesForUsers(userIds)` (a batch version of the existing single-user `getHighestBadge`) and used it to add the previously-missing "highest badge beside uploader name" display on label cards across all five places labels render (gallery, brand/blend pages, feed, homepage, profile) -- a small gold medal icon with the badge name as its tooltip, added to `LabelCard.tsx`. Built the Cellar Choice admin flow that was previously just a data model with no UI: `awardCellarChoice`/`revokeCellarChoice` server actions in `admin.ts`, and a `CellarChoiceControl.tsx` toggle on `/admin/labels` (inline note field on award, confirm-gated revoke). Replaced `CellarChoiceBadge.tsx`'s placeholder star icon with a hand-drawn gold leaf/botanical mark (a vesica shape with a center vein) to match the brand's botanical motif instead of a generic achievement star. Built `/admin/badges` (new page, plus `BadgeRow.tsx`/`NewBadgeForm.tsx`), letting admins view both tracks, edit a badge's threshold/name inline, and add new tiers, backed by new `createBadgeThreshold`/`updateBadge` actions in `admin.ts` -- both guard against creating or moving a badge onto a threshold that's already taken within its track (Badge has a `@@unique([track, threshold])` constraint), and deletion was deliberately left out of scope since `UserBadge.badge` cascades on delete and would silently strip already-earned badges from users. **Verified end to end in local dev:** confirmed the badge icon and its tooltip render on gallery cards; awarded Cellar Choice to a label as admin and confirmed the pill (with the new leaf icon) appears on both the gallery card and detail page, then confirmed the button flips to "Revoke Cellar Choice" and works; edited a badge's name inline and added then removed a test threshold on `/admin/badges`, confirming the duplicate-threshold guard rejects a clashing add; and directly exercised the new `requests_fulfilled` award path end to end via a temporary local-only test route (deleted after use) that created a label against a real open request, called the real `fulfillBlendRequests`/`maybeAwardRequestFulfilledBadges` functions, and confirmed via the DB that `fulfilled_request_id` linked correctly, the "1 Requests Fulfilled" badge was awarded, and both the `badge_earned` and `request_fulfilled` notifications fired -- then cleaned up the synthetic label/badge/notifications afterward so the dev DB stays representative for future sessions. | -- | | 2026-07-14 | 10 | **Phase 10 complete, verified end to end in local dev, as both admin and moderator.** Built the full admin panel: dashboard (`/admin`, key stats and recent flags/uploads), a real flags queue (`/admin/flags`, dismiss/reject/ban actions, replacing the "email alert only" design from earlier phases with an actual working queue now that this phase calls for one), user management (`/admin/users`, search, role promote/demote, contributor flag, ban/unban), a full site-thresholds section on Settings (`/admin/settings`, the 6 `settings` table keys from CLAUDE.md's config table, previously only rejection messages were editable there), a Cellar Choice history page (`/admin/cellar-choice`, revoke plus the award history Phase 9's inline `/admin/labels` control didn't surface anywhere), a moderation log viewer (`/admin/log`), API key management (`/admin/api-keys`, SHA-256-hashed storage with the raw key shown exactly once at creation, ahead of Phase 11's actual Pipe Tool usage of these keys), and search plus multi-select bulk reject/delete on the existing `/admin/labels` queue. **Real, previously-invisible bug found and fixed:** `users.banned`/`banned_at` have existed in the schema since Phase 1 but were never checked anywhere -- banning a user had zero actual effect, they could still log in freely. Fixed with a one-line check in `src/lib/auth.ts`'s `authorize()`, verified live (banned test account correctly got "Invalid email or password" on login attempt). **Moderator role gate implemented as the literal reading of ROADMAP's own wording** ("moderators see flags, fixes, labels, users only") -- moderators get exactly those four pages; everything else (dashboard, brands, blocklist, badges, cellar choice, log, API keys, settings) is admin-only via a new shared `AdminOnlyGate` server component wrapping each restricted page, plus `requireStaff()` (admin-or-moderator) helpers added alongside the existing `requireAdmin()` ones in `labels.ts`, `admin.ts`, and `fix-queue.ts` for the underlying server actions. This closes a scope note from Phase 7 that deliberately left the fix queue admin-only "since gating it piecemeal now would just get redone" once this phase's gate landed. Cellar Choice's award/revoke controls stay admin-only even though they live inline on the (moderator-visible) Labels page -- `LabelsBulkList.tsx` only renders `CellarChoiceControl` when `viewerRole === "admin"`. Retrofitted `moderationLog` entries onto `rejectLabel`/`deleteLabel` (previously silent) and the Phase 9 Cellar Choice actions, so the new Log page actually has content across every phase's moderation actions, not just fix suggestions. Added a `ModerationLog` entry from `rejectLabel` that also auto-resolves any open flags on that label, since there's nothing left for a flag to be "open" about once the label is rejected out of the gallery. **New schema:** `ApiKey` model (hand-written migration, same non-interactive `migrate deploy` workaround as every prior phase's schema change). **Verified end to end in local dev with two real accounts** (`testuploader` as admin, promoted `collector2` to moderator for this session): dashboard stats and recent-activity lists render correctly; dismissed a real community flag and confirmed it left the queue and appeared in the log; banned then unbanned a test account and confirmed the login block actually takes effect and clears; promoted a member to moderator via the Users page and confirmed, logged in as that account, that the nav correctly narrows to Flags/Labels/Fixes/Users, `/admin` (dashboard) correctly renders "Not authorized. This page is admin-only," and the Labels page correctly hides the Award Cellar Choice button while still showing Reject/Delete; saved real values through the new Settings thresholds form; generated and revoked a real API key end to end; searched the Labels page by brand name and confirmed it filtered correctly; multi-selected two labels and bulk-rejected them, confirming both actually changed status and both appeared as separate entries in the moderation log, then restored them to active afterward since the bulk-reject was purely a verification exercise, not a real moderation decision. **One real bug found and fixed during this verification pass, not before:** after adding the `ApiKey` model and running `prisma generate`, the *already-running* dev server kept using its in-memory copy of the old Prisma Client (missing the new model) since Next.js dev doesn't reload node_modules on schema regeneration -- surfaced as `Cannot read properties of undefined (reading 'findMany')` on the API Keys page specifically (the one new page touching the new model). Fixed by restarting the dev server; worth remembering for future schema-adding phases, since `prisma generate` alone isn't sufficient once a dev server is already up. | -- | | 2026-07-14 | 2 | **WordPress article migration completed, closing the last open item from Phase 2.** Brandon provided a real WXR export (`cellarlabels.WordPress.2026-07-14.xml`, ~1.6MB) from the still-live WordPress site. Of 352 total `` entries in the export (mostly `attachment`/`dlm_download`/Divi-theme cruft), only 4 were actual blog posts, and only 3 of those were publishable: "Getting Started: A Brief Overview," "Choosing The Right Jar," and "Creating Custom Labels: Using a Free Online Photo Editor" (all `category: Cellaring Guides`, all `status: publish`). The 4th, "Cellaring Tobacco in Mylar Bags," was a `status: draft` post with genuinely empty content (an unfinished Divi shell with no text) -- correctly excluded, since migrating a never-published draft as a live guide would have published content the original author never intended to ship. **Hand-converted rather than auto-converted:** the post content was wrapped in Divi page-builder shortcode markup (`et_pb_section`/`et_pb_row`/`et_pb_text`, plus Grammarly `` span artifacts throughout the raw HTML). At only 3 posts, hand-building each one's Portable Text `body` array in a migration script was more reliable than writing a generic Divi-to-Portable-Text converter, and let real cleanup happen along the way: dropped a Divi cross-promo/CTA block that wasn't real article content (replaced with a plain "Next up: [link]" paragraph using the new site's actual slug), repointed internal links from the dead `cellarlabels.com/printing-templates/` and `community.cellarlabels.com/login/` (the old community site this project explicitly replaces) to the new site's `/templates` and `/register` routes, converted a 2-cell HTML `` to a 2-item bullet list since the `article` schema's `body` field only supports `block`/`image` types, dropped an `