chore: release v0.4.8

chore: register 0018_container_images in drizzle migration journal
feat: share links visible on plants/containers; container image gallery
2026-06-02 20:26:57 -05:00 · 2026-06-02 20:19:57 -05:00 · 2026-06-02 20:15:29 -05:00 · 2026-06-02 19:53:18 -05:00 · 2026-06-02 19:52:55 -05:00 · 2026-06-02 19:52:24 -05:00
48 changed files with 3439 additions and 200 deletions
@@ -1,5 +1,5 @@
 # Public app URL (used for OIDC redirect URIs, share links, etc.)
-NEXT_PUBLIC_APP_URL=https://fam.ginnoir.com
+NEXT_PUBLIC_APP_URL=https://fam.yourdomain.com

 # Postgres
 DATABASE_URL=postgres://famapp:famapp@localhost:5432/famapp
@@ -15,7 +15,7 @@ DEV_LOGIN_NAME=Dev User
 DEV_HOUSEHOLD_NAME=Home

 # OIDC (Authentik)
-AUTH_OIDC_ISSUER=https://auth.ginnoir.com/application/o/famapp/
+AUTH_OIDC_ISSUER=https://auth.yourdomain.com/application/o/famapp/
 AUTH_OIDC_CLIENT_ID=replace-me
 AUTH_OIDC_CLIENT_SECRET=replace-me

@@ -1,51 +1,57 @@
 # ── famapp ────────────────────────────────────────────────────────────────────
+# These vars are consumed by the famapp service in docker-compose.yml.

 # Image tag to deploy. Pin to a specific version after first deploy
 # (e.g. ghcr.io/ginnoir/famapp:v0.1.0). `latest` is fine for staging/initial.
 FAMAPP_IMAGE=ghcr.io/ginnoir/famapp:latest
-# `always` pulls on every `up`; set `missing` if you want to skip pulls.
 FAMAPP_PULL_POLICY=always
-# Authentik image tag. Bump in lockstep with Authentik release notes.
 AUTHENTIK_IMAGE_TAG=2024.12.3
-# Run drizzle migrations on container start. Leave true.
 RUN_MIGRATIONS=true

-# Public URL for the app — used by Auth.js for OIDC redirect URIs.
-AUTH_URL=https://fam.ginnoir.com
+# Public URL for the app
+AUTH_URL=https://fam.yourdomain.com

-# famapp Postgres credentials (used to build DATABASE_URL inside compose.yaml)
+# famapp Postgres
 FAMAPP_DB_USER=famapp
 FAMAPP_DB_PASSWORD=replace-with-strong-password
 FAMAPP_DB_NAME=famapp

 # Auth.js session secret — generate with: openssl rand -base64 32
+# NOTE: Reactive Resume uses RESUME_AUTH_SECRET; AUTH_SECRET is famapp-only.
+
 AUTH_SECRET=replace-with-openssl-rand-base64-32

 # OIDC provider (Authentik) — fill in after bootstrapping Authentik
-AUTH_OIDC_ISSUER=https://auth.ginnoir.com/application/o/famapp/
+AUTH_OIDC_ISSUER=https://auth.yourdomain.com/application/o/famapp/
 AUTH_OIDC_CLIENT_ID=replace-me
 AUTH_OIDC_CLIENT_SECRET=replace-me

-# Web Push VAPID keys — generate with: pnpm vapid:generate (run from the repo)
+# Web Push VAPID keys — generate with: pnpm vapid:generate
 VAPID_PUBLIC_KEY=
 VAPID_PRIVATE_KEY=
-# Must be "mailto:<address>" or a URL
-VAPID_SUBJECT=mailto:3nigma.matt@gmail.com
+VAPID_SUBJECT=mailto:your-email@example.com

-# ntfy push fallback — uses your existing ntfy instance at ntfy.ginnoir.com
-# Leave NTFY_URL blank to disable ntfy fanout.
-NTFY_URL=https://ntfy.ginnoir.com
+# ntfy push fallback
+NTFY_URL=https://ntfy.yourdomain.com
 NTFY_TOPIC=famapp

 # Log level: error | warn | info | debug
 LOG_LEVEL=info

-# ── Authentik ─────────────────────────────────────────────────────────────────
+# MinIO object storage (garden image uploads)
+famapp_MINIO_ROOT_USER=famapp
+famapp_MINIO_ROOT_PASSWORD=replace-with-strong-password
+famapp_MINIO_BUCKET=garden

-# Authentik Postgres credentials (separate DB per Matt's rule)
+# OpenPlantBook API (optional — used for plant species lookup)
+famapp_OPENPLANTBOOK_CLIENT_ID=
+famapp_OPENPLANTBOOK_CLIENT_SECRET=
+
+# ── Authentik ─────────────────────────────────────────────────────────────────
 AUTHENTIK_DB_USER=authentik
 AUTHENTIK_DB_PASSWORD=replace-with-strong-password
 AUTHENTIK_DB_NAME=authentik
-
-# Authentik secret key — generate with: openssl rand -base64 60
 AUTHENTIK_SECRET_KEY=replace-with-openssl-rand-base64-60
+
+# ── Cloudflare (Caddy DNS-01 TLS) ─────────────────────────────────────────────
+CF_API_TOKEN=replace-with-cloudflare-api-token
@@ -49,5 +49,13 @@ tests/.auth/
 # Backups
 deploy/backups/data/

+# Production configs and deploy scripts — maintainer-specific, never commit
+deploy/.prod/
+deploy/compose.yaml
+deploy/Caddyfile
+deploy/Caddyfile.dev.snippet
+scripts/apply-compose.ps1
+scripts/sync-prod.ps1
+
 # Design handoff bundle (reference only, not committed)
 .design-tmp/
@@ -11,6 +11,9 @@
    "release": true,
    "releaseName": "v${version}"
  },
+  "hooks": {
+    "before:git:release": "echo 'Check: README.md reflects current modules and env vars before tagging'"
+  },
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": {
@@ -1,5 +1,34 @@
 # Changelog

+## [0.4.8](https://github.com/ginnoir/famapp/compare/v0.4.6...v0.4.8) (2026-06-03)
+
+### Features
+
+- **garden:** add share button to plant and container detail views ([989bae8](https://github.com/ginnoir/famapp/commit/989bae8f1e2d5577da3e8777b6a35320c6da274c))
+- share links visible on plants/containers; container image gallery ([c6a34f7](https://github.com/ginnoir/famapp/commit/c6a34f74717505e39ac4a88077728efa9fc50478))
+
+### Bug Fixes
+
+- **deploy:** separate reactive resume auth_secret from famapp ([aae3e30](https://github.com/ginnoir/famapp/commit/aae3e30843f54406244b637073aaf5e9ccc6b1d3))
+
+### Documentation
+
+- add contributing guide, env reference, and operations runbook ([076e35a](https://github.com/ginnoir/famapp/commit/076e35aced9303973da71ddd0ebded13f6c98833))
+- add professional readme with full feature coverage and release pipeline hook ([6a1ec8b](https://github.com/ginnoir/famapp/commit/6a1ec8bb7be7ce64e82e5a4cee6b9f4ef92c7af8))
+- update decisions index and task index for garden module and adr backfill ([8bf00c3](https://github.com/ginnoir/famapp/commit/8bf00c326db591851bdf8eee2fcedbfbed53d076))
+
+## [0.4.6](https://github.com/ginnoir/famapp/compare/v0.4.5...v0.4.6) (2026-06-02)
+
+### Bug Fixes
+
+- **garden:** accept relative urls for plant image uploads ([6ca2e52](https://github.com/ginnoir/famapp/commit/6ca2e52e0a63d94826d9b1e208bcdded9c75fb07))
+
+## [0.4.5](https://github.com/ginnoir/famapp/compare/v0.4.4...v0.4.5) (2026-06-02)
+
+### Features
+
+- **bangs:** add bang counter dashboard widget ([c850521](https://github.com/ginnoir/famapp/commit/c850521f3e993a5410f37cf29eb635cbc9540fd1))
+
 ## [0.4.4](https://github.com/ginnoir/famapp/compare/v0.4.3...v0.4.4) (2026-06-02)

 ### Bug Fixes
@@ -1,8 +1,158 @@
 # famapp

-Self-hosted family coordination: shared calendar, lists, notes.
+Self-hosted family coordination web app. Shared calendar, lists, notes, and garden tracker — installable as a PWA, protected by OIDC single sign-on.

- **Plan & architecture:** [`CLAUDE.md`](CLAUDE.md)
- **Current progress:** [`STATUS.md`](STATUS.md)
- **Task briefs (for sub-sessions):** [`docs/tasks/`](docs/tasks/)
- **Architecture decisions:** [`docs/decisions/`](docs/decisions/)
+[![CI](https://github.com/ginnoir/famapp/actions/workflows/ci.yml/badge.svg)](https://github.com/ginnoir/famapp/actions/workflows/ci.yml)
+[![Latest release](https://img.shields.io/github/v/release/ginnoir/famapp?sort=semver)](https://github.com/ginnoir/famapp/releases)
+[![Docker image](https://img.shields.io/badge/image-ghcr.io%2Fginnoir%2Ffamapp-blue?logo=docker)](https://github.com/ginnoir/famapp/pkgs/container/famapp)
+[![Node ≥ 22](https://img.shields.io/badge/node-%E2%89%A522-brightgreen?logo=node.js)](https://nodejs.org)
+
+---
+
+## Features
+
+### Modules
+
+| Module       | What it does                                                                               |
+| ------------ | ------------------------------------------------------------------------------------------ |
+| **Calendar** | Month / week / day views, drag-to-create, household and private calendars, event reminders |
+| **Lists**    | Shopping and task lists with real-time sync, reorder, keyboard-first item entry            |
+| **Notes**    | Markdown notes with pinning, safe preview, and optional remind-at scheduling               |
+| **Garden**   | Plant and container tracking, care schedules, care logs, species lookup via OpenPlantBook  |
+
+### Platform capabilities
+
+| Capability             | Detail                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| **Dashboard**          | Per-user named dashboards, drag-resize widget grid, configurable widget instances           |
+| **Quick-add**          | `Cmd/Ctrl+K` command palette and `+` FAB — every module registers its own actions           |
+| **Share links**        | Any entity produces a temporary public link (`/s/<token>`), scoped read or read-write       |
+| **Activity log**       | Household-scoped feed of every create / update / delete across all modules                  |
+| **Reminders**          | Generic reminder engine ticked every 30 s; notes and calendar events both use it            |
+| **Push notifications** | VAPID web push + in-app inbox + optional ntfy fallback                                      |
+| **Themes**             | Two palettes (`default` / `warm`) × light / dark / system, zero flash on load               |
+| **PWA / offline**      | Installable on iOS and Android, offline shell, stale-while-revalidate caching               |
+| **Structured logging** | JSON logs via pino in production, pretty-printed in dev, `LOG_LEVEL` configurable           |
+| **Nightly backups**    | `pg_dump` cron for both databases, 14-day daily / 8-week weekly / 6-month monthly retention |
+
+---
+
+## Requirements
+
+- **Docker** with the Compose plugin (v2)
+- **Caddy** (or any reverse proxy that handles HTTPS)
+- **Authentik** — famapp delegates all authentication to an Authentik OIDC provider; see the [bootstrap guide](deploy/authentik/README.md)
+- A domain with DNS pointing to your host
+
+---
+
+## Quick start
+
+Full details are in [`deploy/README.md`](deploy/README.md). The short version:
+
+```bash
+# 1. Clone and enter the repo
+git clone https://github.com/ginnoir/famapp.git /srv/famapp
+cd /srv/famapp
+
+# 2. Create your environment file
+cp .env.production.example deploy/.env
+# Edit deploy/.env — see Configuration below for required values
+
+# 3. Configure your reverse proxy
+# Add deploy/Caddyfile.snippet to your Caddyfile, then reload Caddy
+
+# 4. Bootstrap Authentik and record the OIDC client id/secret in deploy/.env
+# See deploy/authentik/README.md
+
+# 5. Start the stack
+docker compose -f deploy/compose.example.yaml up -d
+```
+
+The container runs database migrations automatically on start. The first user to sign in becomes the household owner; a second sign-in joins the same household as a member.
+
+Pin `FAMAPP_IMAGE` in `deploy/.env` after the first deploy:
+
+```
+FAMAPP_IMAGE=ghcr.io/ginnoir/famapp:v0.4.7
+```
+
+---
+
+## Development setup
+
+Requires Node ≥ 22 and pnpm 10.
+
+```bash
+git clone https://github.com/ginnoir/famapp.git
+cd famapp
+pnpm install
+
+# Copy the example env and fill in dev values (set ENABLE_DEV_LOGIN=true)
+cp .env.example .env
+
+# Start the local database, run migrations, seed, and launch the dev server
+pnpm dev:local
+```
+
+Then open `http://localhost:3000/login` and click **Dev login**.
+
+Additional dev commands:
+
+| Command               | Purpose                                        |
+| --------------------- | ---------------------------------------------- |
+| `pnpm dev:reset`      | Drop and reseed the local database             |
+| `pnpm db:studio`      | Open Drizzle Studio against the local database |
+| `pnpm db:generate`    | Generate a new migration after schema changes  |
+| `pnpm typecheck`      | Run `tsc --noEmit`                             |
+| `pnpm lint`           | ESLint                                         |
+| `pnpm test:e2e`       | Playwright E2E suite                           |
+| `pnpm vapid:generate` | Print VAPID key env vars to stdout             |
+| `pnpm gen:icons`      | Regenerate PWA icons from `public/icon.svg`    |
+
+See [`docs/dev-login.md`](docs/dev-login.md) for push notification and E2E testing setup.
+
+---
+
+## Configuration
+
+Copy `.env.production.example` to `deploy/.env` and fill in values. Key variables:
+
+| Variable                         | Required | How to generate                                                      |
+| -------------------------------- | -------- | -------------------------------------------------------------------- |
+| `AUTH_URL`                       | Yes      | Public HTTPS URL for the app (e.g. `https://fam.yourdomain.com`)     |
+| `AUTH_SECRET`                    | Yes      | `openssl rand -base64 32`                                            |
+| `AUTH_OIDC_ISSUER`               | Yes      | From Authentik — `https://auth.yourdomain.com/application/o/famapp/` |
+| `AUTH_OIDC_CLIENT_ID`            | Yes      | From Authentik application                                           |
+| `AUTH_OIDC_CLIENT_SECRET`        | Yes      | From Authentik application                                           |
+| `FAMAPP_DB_PASSWORD`             | Yes      | Strong random password                                               |
+| `AUTHENTIK_DB_PASSWORD`          | Yes      | Strong random password                                               |
+| `AUTHENTIK_SECRET_KEY`           | Yes      | `openssl rand -base64 60`                                            |
+| `VAPID_PUBLIC_KEY`               | Push     | `pnpm vapid:generate`                                                |
+| `VAPID_PRIVATE_KEY`              | Push     | `pnpm vapid:generate`                                                |
+| `VAPID_SUBJECT`                  | Push     | `mailto:your-email@example.com`                                      |
+| `NTFY_URL` / `NTFY_TOPIC`        | Optional | ntfy push fallback                                                   |
+| `famapp_OPENPLANTBOOK_CLIENT_ID` | Optional | OpenPlantBook API — plant species lookup                             |
+| `LOG_LEVEL`                      | Optional | `error` / `warn` / `info` / `debug` (default: `info`)                |
+
+---
+
+## Architecture
+
+famapp uses an extensibility-first module system: every feature lives under `src/modules/<name>/` and declares its tables, routes, dashboard widgets, quick-add actions, and share/reminder/search behaviors via a manifest. Core services (sharing, push, reminders, activity log, search) operate generically — adding a new module does not require touching core code.
+
+See [`CLAUDE.md`](CLAUDE.md) for the full architecture brief and [`docs/decisions/`](docs/decisions/) for ADRs.
+
+---
+
+## Deployment
+
+| Resource             | Link                                                                             |
+| -------------------- | -------------------------------------------------------------------------------- |
+| Full host setup      | [`deploy/README.md`](deploy/README.md)                                           |
+| Authentik bootstrap  | [`deploy/authentik/README.md`](deploy/authentik/README.md)                       |
+| Backup / restore     | [`deploy/backups/README.md`](deploy/backups/README.md)                           |
+| Pre-deploy checklist | [`docs/tasks/09-pre-deploy-checklist.md`](docs/tasks/09-pre-deploy-checklist.md) |
+| Changelog            | [`CHANGELOG.md`](CHANGELOG.md)                                                   |
+
+Cutting a release: tag `vX.Y.Z` on `main` and push — CI builds and pushes `ghcr.io/ginnoir/famapp:vX.Y.Z` automatically.
@@ -1,10 +1,11 @@
-# famapp — paste into your existing Caddyfile.
-# famapp runs on 3010, authentik-server on 9200 (both bound to the host by deploy/compose.yaml).
+# Add these blocks to your existing Caddyfile.
+# Assumes famapp and authentik-server are reachable by Caddy
+# (e.g. on a shared Docker network).

-fam.ginnoir.com {
-    reverse_proxy 192.168.1.69:3010
+fam.yourdomain.com {
+	reverse_proxy famapp:3000
 }

-auth.ginnoir.com {
-    reverse_proxy 192.168.1.69:9200
+auth.yourdomain.com {
+	reverse_proxy authentik-server:9000
 }
@@ -2,16 +2,30 @@

 Trunk-based: `main` is always green. Production deploys only from version tags (`vX.Y.Z`). The dev-login flow is retained for local development behind a double gate (`NODE_ENV !== "production"` **and** `ENABLE_DEV_LOGIN=true`); a startup assertion in `src/lib/dev-login-config.ts` makes a misconfigured prod fail loud instead of silently exposing it.

+## Files in this directory
+
+| File                    | Purpose                                                                    |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `compose.example.yaml`  | **Start here.** Standalone famapp + Authentik stack for new deployments.   |
+| `compose.yaml`          | Maintainer's production compose (full homelab monolith — not a template).  |
+| `Caddyfile.snippet`     | Reverse proxy blocks to add to your Caddyfile.                             |
+| `Caddyfile.dev.snippet` | Dev machine proxy block (maintainer-specific).                             |
+| `Caddyfile`             | Maintainer's full production Caddyfile (not a template).                   |
+| `authentik/README.md`   | Authentik bootstrap guide.                                                 |
+| `backups/`              | Backup container scripts (used by `famapp-backup` in the example compose). |
+
 ## One-time host setup

 1. Install Docker + Compose plugin on the host.
 2. `git clone` this repo to e.g. `/srv/famapp`.
-3. Copy `.env.production.example` → `/srv/famapp/deploy/.env` and fill in real values.
+3. Copy `deploy/compose.example.yaml` → `/srv/famapp/deploy/compose.yaml`.
+4. Copy `.env.production.example` → `/srv/famapp/deploy/.env` and fill in real values.
   - `openssl rand -base64 32` for `AUTH_SECRET`.
   - `openssl rand -base64 60` for `AUTHENTIK_SECRET_KEY`.
-   - `pnpm vapid:generate` (locally) for the three VAPID lines.
-4. Bootstrap Authentik per `deploy/authentik/README.md`. Save the OIDC client id/secret into `.env`.
-5. Wire Caddy with `deploy/Caddyfile.snippet`.
+   - `openssl rand -hex 64` for the MinIO passwords.
+   - `pnpm vapid:generate` (locally, from the repo) for the three VAPID lines.
+5. Bootstrap Authentik per `deploy/authentik/README.md`. Save the OIDC client id/secret into `.env`.
+6. Wire Caddy (or any reverse proxy) using `deploy/Caddyfile.snippet`.

 ## Cutting a release

@@ -28,7 +42,7 @@ git push origin v0.1.0
 ```bash
 cd /srv/famapp/deploy
 # pin to the tag you just cut
-echo 'FAMAPP_IMAGE=ghcr.io/ginnoir/famapp:v0.1.0' >> .env  # or edit in place
+sed -i 's|FAMAPP_IMAGE=.*|FAMAPP_IMAGE=ghcr.io/ginnoir/famapp:v0.1.0|' .env
 docker compose pull famapp
 docker compose up -d famapp
 docker compose logs -f famapp   # watch migrations + boot
@@ -6,13 +6,13 @@ Run these steps once after the first `docker compose up -d` in the `deploy/` dir

 ## 1. Set the admin password

-Visit `https://auth.ginnoir.com/if/flow/initial-setup/` and set the **akadmin** password.
+Visit `https://auth.yourdomain.com/if/flow/initial-setup/` and set the **akadmin** password.

 ---

 ## 2. Create the OIDC provider

-1. Log in to the Authentik Admin UI at `https://auth.ginnoir.com/if/admin/`.
+1. Log in to the Authentik Admin UI at `https://auth.yourdomain.com/if/admin/`.
 2. Go to **Applications → Providers → Create**.
 3. Choose **OAuth2/OpenID Provider**.
 4. Configure:
@@ -21,7 +21,7 @@ Visit `https://auth.ginnoir.com/if/flow/initial-setup/` and set the **akadmin**
   - **Client type:** `Confidential`
   - **Client ID:** (auto-generated — copy this)
   - **Client Secret:** (auto-generated — copy this)
-   - **Redirect URIs:** `https://fam.ginnoir.com/api/auth/callback/authentik`
+   - **Redirect URIs:** `https://fam.yourdomain.com/api/auth/callback/authentik`
   - **Signing Key:** `authentik Self-signed Certificate`
   - **Token validity:** 24 hours (or your preference)
 5. Save and note the **Issuer URL** shown on the provider detail page.
@@ -29,13 +29,13 @@ Visit `https://auth.ginnoir.com/if/flow/initial-setup/` and set the **akadmin**
 The issuer URL will look like:

 ```
-https://auth.ginnoir.com/application/o/famapp/
+https://auth.yourdomain.com/application/o/famapp/
 ```

 Set this (and the client ID/secret) in famapp's `.env` / production secrets:

 ```env
-AUTH_OIDC_ISSUER=https://auth.ginnoir.com/application/o/famapp/
+AUTH_OIDC_ISSUER=https://auth.yourdomain.com/application/o/famapp/
 AUTH_OIDC_CLIENT_ID=<client-id>
 AUTH_OIDC_CLIENT_SECRET=<client-secret>
 ```
@@ -49,7 +49,7 @@ AUTH_OIDC_CLIENT_SECRET=<client-secret>
   - **Name:** `famapp`
   - **Slug:** `famapp`
   - **Provider:** select the `famapp` provider created above
-   - **Launch URL:** `https://fam.ginnoir.com`
+   - **Launch URL:** `https://fam.yourdomain.com`
 3. Save.

 ---
@@ -68,7 +68,7 @@ AUTH_OIDC_CLIENT_SECRET=<client-secret>

 Each user can enroll a passkey from their Authentik profile:

-1. Sign in as the user at `https://auth.ginnoir.com`.
+1. Sign in as the user at `https://auth.yourdomain.com`.
 2. Go to **Settings → MFA Devices → Add → WebAuthn Device**.
 3. Follow the browser prompt to register a Touch ID / Face ID / hardware key.

@@ -0,0 +1,196 @@
+# Standalone famapp deployment template.
+# Copy this to compose.yaml (or reference with -f), fill in .env from
+# .env.production.example, then: docker compose up -d
+#
+# Caddy (or any reverse proxy) should sit in front — see Caddyfile.snippet.
+# If Caddy runs in a separate compose stack, add famapp to that stack's
+# external network instead of exposing ports directly.
+
+name: famapp
+
+networks:
+  famapp_net:
+
+volumes:
+  famapp_db_data:
+  authentik_db_data:
+  authentik_redis_data:
+  garden_uploads:
+  backups:
+
+services:
+  famapp:
+    image: ${FAMAPP_IMAGE:-ghcr.io/ginnoir/famapp:latest}
+    pull_policy: ${FAMAPP_PULL_POLICY:-always}
+    restart: unless-stopped
+    environment:
+      NODE_ENV: production
+      AUTH_URL: ${AUTH_URL}
+      DATABASE_URL: postgres://${FAMAPP_DB_USER}:${FAMAPP_DB_PASSWORD}@famapp-db:5432/${FAMAPP_DB_NAME}
+      AUTH_SECRET: ${AUTH_SECRET}
+      AUTH_OIDC_ISSUER: ${AUTH_OIDC_ISSUER}
+      AUTH_OIDC_CLIENT_ID: ${AUTH_OIDC_CLIENT_ID}
+      AUTH_OIDC_CLIENT_SECRET: ${AUTH_OIDC_CLIENT_SECRET}
+      VAPID_PUBLIC_KEY: ${VAPID_PUBLIC_KEY}
+      VAPID_PRIVATE_KEY: ${VAPID_PRIVATE_KEY}
+      VAPID_SUBJECT: ${VAPID_SUBJECT}
+      NTFY_URL: ${NTFY_URL:-}
+      NTFY_TOPIC: ${NTFY_TOPIC:-}
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+      RUN_MIGRATIONS: ${RUN_MIGRATIONS:-true}
+      MINIO_ENDPOINT: http://famapp-minio:9000
+      MINIO_ROOT_USER: ${famapp_MINIO_ROOT_USER}
+      MINIO_ROOT_PASSWORD: ${famapp_MINIO_ROOT_PASSWORD}
+      MINIO_BUCKET: ${famapp_MINIO_BUCKET:-garden}
+      OPENPLANTBOOK_CLIENT_ID: ${famapp_OPENPLANTBOOK_CLIENT_ID:-}
+      OPENPLANTBOOK_CLIENT_SECRET: ${famapp_OPENPLANTBOOK_CLIENT_SECRET:-}
+    ports:
+      - "${FAMAPP_PORT:-3000}:3000"
+    depends_on:
+      famapp-db:
+        condition: service_healthy
+      famapp-minio:
+        condition: service_healthy
+    networks:
+      - famapp_net
+
+  famapp-db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${FAMAPP_DB_USER}
+      POSTGRES_PASSWORD: ${FAMAPP_DB_PASSWORD}
+      POSTGRES_DB: ${FAMAPP_DB_NAME}
+    volumes:
+      - famapp_db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${FAMAPP_DB_USER} -d ${FAMAPP_DB_NAME}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - famapp_net
+
+  famapp-minio:
+    image: minio/minio:latest
+    command: server /data --console-address ":9001"
+    restart: unless-stopped
+    environment:
+      MINIO_ROOT_USER: ${famapp_MINIO_ROOT_USER}
+      MINIO_ROOT_PASSWORD: ${famapp_MINIO_ROOT_PASSWORD}
+    volumes:
+      - garden_uploads:/data
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:9000/minio/health/live || exit 1"]
+      interval: 30s
+      timeout: 20s
+      retries: 3
+      start_period: 30s
+    networks:
+      - famapp_net
+
+  famapp-backup:
+    image: alpine:3.20
+    restart: unless-stopped
+    environment:
+      FAMAPP_DB_HOST: famapp-db
+      FAMAPP_DB_PORT: "5432"
+      FAMAPP_DB_USER: ${FAMAPP_DB_USER}
+      FAMAPP_DB_PASSWORD: ${FAMAPP_DB_PASSWORD}
+      FAMAPP_DB_NAME: ${FAMAPP_DB_NAME}
+      AUTHENTIK_DB_HOST: authentik-db
+      AUTHENTIK_DB_PORT: "5432"
+      AUTHENTIK_DB_USER: ${AUTHENTIK_DB_USER:-authentik}
+      AUTHENTIK_DB_PASSWORD: ${AUTHENTIK_DB_PASSWORD}
+      AUTHENTIK_DB_NAME: ${AUTHENTIK_DB_NAME:-authentik}
+    volumes:
+      - backups:/backups
+      - ./backups:/scripts:ro
+    depends_on:
+      famapp-db:
+        condition: service_healthy
+      authentik-db:
+        condition: service_healthy
+    networks:
+      - famapp_net
+    entrypoint: ["sh", "/scripts/entrypoint.sh"]
+
+  authentik-server:
+    image: ghcr.io/goauthentik/server:${AUTHENTIK_IMAGE_TAG:-2024.12.3}
+    restart: unless-stopped
+    command: server
+    environment:
+      AUTHENTIK_REDIS__HOST: authentik-redis
+      AUTHENTIK_POSTGRESQL__HOST: authentik-db
+      AUTHENTIK_POSTGRESQL__USER: ${AUTHENTIK_DB_USER:-authentik}
+      AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_DB_PASSWORD}
+      AUTHENTIK_POSTGRESQL__NAME: ${AUTHENTIK_DB_NAME:-authentik}
+      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY}
+      AUTHENTIK_ERROR_REPORTING__ENABLED: "false"
+    ports:
+      - "9200:9000"
+    depends_on:
+      authentik-db:
+        condition: service_healthy
+      authentik-redis:
+        condition: service_healthy
+    networks:
+      - famapp_net
+
+  authentik-worker:
+    image: ghcr.io/goauthentik/server:${AUTHENTIK_IMAGE_TAG:-2024.12.3}
+    restart: unless-stopped
+    command: worker
+    environment:
+      AUTHENTIK_REDIS__HOST: authentik-redis
+      AUTHENTIK_POSTGRESQL__HOST: authentik-db
+      AUTHENTIK_POSTGRESQL__USER: ${AUTHENTIK_DB_USER:-authentik}
+      AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_DB_PASSWORD}
+      AUTHENTIK_POSTGRESQL__NAME: ${AUTHENTIK_DB_NAME:-authentik}
+      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY}
+      AUTHENTIK_ERROR_REPORTING__ENABLED: "false"
+    depends_on:
+      authentik-db:
+        condition: service_healthy
+      authentik-redis:
+        condition: service_healthy
+    networks:
+      - famapp_net
+
+  authentik-db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${AUTHENTIK_DB_USER:-authentik}
+      POSTGRES_PASSWORD: ${AUTHENTIK_DB_PASSWORD}
+      POSTGRES_DB: ${AUTHENTIK_DB_NAME:-authentik}
+    volumes:
+      - authentik_db_data:/var/lib/postgresql/data
+    healthcheck:
+      test:
+        [
+          "CMD-SHELL",
+          "pg_isready -U ${AUTHENTIK_DB_USER:-authentik} -d ${AUTHENTIK_DB_NAME:-authentik}",
+        ]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - famapp_net
+
+  authentik-redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    command: --save 60 1 --loglevel warning
+    volumes:
+      - authentik_redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - famapp_net
@@ -1,11 +0,0 @@
-#!/bin/sh
-set -e
-
-if [ "${RUN_MIGRATIONS:-true}" = "true" ]; then
-  echo "running migrations..."
-  node /app/scripts/migrate.mjs
-else
-  echo "skipping migrations (RUN_MIGRATIONS=$RUN_MIGRATIONS)"
-fi
-
-exec node /app/server.js
@@ -0,0 +1,158 @@
+# Contributing
+
+## Prerequisites
+
+- **Node.js** 22 LTS (`node --version` should print `v22.x.x`)
+- **pnpm** 10 (`pnpm --version` should print `10.x.x`)
+- **Docker** with the Compose plugin (used for the local Postgres + MinIO containers)
+
+## Setup
+
+```bash
+git clone https://github.com/ginnoir/famapp.git
+cd famapp
+pnpm install
+cp .env.example .env
+# Edit .env — minimum required for local dev:
+#   NEXT_PUBLIC_APP_URL=http://127.0.0.1:3000
+#   DATABASE_URL=postgres://famapp:famapp@localhost:5432/famapp
+#   ENABLE_DEV_LOGIN=true
+#   AUTH_SECRET=<any-32-char-string-for-local>
+```
+
+Start everything (database + migrations + seed + dev server):
+
+```bash
+pnpm dev:local
+```
+
+Then open `http://localhost:3000/login` and click **Dev login**. See `docs/dev-login.md` for the full local setup including HTTPS/PWA testing.
+
+## Available scripts
+
+<!-- AUTO-GENERATED from package.json scripts -->
+
+| Command               | Description                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------- |
+| `pnpm dev`            | Next.js dev server (localhost only)                                                       |
+| `pnpm dev:network`    | Dev server bound to `0.0.0.0` (LAN access for phone testing)                              |
+| `pnpm dev:local`      | Full local stack — starts DB container, runs migrations, seeds, launches dev server       |
+| `pnpm dev:reset`      | Tear down local DB and start fresh (destructive — deletes all local data)                 |
+| `pnpm build`          | Production Next.js build                                                                  |
+| `pnpm start`          | Start the production build locally                                                        |
+| `pnpm lint`           | ESLint check                                                                              |
+| `pnpm lint:fix`       | ESLint with auto-fix                                                                      |
+| `pnpm format`         | Prettier — format all files                                                               |
+| `pnpm format:check`   | Prettier — check only (used in CI)                                                        |
+| `pnpm typecheck`      | TypeScript type check (`tsc --noEmit`)                                                    |
+| `pnpm test:e2e`       | Playwright end-to-end tests                                                               |
+| `pnpm db:generate`    | Generate a new Drizzle migration from schema changes                                      |
+| `pnpm db:migrate`     | Apply pending Drizzle migrations                                                          |
+| `pnpm db:seed`        | Seed the database with dev fixtures                                                       |
+| `pnpm db:studio`      | Open Drizzle Studio (local DB browser)                                                    |
+| `pnpm gen:icons`      | Regenerate PWA icon set from source                                                       |
+| `pnpm vapid:generate` | Generate VAPID key pair for Web Push                                                      |
+| `pnpm release`        | Interactive release (prompts for semver bump, tags, publishes changelog + GitHub Release) |
+| `pnpm release:patch`  | Non-interactive patch release                                                             |
+| `pnpm release:minor`  | Non-interactive minor release                                                             |
+| `pnpm release:major`  | Non-interactive major release                                                             |
+| `pnpm release:dry`    | Dry-run release — preview without writing                                                 |
+
+<!-- END AUTO-GENERATED -->
+
+## Running tests
+
+### Type check + lint (CI equivalent)
+
+```bash
+pnpm typecheck
+pnpm lint
+pnpm format:check
+```
+
+### End-to-end tests
+
+The app must be running first (`pnpm dev:local`). Generate a Playwright auth state file, then run tests:
+
+```powershell
+# Generate auth state (run once after starting the app)
+New-Item -ItemType Directory -Force tests\.auth | Out-Null
+@'
+const { chromium } = require('@playwright/test');
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto('http://127.0.0.1:3000/login');
+  await page.getByRole('button', { name: 'Dev login' }).click();
+  await page.waitForURL('http://127.0.0.1:3000/');
+  await page.context().storageState({ path: 'tests/.auth/dev-user.json' });
+  await browser.close();
+})();
+'@ | node -
+
+# Run tests
+$env:PLAYWRIGHT_STORAGE_STATE='tests/.auth/dev-user.json'
+pnpm test:e2e
+```
+
+### Writing tests
+
+- Unit tests: Vitest under `tests/unit/` — only where it pays off (utilities, pure logic).
+- E2E tests: Playwright under `tests/e2e/` — one happy-path test per module. Do not write brittle selector-heavy tests for trivial CRUD.
+
+## Code style
+
+- **TypeScript strict** — no `any` without a written reason.
+- **No comments** unless the _why_ is non-obvious. Names carry intent.
+- **Immutable** — always return new objects; never mutate in place.
+- **Module isolation** — a module imports from `_core` and `lib/` only; never from a sibling module.
+- **File size** — 200–400 lines typical, 800 hard cap.
+
+Formatting and lint run automatically on staged files via `lint-staged` at commit time. You can also run them manually with `pnpm lint:fix` and `pnpm format`.
+
+## Commit format
+
+Commits must follow [Conventional Commits](https://www.conventionalcommits.org/). `commitlint` enforces this at the `commit-msg` hook.
+
+```
+<type>: <short description>
+
+[optional body]
+```
+
+Allowed types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `revert`
+
+Examples:
+
+```
+feat: add plant species search to garden module
+fix: calendar event end time off by one day
+chore: bump next to 15.6
+```
+
+## Adding a module
+
+Every feature lives under `src/modules/<name>/`. A new module needs:
+
+- `schema.ts` — Drizzle tables
+- `server/` — server actions and queries
+- `components/` — React components
+- `manifest.ts` — registers the module with the core registry (nav, entity types, dashboard widget, quick-add actions)
+
+See `CLAUDE.md` for the full architectural brief. The module loader in `src/modules/_core/` discovers manifests automatically — no changes to core code required for a new module.
+
+## Schema changes
+
+1. Edit the relevant `schema.ts`.
+2. Run `pnpm db:generate` to create a new migration file under `drizzle/`.
+3. Commit the migration alongside the schema change.
+4. Never edit a shipped migration — always add a new one.
+
+## PR checklist
+
+- [ ] `pnpm typecheck` passes
+- [ ] `pnpm lint` passes
+- [ ] `pnpm build` succeeds
+- [ ] New Drizzle migration committed if schema changed
+- [ ] E2E test added or updated if a user-visible flow changed
+- [ ] `docs/tasks/09-pre-deploy-checklist.md` reviewed if touching auth or env
@@ -0,0 +1,112 @@
+# Environment Variables
+
+<!-- AUTO-GENERATED from .env.example and deploy/compose.example.yaml -->
+
+## Quick start
+
+```bash
+cp .env.example .env
+# Fill in required values, then:
+pnpm dev:local
+```
+
+## Core
+
+| Variable              | Required | Description                                                        | Example / Default                                |
+| --------------------- | -------- | ------------------------------------------------------------------ | ------------------------------------------------ |
+| `NEXT_PUBLIC_APP_URL` | Yes      | Public URL of the app — used in OIDC redirect URIs and share links | `https://fam.yourdomain.com`                     |
+| `DATABASE_URL`        | Yes      | Postgres connection string                                         | `postgres://famapp:famapp@localhost:5432/famapp` |
+| `AUTH_SECRET`         | Yes      | Auth.js signing secret — generate with `openssl rand -base64 32`   | —                                                |
+
+## OIDC (Authentik)
+
+Required in production. Obtain from the Authentik admin panel after bootstrapping the provider — see `deploy/authentik/README.md`.
+
+| Variable                  | Required   | Description                       | Example                                             |
+| ------------------------- | ---------- | --------------------------------- | --------------------------------------------------- |
+| `AUTH_OIDC_ISSUER`        | Yes (prod) | Authentik OIDC issuer URL         | `https://auth.yourdomain.com/application/o/famapp/` |
+| `AUTH_OIDC_CLIENT_ID`     | Yes (prod) | OIDC client ID from Authentik     | —                                                   |
+| `AUTH_OIDC_CLIENT_SECRET` | Yes (prod) | OIDC client secret from Authentik | —                                                   |
+
+## Dev login
+
+Local development only. Never set `ENABLE_DEV_LOGIN=true` in production — a startup assertion in `src/lib/dev-login-config.ts` will crash the container if you do.
+
+| Variable             | Required | Description                                       | Default            |
+| -------------------- | -------- | ------------------------------------------------- | ------------------ |
+| `ENABLE_DEV_LOGIN`   | No       | Show a one-click **Dev login** button on `/login` | `false`            |
+| `DEV_LOGIN_EMAIL`    | No       | Email for the auto-created dev session            | `dev@famapp.local` |
+| `DEV_LOGIN_NAME`     | No       | Display name for the dev user                     | `Dev User`         |
+| `DEV_HOUSEHOLD_NAME` | No       | Household created for the dev user                | `Home`             |
+
+See `docs/dev-login.md` for the full local run procedure.
+
+## Web Push (VAPID)
+
+All three are required together. Generate them once with `pnpm vapid:generate` and copy all three lines into `.env`.
+
+| Variable            | Required | Description                                   |
+| ------------------- | -------- | --------------------------------------------- | ------------------------ |
+| `VAPID_PUBLIC_KEY`  | Yes      | VAPID public key — also passed to the browser |
+| `VAPID_PRIVATE_KEY` | Yes      | VAPID private key — server only               |
+| `VAPID_SUBJECT`     | Yes      | Contact URI for push servers                  | `mailto:you@example.com` |
+
+## ntfy (optional)
+
+Leave both blank to disable the ntfy notification channel. Web Push is the primary channel.
+
+| Variable     | Required | Description              | Example           |
+| ------------ | -------- | ------------------------ | ----------------- |
+| `NTFY_URL`   | No       | ntfy server base URL     | `https://ntfy.sh` |
+| `NTFY_TOPIC` | No       | ntfy topic to publish to | `famapp-alerts`   |
+
+## Logging
+
+| Variable    | Required | Description        | Values                                                      |
+| ----------- | -------- | ------------------ | ----------------------------------------------------------- |
+| `LOG_LEVEL` | No       | Pino log verbosity | `trace`, `debug`, `info`, `warn`, `error` (default: `info`) |
+
+## MinIO object storage
+
+Required when the garden module is enabled. The dev compose stack starts a local MinIO instance automatically via `pnpm dev:local`.
+
+| Variable              | Required | Description                          | Default                 |
+| --------------------- | -------- | ------------------------------------ | ----------------------- |
+| `MINIO_ENDPOINT`      | Yes      | MinIO server base URL                | `http://localhost:9000` |
+| `MINIO_ROOT_USER`     | Yes      | MinIO root access key                | `famapp`                |
+| `MINIO_ROOT_PASSWORD` | Yes      | MinIO root secret key                | `changeme`              |
+| `MINIO_BUCKET`        | No       | Bucket used for garden image uploads | `garden`                |
+
+## OpenPlantBook
+
+Optional. Enables plant species lookup in the garden module. Free account at <https://open.plantbook.io>.
+
+| Variable                      | Required | Description          |
+| ----------------------------- | -------- | -------------------- |
+| `OPENPLANTBOOK_CLIENT_ID`     | No       | OAuth2 client ID     |
+| `OPENPLANTBOOK_CLIENT_SECRET` | No       | OAuth2 client secret |
+
+## Release tooling
+
+Only needed on the machine that cuts releases (`pnpm release`).
+
+| Variable       | Required      | Description                                      |
+| -------------- | ------------- | ------------------------------------------------ |
+| `GITHUB_TOKEN` | Yes (release) | Personal access token — creates a GitHub Release |
+
+## Production-only compose variables
+
+Used by `deploy/compose.example.yaml`. Set in `deploy/.env` on the server — not in the local `.env`.
+
+| Variable                                                            | Description                                                       |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `FAMAPP_IMAGE`                                                      | Docker image tag to deploy (e.g. `ghcr.io/ginnoir/famapp:v0.4.7`) |
+| `FAMAPP_PORT`                                                       | Host port to bind (default: `3000`)                               |
+| `FAMAPP_PULL_POLICY`                                                | Docker pull policy (default: `always`)                            |
+| `FAMAPP_DB_USER` / `FAMAPP_DB_PASSWORD` / `FAMAPP_DB_NAME`          | Postgres credentials for the famapp database                      |
+| `AUTHENTIK_DB_USER` / `AUTHENTIK_DB_PASSWORD` / `AUTHENTIK_DB_NAME` | Postgres credentials for the Authentik database                   |
+| `AUTHENTIK_SECRET_KEY`                                              | Authentik signing key — generate with `openssl rand -base64 60`   |
+| `AUTHENTIK_IMAGE_TAG`                                               | Authentik server image tag (default: `2024.12.3`)                 |
+| `RUN_MIGRATIONS`                                                    | Set `false` to skip auto-migration on start (default: `true`)     |
+
+<!-- END AUTO-GENERATED -->
@@ -0,0 +1,158 @@
+# Runbook
+
+Operational reference for famapp in production. See `deploy/README.md` for the one-time host setup and `docs/tasks/09-pre-deploy-checklist.md` for the pre-deploy checklist.
+
+## Cutting a release
+
+From `main` on the dev machine, with a clean working tree:
+
+```bash
+pnpm release:patch   # or :minor / :major
+# — bumps package.json version
+# — prepends to CHANGELOG.md
+# — creates and pushes a signed git tag (v0.x.y)
+# — creates a GitHub Release with generated notes
+# Requires GITHUB_TOKEN in .env
+```
+
+CI (`release.yml`) then builds and pushes the Docker image to GHCR:
+
+- `ghcr.io/ginnoir/famapp:v0.x.y`
+- `ghcr.io/ginnoir/famapp:0.x` (minor alias)
+- `ghcr.io/ginnoir/famapp:latest`
+
+## Deploying a release
+
+On the home server, in `/srv/famapp/deploy/`:
+
+```bash
+# Pin the new tag
+sed -i 's|FAMAPP_IMAGE=.*|FAMAPP_IMAGE=ghcr.io/ginnoir/famapp:v0.x.y|' .env
+
+# Pull and restart only the app container
+docker compose pull famapp
+docker compose up -d famapp
+
+# Watch the boot log — migrations run before the server starts
+docker compose logs -f famapp
+```
+
+The container entrypoint runs `node scripts/migrate.mjs` automatically. A healthy boot ends with a log line like `ready on http://0.0.0.0:3000`.
+
+## Health check
+
+```bash
+# Container status
+docker compose ps
+
+# App response (200 = healthy)
+curl -sf https://fam.yourdomain.com/ -o /dev/null -w "%{http_code}\n"
+
+# Recent app logs
+docker compose logs --tail=100 famapp
+
+# Database connectivity
+docker compose exec famapp-db pg_isready -U famapp -d famapp
+```
+
+## Rollback
+
+1. Find the previous working tag in `CHANGELOG.md` or `docker images`.
+2. Pin it in `deploy/.env`:
+   ```bash
+   sed -i 's|FAMAPP_IMAGE=.*|FAMAPP_IMAGE=ghcr.io/ginnoir/famapp:v0.x.y|' .env
+   ```
+3. Restart the container:
+   ```bash
+   docker compose up -d famapp
+   ```
+
+If the rollback target predates a migration that has already been applied to the database, restore from backup first — see **Backups** below. To skip auto-migration on a given start (rarely needed):
+
+```bash
+RUN_MIGRATIONS=false docker compose up -d famapp
+```
+
+## Backups
+
+The `famapp-backup` container runs nightly `pg_dump` for both `famapp` and `authentik` databases into the `backups` volume.
+
+```bash
+# Check last backup run
+docker compose logs famapp-backup | tail -20
+
+# List backup files
+docker compose exec famapp-backup ls -lh /backups
+
+# Manual backup now
+docker compose exec famapp-backup sh /scripts/backup.sh
+
+# Restore from a backup file
+docker compose exec famapp-backup sh /scripts/restore.sh famapp_2026-06-01.sql.gz
+```
+
+See `deploy/backups/README.md` for retention policy and full restore details.
+
+## Common issues
+
+### App container exits immediately
+
+```bash
+docker compose logs famapp
+```
+
+Likely causes:
+
+- **Missing required env var** — the app throws on startup if `AUTH_SECRET`, `DATABASE_URL`, or `AUTH_OIDC_*` are absent.
+- **`ENABLE_DEV_LOGIN=true` in production** — `src/lib/dev-login-config.ts` throws an assertion error on import. Remove the variable from the production env.
+- **Database not ready** — Postgres healthcheck should prevent this, but if the DB is slow to start, increase `start_period` in `compose.yaml`.
+
+### Migrations fail on boot
+
+```bash
+docker compose logs famapp | grep -i migration
+```
+
+- Schema is ahead of code: roll back the image or forward-migrate manually.
+- Database unreachable: confirm `famapp-db` is healthy (`docker compose ps`).
+
+### OIDC login fails
+
+1. Confirm `AUTH_OIDC_ISSUER` matches the Authentik provider URL exactly (trailing slash matters).
+2. Confirm the OIDC client redirect URI in Authentik includes `https://fam.yourdomain.com/api/auth/callback/oidc`.
+3. Check Authentik logs: `docker compose logs authentik-server | tail -50`.
+
+### Push notifications not arriving
+
+1. Confirm `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, and `VAPID_SUBJECT` are all set in the production env.
+2. Verify the browser's push subscription is still valid (Settings → notifications → re-enable).
+3. If using ntfy as a secondary channel, confirm `NTFY_URL` and `NTFY_TOPIC` are set.
+
+### MinIO / garden image uploads failing
+
+```bash
+docker compose logs famapp-minio | tail -30
+```
+
+- Confirm `MINIO_ENDPOINT` is `http://famapp-minio:9000` in the compose env (not `localhost`).
+- Confirm the `garden` bucket exists — create it manually via the MinIO console at port `9001` if it is missing.
+
+### Out of disk space
+
+```bash
+df -h /var/lib/docker
+docker system prune --volumes   # removes stopped containers, dangling images, unused volumes
+```
+
+Old backup files accumulate in the `backups` volume. The retention script (`deploy/backups/retain.sh`) runs nightly — check its logs if the volume keeps growing.
+
+## Authentik admin access
+
+The Authentik admin UI is at `https://auth.yourdomain.com`. Log in with the superuser credentials set during bootstrap — see `deploy/authentik/README.md`.
+
+To reset the Authentik admin password from the CLI:
+
+```bash
+docker compose exec authentik-server ak create_recovery_key 1 akadmin
+# prints a one-time recovery URL
+```
@@ -22,4 +22,8 @@ What this costs us, what it buys us.

 ## Index

- (none yet — add as decisions are made)
+<!-- AUTO-GENERATED -->
+
+- [0002 — List realtime uses Postgres NOTIFY and SSE](0002-list-sse-notify.md)
+- [0003 — Release workflow (commitlint + release-it)](0003-release-workflow.md)
+<!-- END AUTO-GENERATED -->
@@ -42,11 +42,11 @@ pnpm dev:local

 The script prints three URLs at startup:

-| URL                        | Use for                                                    |
-| -------------------------- | ---------------------------------------------------------- |
-| `http://localhost:3000`    | Browser on this machine                                    |
-| `http://192.168.1.74:3000` | Phone on the same WiFi (general UI testing)                |
-| `https://dev.ginnoir.com`  | Push notifications + PWA install (needs Caddy — see below) |
+| URL                          | Use for                                                    |
+| ---------------------------- | ---------------------------------------------------------- |
+| `http://localhost:3000`      | Browser on this machine                                    |
+| `http://192.168.x.y:3000`    | Phone on the same WiFi (general UI testing)                |
+| `https://dev.yourdomain.com` | Push notifications + PWA install (needs Caddy — see below) |

 Then open `/login` and click **Dev login**.

@@ -74,11 +74,11 @@ Route through the existing Caddy server on the home server instead — no extra

 **Step 1 — DHCP reservation**

-Set a reservation on the router so the dev machine always gets `192.168.1.74`.
+Set a reservation on the router so the dev machine always gets `192.168.x.y`.

 **Step 2 — DNS record**

-Add a `dev.ginnoir.com` A record pointing to the same public IP as `fam.ginnoir.com`.
+Add a `dev.yourdomain.com` A record pointing to the same public IP as `fam.yourdomain.com`.

 **Step 3 — Windows Firewall**

@@ -97,7 +97,7 @@ Paste `deploy/Caddyfile.dev.snippet` into the home server Caddyfile and reload:
 caddy reload --config /path/to/Caddyfile
 ```

-After this, `https://dev.ginnoir.com` proxies to the dev machine with a real Let's Encrypt cert.
+After this, `https://dev.yourdomain.com` proxies to the dev machine with a real Let's Encrypt cert.

 ## Current Local E2E Procedure

@@ -2,6 +2,10 @@

 Run this before every production deploy (first deploy and each tagged release). Dev-login is intentionally retained behind a double gate; this checklist is what keeps that gate honest.

+## README
+
+- [ ] `README.md` reflects the current module list and any env vars added since the last release.
+
 ## Env hygiene

 - [ ] Server `.env` (next to `deploy/compose.yaml`) does **not** set:
@@ -33,6 +33,7 @@ Every task file has these sections:
 - [06 — Authentik install + OIDC integration](06-authentik-oidc.md)
 - [07 — Household seeding & session](07-household-seed.md)
 - [08 — Theming infrastructure (multi-theme + dark mode)](08-theming.md)
+- [09 — Pre-deploy checklist (recurring)](09-pre-deploy-checklist.md)

 ### Phase 2 — Core modules

@@ -69,3 +70,12 @@ Every task file has these sections:
 - [60 — Postgres backups (pg_dump cron)](60-backups.md)
 - [61 — Rate limiting on share links](61-rate-limit.md)
 - [62 — Structured logging](62-logging.md)
+
+### Phase 8 — Garden module
+
+- [70 — Garden infrastructure (MinIO + upload route + schema)](70-garden-infrastructure.md)
+- [71 — Garden containers](71-garden-containers.md)
+- [72 — Garden plants](72-garden-plants.md)
+- [73 — Garden care tracking](73-garden-care-tracking.md)
+- [74 — Garden integrations](74-garden-integrations.md)
+- [75 — Garden dashboard](75-garden-dashboard.md)
@@ -0,0 +1,13 @@
+CREATE TABLE "bang_events" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"household_id" uuid NOT NULL,
+	"recorded_by" uuid,
+	"occurred_on" text NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "bang_events" ADD CONSTRAINT "bang_events_household_id_households_id_fk" FOREIGN KEY ("household_id") REFERENCES "public"."households"("id") ON DELETE cascade ON UPDATE no action;
+--> statement-breakpoint
+ALTER TABLE "bang_events" ADD CONSTRAINT "bang_events_recorded_by_users_id_fk" FOREIGN KEY ("recorded_by") REFERENCES "public"."users"("id") ON DELETE set null ON UPDATE no action;
+--> statement-breakpoint
+CREATE INDEX "bang_events_household_occurred_idx" ON "bang_events" USING btree ("household_id","occurred_on");
@@ -0,0 +1 @@
+ALTER TABLE "garden_containers" ADD COLUMN "images" jsonb DEFAULT '[]'::jsonb NOT NULL;
@@ -1,6 +1,6 @@
 {
-  "id": "fc208bad-8bfd-452d-876f-7e853f699931",
-  "prevId": "cb06cd57-d5a0-4fb7-bbf3-335173a1168c",
+  "id": "ff1f5ff1-7539-4c5e-a20d-f01c719ef198",
+  "prevId": "fc208bad-8bfd-452d-876f-7e853f699931",
  "version": "7",
  "dialect": "postgresql",
  "tables": {
@@ -120,6 +120,20 @@
      "when": 1748822400000,
      "tag": "0016_garden_improvements",
      "breakpoints": true
+    },
+    {
+      "idx": 17,
+      "version": "7",
+      "when": 1780391596552,
+      "tag": "0017_bang_counter",
+      "breakpoints": true
+    },
+    {
+      "idx": 18,
+      "version": "7",
+      "when": 1748995200000,
+      "tag": "0018_container_images",
+      "breakpoints": true
    }
  ]
 }
@@ -1,6 +1,6 @@
 {
  "name": "famapp",
-  "version": "0.4.4",
+  "version": "0.4.8",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@10.33.3",
@@ -52,6 +52,7 @@
    "@playwright/test": "^1.59.1",
    "@release-it/conventional-changelog": "^11.0.1",
    "@tailwindcss/postcss": "^4.2.4",
+    "@types/canvas-confetti": "^1.9.0",
    "@types/node": "^22.9.0",
    "@types/react": "^19.2.14",
    "@types/react-dom": "^19.2.3",
@@ -79,6 +80,7 @@
    "@fullcalendar/interaction": "^6.1.20",
    "@fullcalendar/react": "^6.1.20",
    "@fullcalendar/timegrid": "^6.1.20",
+    "canvas-confetti": "^1.9.4",
    "class-variance-authority": "^0.7.1",
    "clsx": "^2.1.1",
    "cmdk": "^1.1.1",
@@ -29,6 +29,9 @@ importers:
      '@fullcalendar/timegrid':
        specifier: ^6.1.20
        version: 6.1.20(@fullcalendar/core@6.1.20)
+      canvas-confetti:
+        specifier: ^1.9.4
+        version: 1.9.4
      class-variance-authority:
        specifier: ^0.7.1
        version: 0.7.1
@@ -102,6 +105,9 @@ importers:
      '@tailwindcss/postcss':
        specifier: ^4.2.4
        version: 4.2.4
+      '@types/canvas-confetti':
+        specifier: ^1.9.0
+        version: 1.9.0
      '@types/node':
        specifier: ^22.9.0
        version: 22.19.17
@@ -1844,6 +1850,9 @@ packages:
  '@tybys/wasm-util@0.10.2':
    resolution: {integrity: sha512-RoBvJ2X0wuKlWFIjrwffGw1IqZHKQqzIchKaadZZfnNpsAYp2mM0h36JtPCjNDAHGgYez/15uMBpfGwchhiMgg==}

+  '@types/canvas-confetti@1.9.0':
+    resolution: {integrity: sha512-aBGj/dULrimR1XDZLtG9JwxX1b4HPRF6CX9Yfwh3NvstZEm1ZL7RBnel4keCPSqs1ANRu1u2Aoz9R+VmtjYuTg==}
+
  '@types/estree@1.0.8':
    resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}

@@ -2280,6 +2289,9 @@ packages:
  caniuse-lite@1.0.30001791:
    resolution: {integrity: sha512-yk0l/YSrOnFZk3UROpDLQD9+kC1l4meK/wed583AXrzoarMGJcbRi2Q4RaUYbKxYAsZ8sWmaSa/DsLmdBeI1vQ==}

+  canvas-confetti@1.9.4:
+    resolution: {integrity: sha512-yxQbJkAVrFXWNbTUjPqjF7G+g6pDotOUHGbkZq2NELZUMDpiJ85rIEazVb8GTaAptNW2miJAXbs1BtioA251Pw==}
+
  chalk@4.1.2:
    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
    engines: {node: '>=10'}
@@ -6531,6 +6543,8 @@ snapshots:
      tslib: 2.8.1
    optional: true

+  '@types/canvas-confetti@1.9.0': {}
+
  '@types/estree@1.0.8': {}

  '@types/json-schema@7.0.15': {}
@@ -6977,6 +6991,8 @@ snapshots:

  caniuse-lite@1.0.30001791: {}

+  canvas-confetti@1.9.4: {}
+
  chalk@4.1.2:
    dependencies:
      ansi-styles: 4.3.0
@@ -85,7 +85,7 @@ export async function main() {
  console.log("\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
  console.log(`  Local   → http://localhost:3000`);
  console.log(`  LAN     → http://${lanIp}:3000      (phone on same WiFi)`);
-  console.log(`  HTTPS   → https://dev.ginnoir.com       (push/PWA — needs Caddy snippet)`);
+  console.log(`  HTTPS   → https://dev.<your-domain>     (push/PWA — needs Caddyfile.dev.snippet)`);
  console.log("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");

  // 6. Spawn Next.js dev server bound to all interfaces.
@@ -1,30 +0,0 @@
-import postgres from "postgres";
-import { drizzle } from "drizzle-orm/postgres-js";
-import { households } from "@/modules/_core/schema";
-import { ensureDefaultCalendars } from "@/modules/calendar/server/defaults";
-import { ensureDefaultLists } from "@/modules/lists/server/defaults";
-
-const client = postgres(process.env["DATABASE_URL"]!);
-const db = drizzle(client);
-
-async function seed() {
-  const [existing] = await db.select().from(households).limit(1);
-  if (existing) {
-    console.log(`Household already exists ("${existing.name}"), skipping.`);
-  } else {
-    await db.insert(households).values({ name: "Home" });
-    console.log('Seeded household "Home".');
-  }
-
-  await ensureDefaultCalendars();
-  console.log("Ensured default calendars.");
-  await ensureDefaultLists();
-  console.log("Ensured default lists.");
-  await client.end();
-  process.exit(0);
-}
-
-seed().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
@@ -0,0 +1,27 @@
+"use client";
+
+import { useEffect } from "react";
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    console.error(error);
+  }, [error]);
+
+  return (
+    <div className="flex min-h-screen flex-col items-center justify-center gap-4 p-8">
+      <h2 className="text-xl font-semibold">Something went wrong</h2>
+      <button
+        onClick={reset}
+        className="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}
@@ -1,14 +1,18 @@
 import { notFound } from "next/navigation";
 import { getContainer } from "@/modules/garden/server/queries";
 import { ContainerDetail } from "@/modules/garden/components/container-detail";
+import { getShareLinksForEntity } from "@/modules/_core/share";

 export default async function ContainerPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
-  const container = await getContainer(id);
+  const [container, shareLinks] = await Promise.all([
+    getContainer(id),
+    getShareLinksForEntity("garden.container", id),
+  ]);
  if (!container) notFound();
  return (
    <div className="page-content">
-      <ContainerDetail container={container} />
+      <ContainerDetail container={container} shareLinks={shareLinks} />
    </div>
  );
 }
@@ -2,14 +2,16 @@ import { notFound } from "next/navigation";
 import { listCalendars } from "@/modules/garden/server/calendar-bridge";
 import { getCareLogs, getCareSchedules, getPlant } from "@/modules/garden/server/queries";
 import { PlantDetail } from "@/modules/garden/components/plant-detail";
+import { getShareLinksForEntity } from "@/modules/_core/share";

 export default async function PlantPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
-  const [plant, careLogs, careSchedules, calendars] = await Promise.all([
+  const [plant, careLogs, careSchedules, calendars, shareLinks] = await Promise.all([
    getPlant(id),
    getCareLogs(id),
    getCareSchedules(id),
    listCalendars(),
+    getShareLinksForEntity("garden.plant", id),
  ]);
  if (!plant) notFound();

@@ -20,6 +22,7 @@ export default async function PlantPage({ params }: { params: Promise<{ id: stri
        careLogs={careLogs}
        careSchedules={careSchedules}
        calendars={calendars}
+        shareLinks={shareLinks}
      />
    </div>
  );
@@ -0,0 +1,29 @@
+"use client";
+
+import { useEffect } from "react";
+
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  useEffect(() => {
+    console.error(error);
+  }, [error]);
+
+  return (
+    <html>
+      <body className="flex min-h-screen flex-col items-center justify-center gap-4 p-8">
+        <h2 className="text-xl font-semibold">Something went wrong</h2>
+        <button
+          onClick={reset}
+          className="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground hover:bg-primary/90"
+        >
+          Try again
+        </button>
+      </body>
+    </html>
+  );
+}
@@ -1346,3 +1346,81 @@ select {
    inset 0 1px 2px rgba(0, 0, 0, 0.12),
    0 0 0 2px rgba(244, 239, 229, 0.08);
 }
+
+/* ─── Bang Counter celebration animations ─────────────────────────────────── */
+@keyframes shake {
+  0%,
+  100% {
+    transform: translateX(0);
+  }
+  10% {
+    transform: translateX(-6px) rotate(-1deg);
+  }
+  20% {
+    transform: translateX(6px) rotate(1deg);
+  }
+  30% {
+    transform: translateX(-5px) rotate(-0.8deg);
+  }
+  40% {
+    transform: translateX(5px) rotate(0.8deg);
+  }
+  50% {
+    transform: translateX(-4px) rotate(-0.5deg);
+  }
+  60% {
+    transform: translateX(4px) rotate(0.5deg);
+  }
+  70% {
+    transform: translateX(-2px);
+  }
+  80% {
+    transform: translateX(2px);
+  }
+  90% {
+    transform: translateX(-1px);
+  }
+}
+
+@keyframes countPop {
+  0% {
+    transform: scale(1);
+  }
+  30% {
+    transform: scale(1.45);
+  }
+  60% {
+    transform: scale(0.9);
+  }
+  80% {
+    transform: scale(1.1);
+  }
+  100% {
+    transform: scale(1);
+  }
+}
+
+@keyframes emojiFloat {
+  0% {
+    transform: translateY(0) scale(1);
+    opacity: 1;
+  }
+  50% {
+    transform: translateY(-60px) scale(1.2);
+    opacity: 0.9;
+  }
+  100% {
+    transform: translateY(-120px) scale(0.7);
+    opacity: 0;
+  }
+}
+
+.animate-shake {
+  animation: shake 0.35s ease-in-out both;
+}
+.animate-count-pop {
+  animation: countPop 0.4s cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
+}
+.animate-emoji-float {
+  animation: emojiFloat 1.8s ease-out both;
+}
@@ -19,15 +19,21 @@ export function ShareButton({
  const [open, setOpen] = useState(false);
  const [shareUrl, setShareUrl] = useState<string | null>(null);
  const [copied, setCopied] = useState(false);
+  const [error, setError] = useState<string | null>(null);
  const [isPending, startTransition] = useTransition();

  function share() {
+    setError(null);
    startTransition(async () => {
-      const result = await createShareLink(entityType, entityId, {
-        capabilities: { read: true, write: canWrite },
-      });
-      setShareUrl(result.url);
-      setOpen(true);
+      try {
+        const result = await createShareLink(entityType, entityId, {
+          capabilities: { read: true, write: canWrite },
+        });
+        setShareUrl(result.url);
+        setOpen(true);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to create share link");
+      }
    });
  }

@@ -41,10 +47,13 @@ export function ShareButton({

  return (
    <>
-      <Button variant="outline" onClick={share} disabled={isPending}>
-        <Link />
-        Share
-      </Button>
+      <div className="flex flex-col items-end gap-1">
+        <Button variant="outline" onClick={share} disabled={isPending}>
+          <Link />
+          Share
+        </Button>
+        {error && <p className="text-xs text-red-500">{error}</p>}
+      </div>

      <Dialog open={open} onOpenChange={setOpen}>
        <DialogContent>
@@ -0,0 +1,53 @@
+"use client";
+
+import { useTransition } from "react";
+import { useRouter } from "next/navigation";
+import { revokeShareLink } from "@/modules/_core/share";
+import type { EntityShareLink } from "@/modules/_core/share";
+
+type Props = {
+  links: EntityShareLink[];
+};
+
+export function ShareLinkList({ links }: Props) {
+  const [isPending, startTransition] = useTransition();
+  const router = useRouter();
+
+  if (links.length === 0) return null;
+
+  function handleRevoke(id: string) {
+    startTransition(async () => {
+      await revokeShareLink(id);
+      router.refresh();
+    });
+  }
+
+  return (
+    <div className="flex flex-col gap-1 pt-1 border-t border-[var(--ink-faint)]">
+      <p className="text-xs font-semibold uppercase text-[var(--ink-mute)] tracking-wide">
+        Active share links ({links.length})
+      </p>
+      {links.map((link) => (
+        <div key={link.id} className="flex items-center justify-between gap-2 text-sm py-0.5">
+          <div className="flex flex-col">
+            <span className="text-[var(--ink-mute)]">
+              Created {new Date(link.createdAt).toLocaleDateString()}
+            </span>
+            {link.expiresAt && (
+              <span className="text-xs text-[var(--ink-mute)]">
+                Expires {new Date(link.expiresAt).toLocaleDateString()}
+              </span>
+            )}
+          </div>
+          <button
+            className="btn btn-ghost btn-sm text-red-500 hover:text-red-600"
+            onClick={() => handleRevoke(link.id)}
+            disabled={isPending}
+          >
+            Revoke
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}
@@ -100,6 +100,48 @@ export async function revokeShareLink(id: string): Promise<void> {

 export type ActiveShareLink = typeof shareLinks.$inferSelect;

+export type EntityShareLink = {
+  id: string;
+  createdAt: string;
+  expiresAt: string | null;
+  capabilities: ShareLinkCapabilities;
+};
+
+export async function getShareLinksForEntity(
+  entityType: string,
+  entityId: string,
+): Promise<EntityShareLink[]> {
+  const { household } = await getCurrentSession();
+  const now = new Date();
+
+  const rows = await db
+    .select({
+      id: shareLinks.id,
+      createdAt: shareLinks.createdAt,
+      expiresAt: shareLinks.expiresAt,
+      capabilities: shareLinks.capabilities,
+    })
+    .from(shareLinks)
+    .where(
+      and(
+        eq(shareLinks.householdId, household.id),
+        eq(shareLinks.entityType, entityType),
+        eq(shareLinks.entityId, entityId),
+        isNull(shareLinks.revokedAt),
+      ),
+    )
+    .orderBy(shareLinks.createdAt);
+
+  return rows
+    .filter((r) => !r.expiresAt || r.expiresAt > now)
+    .map((r) => ({
+      id: r.id,
+      createdAt: r.createdAt.toISOString(),
+      expiresAt: r.expiresAt?.toISOString() ?? null,
+      capabilities: r.capabilities,
+    }));
+}
+
 export async function getActiveShareLinks(): Promise<ActiveShareLink[]> {
  const { household } = await getCurrentSession();
  const now = new Date();
@@ -0,0 +1,332 @@
+"use client";
+
+import { useState, useTransition, useRef, useCallback } from "react";
+import { createPortal } from "react-dom";
+import confetti from "canvas-confetti";
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@/components/ui/dialog";
+import type { BangStatsDto } from "../server/queries";
+import { addBang } from "../server/actions";
+
+// ─── Celebration engine ───────────────────────────────────────────────────────
+
+function launchFirework(originX: number, originY: number) {
+  confetti({
+    particleCount: 80,
+    startVelocity: 45,
+    spread: 360,
+    origin: { x: originX, y: originY },
+    colors: ["#ff0", "#f0f", "#0ff", "#f60", "#0f6", "#06f"],
+    shapes: ["circle", "square"],
+    gravity: 0.8,
+    scalar: 1.2,
+    ticks: 200,
+  });
+}
+
+function launchSideCannon(side: "left" | "right") {
+  confetti({
+    particleCount: 120,
+    angle: side === "left" ? 60 : 120,
+    spread: 55,
+    origin: { x: side === "left" ? 0 : 1, y: 0.65 },
+    colors: ["#ff4e50", "#fc913a", "#f9d423", "#ede574", "#e1f5c4"],
+    shapes: ["circle", "square", "star"],
+    scalar: 1.1,
+    ticks: 300,
+  });
+}
+
+function launchStarBurst() {
+  const defaults = {
+    spread: 360,
+    ticks: 100,
+    gravity: 0,
+    decay: 0.94,
+    startVelocity: 30,
+    shapes: ["star"] as confetti.Shape[],
+    colors: ["FFE400", "FFBD00", "E89400", "FFCA6C", "FDFFB8"],
+  };
+  function shoot() {
+    confetti({ ...defaults, particleCount: 40, scalar: 1.2, shapes: ["star"] });
+    confetti({ ...defaults, particleCount: 15, scalar: 0.75, shapes: ["circle"] });
+  }
+  shoot();
+  setTimeout(shoot, 100);
+  setTimeout(shoot, 200);
+}
+
+function synthFireworkSound() {
+  try {
+    const ctx = new AudioContext();
+    // Rising "pew" tone
+    const osc = ctx.createOscillator();
+    const gain = ctx.createGain();
+    osc.connect(gain);
+    gain.connect(ctx.destination);
+    osc.frequency.setValueAtTime(200, ctx.currentTime);
+    osc.frequency.exponentialRampToValueAtTime(900, ctx.currentTime + 0.12);
+    gain.gain.setValueAtTime(0.35, ctx.currentTime);
+    gain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.18);
+    osc.start(ctx.currentTime);
+    osc.stop(ctx.currentTime + 0.18);
+
+    // Noise "boom"
+    const bufferSize = ctx.sampleRate * 0.4;
+    const buffer = ctx.createBuffer(1, bufferSize, ctx.sampleRate);
+    const data = buffer.getChannelData(0);
+    for (let i = 0; i < bufferSize; i++) data[i] = Math.random() * 2 - 1;
+    const noise = ctx.createBufferSource();
+    noise.buffer = buffer;
+    const noiseGain = ctx.createGain();
+    const bpFilter = ctx.createBiquadFilter();
+    bpFilter.type = "bandpass";
+    bpFilter.frequency.value = 150;
+    noise.connect(bpFilter);
+    bpFilter.connect(noiseGain);
+    noiseGain.connect(ctx.destination);
+    noiseGain.gain.setValueAtTime(0.6, ctx.currentTime + 0.15);
+    noiseGain.gain.exponentialRampToValueAtTime(0.001, ctx.currentTime + 0.6);
+    noise.start(ctx.currentTime + 0.15);
+    noise.stop(ctx.currentTime + 0.6);
+  } catch {
+    // Autoplay policy blocked — silently skip
+  }
+}
+
+type EmojiParticle = {
+  id: number;
+  emoji: string;
+  x: number;
+  y: number;
+  size: number;
+  delay: number;
+};
+
+const CELEBRATION_EMOJIS = [
+  "💥",
+  "🎉",
+  "🔥",
+  "✨",
+  "🎊",
+  "🥳",
+  "💦",
+  "😈",
+  "🎆",
+  "⭐",
+  "🍆",
+  "💫",
+  "🌟",
+  "🎇",
+  "🍒",
+];
+
+function EmojiOverlay({ particles }: { particles: EmojiParticle[] }) {
+  if (particles.length === 0) return null;
+  return createPortal(
+    <div className="pointer-events-none fixed inset-0 z-[9999] overflow-hidden" aria-hidden>
+      {particles.map((p) => (
+        <span
+          key={p.id}
+          className="absolute select-none animate-emoji-float"
+          style={{
+            left: `${p.x}%`,
+            top: `${p.y}%`,
+            fontSize: `${p.size}rem`,
+            animationDelay: `${p.delay}ms`,
+          }}
+        >
+          {p.emoji}
+        </span>
+      ))}
+    </div>,
+    document.body,
+  );
+}
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+type Props = {
+  stats: BangStatsDto;
+  maxRecentBangs: number;
+};
+
+export function BangWidget({ stats, maxRecentBangs }: Props) {
+  const [open, setOpen] = useState(false);
+  const [dateValue, setDateValue] = useState(todayValue());
+  const [isPending, startTransition] = useTransition();
+  const [error, setError] = useState<string | null>(null);
+  const [emojiParticles, setEmojiParticles] = useState<EmojiParticle[]>([]);
+  const [countPop, setCountPop] = useState(false);
+  const [shake, setShake] = useState(false);
+  const [flash, setFlash] = useState(false);
+  const particleIdRef = useRef(0);
+
+  const spawnEmojis = useCallback(() => {
+    const batch: EmojiParticle[] = Array.from({ length: 50 }, () => ({
+      id: ++particleIdRef.current,
+      emoji: CELEBRATION_EMOJIS[Math.floor(Math.random() * CELEBRATION_EMOJIS.length)]!,
+      x: Math.random() * 100,
+      y: 20 + Math.random() * 70, // keep out of very top/bottom edges so float-up is visible
+      size: 1.5 + Math.random() * 2,
+      delay: Math.random() * 600, // stagger spawning over 600ms so it feels like a cascade
+    }));
+    setEmojiParticles((prev) => [...prev, ...batch]);
+    setTimeout(() => {
+      const ids = new Set(batch.map((p) => p.id));
+      setEmojiParticles((prev) => prev.filter((p) => !ids.has(p.id)));
+    }, 2400);
+  }, []);
+
+  const triggerCelebration = useCallback(() => {
+    setFlash(true);
+    setTimeout(() => setFlash(false), 120);
+
+    setShake(true);
+    setTimeout(() => setShake(false), 350);
+
+    setCountPop(true);
+    setTimeout(() => setCountPop(false), 400);
+
+    synthFireworkSound();
+    spawnEmojis();
+    launchStarBurst();
+
+    launchSideCannon("left");
+    setTimeout(() => launchSideCannon("right"), 150);
+
+    setTimeout(() => launchFirework(0.3, 0.7), 200);
+    setTimeout(() => launchFirework(0.7, 0.65), 450);
+    setTimeout(() => launchFirework(0.5, 0.6), 700);
+    setTimeout(() => launchFirework(0.2, 0.75), 950);
+    setTimeout(() => launchFirework(0.8, 0.7), 1100);
+    setTimeout(() => {
+      launchSideCannon("left");
+      launchSideCannon("right");
+    }, 1300);
+    setTimeout(() => launchFirework(0.5, 0.5), 1600);
+  }, [spawnEmojis]);
+
+  function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    startTransition(async () => {
+      try {
+        await addBang({ occurredOn: dateValue });
+        setOpen(false);
+        triggerCelebration();
+      } catch {
+        setError("Something went wrong. Try again.");
+      }
+    });
+  }
+
+  return (
+    <div className={`relative flex flex-col gap-3 overflow-hidden ${shake ? "animate-shake" : ""}`}>
+      {flash && (
+        <div className="pointer-events-none absolute inset-0 z-20 rounded-xl bg-white/70" />
+      )}
+
+      <EmojiOverlay particles={emojiParticles} />
+
+      <div className="flex items-center justify-between">
+        <div className="flex flex-col">
+          <span
+            className={`text-5xl font-bold leading-none tabular-nums ${countPop ? "animate-count-pop" : ""}`}
+          >
+            {stats.total}
+          </span>
+          <span className="text-xs text-[var(--ink-mute)] mt-1">
+            {stats.total === 1 ? "bang" : "bangs"}
+          </span>
+        </div>
+
+        <Dialog open={open} onOpenChange={setOpen}>
+          <DialogTrigger
+            render={
+              <button
+                type="button"
+                className="btn btn-primary flex items-center gap-1.5 text-sm px-3 py-1.5"
+              />
+            }
+          >
+            <span aria-hidden>💥</span> Add Bang
+          </DialogTrigger>
+          <DialogContent>
+            <DialogHeader>
+              <DialogTitle>Record a bang</DialogTitle>
+            </DialogHeader>
+            <form id="bang-form" onSubmit={handleSubmit} className="flex flex-col gap-3 pt-1">
+              <div className="flex flex-col gap-1">
+                <label htmlFor="bang-date" className="text-sm font-medium">
+                  Date
+                </label>
+                <input
+                  id="bang-date"
+                  type="date"
+                  value={dateValue}
+                  onChange={(e) => setDateValue(e.target.value)}
+                  className="input input-sm"
+                  required
+                />
+                <p className="text-xs text-[var(--ink-mute)]">
+                  Change if you&apos;re documenting a bang from a previous day.
+                </p>
+              </div>
+              {error && <p className="text-sm text-red-500">{error}</p>}
+            </form>
+            <DialogFooter showCloseButton>
+              <button
+                type="submit"
+                form="bang-form"
+                disabled={isPending}
+                className="btn btn-primary btn-sm"
+              >
+                {isPending ? "Recording…" : "🎆 Record it"}
+              </button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      </div>
+
+      {stats.recent.length > 0 && (
+        <div className="flex flex-col gap-0.5 border-t border-[var(--surface-3)] pt-2">
+          <p className="text-xs font-medium text-[var(--ink-mute)] mb-1">
+            Last {Math.min(stats.recent.length, maxRecentBangs)}
+          </p>
+          {stats.recent.map((bang) => (
+            <div key={bang.id} className="flex items-center justify-between gap-2 py-0.5">
+              <span className="text-sm">{formatBangDate(bang.occurredOn)}</span>
+              {bang.recordedByName && (
+                <span className="max-w-[40%] truncate text-xs text-[var(--ink-mute)]">
+                  {bang.recordedByName}
+                </span>
+              )}
+            </div>
+          ))}
+        </div>
+      )}
+
+      {stats.total === 0 && (
+        <p className="text-sm text-[var(--ink-mute)]">No bangs yet. Add the first one!</p>
+      )}
+    </div>
+  );
+}
+
+function todayValue(): string {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+function formatBangDate(iso: string): string {
+  const [year, month, day] = iso.split("-").map(Number);
+  const d = new Date(year!, month! - 1, day!);
+  return d.toLocaleDateString(undefined, { month: "short", day: "numeric", year: "numeric" });
+}
@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { ModuleManifest, WidgetContext } from "../_core/module";
+import { getBangStats } from "./server/queries";
+import { BangWidget } from "./components/bang-widget";
+
+const bangWidgetConfigSchema = z.object({
+  maxRecentBangs: z.number().int().min(1).max(20).default(5),
+});
+
+async function BangWidgetServer({ config, ctx }: { config: unknown; ctx: WidgetContext }) {
+  const parsed = bangWidgetConfigSchema.parse(config);
+  const stats = await getBangStats(ctx.householdId, parsed.maxRecentBangs);
+  return <BangWidget stats={stats} maxRecentBangs={parsed.maxRecentBangs} />;
+}
+
+const bangsManifest: ModuleManifest = {
+  id: "bangs",
+  name: "Bangs",
+  entities: [
+    {
+      type: "bangs.event",
+      label: { singular: "Bang", plural: "Bangs" },
+      resolveUrl: () => "/",
+      renderActivity: (entry) => {
+        const date = entry.payload?.occurredOn as string | undefined;
+        return date ? `Recorded a bang on ${date}` : "Recorded a bang";
+      },
+    },
+  ],
+  dashboardWidgets: [
+    {
+      id: "bangs.counter",
+      title: "Bang Counter",
+      description: "Track and celebrate bangs with your household.",
+      category: "Fun",
+      defaultSize: { w: 3, h: 3 },
+      minSize: { w: 2, h: 2 },
+      defaultPriority: 60,
+      configSchema: bangWidgetConfigSchema,
+      defaultConfig: { maxRecentBangs: 5 },
+      render: (props) => <BangWidgetServer {...props} />,
+    },
+  ],
+};
+
+export default bangsManifest;
@@ -0,0 +1,18 @@
+import { index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { households, users } from "../_core/schema";
+
+export const bangEvents = pgTable(
+  "bang_events",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    householdId: uuid("household_id")
+      .notNull()
+      .references(() => households.id, { onDelete: "cascade" }),
+    recordedBy: uuid("recorded_by").references(() => users.id, { onDelete: "set null" }),
+    occurredOn: text("occurred_on").notNull(), // YYYY-MM-DD, text to avoid timezone confusion
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [index("bang_events_household_occurred_idx").on(t.householdId, t.occurredOn)],
+);
+
+export type BangEvent = typeof bangEvents.$inferSelect;
@@ -0,0 +1,50 @@
+"use server";
+
+import { revalidatePath } from "next/cache";
+import { z } from "zod";
+import { db } from "@/lib/db";
+import { getCurrentSession } from "@/lib/session";
+import { logActivity } from "@/modules/_core/activity";
+import { bangEvents } from "../schema";
+
+const addBangInput = z.object({
+  occurredOn: z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, "Must be YYYY-MM-DD")
+    .optional(),
+});
+
+function todayString(): string {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+export async function addBang(input: z.input<typeof addBangInput> = {}) {
+  const parsed = addBangInput.parse(input);
+  const { user, household } = await getCurrentSession();
+
+  const occurredOn = parsed.occurredOn ?? todayString();
+
+  const [bang] = await db
+    .insert(bangEvents)
+    .values({
+      householdId: household.id,
+      recordedBy: user.id,
+      occurredOn,
+    })
+    .returning();
+
+  if (!bang) throw new Error("Bang was not recorded");
+
+  await logActivity({
+    entityType: "bangs.event",
+    entityId: bang.id,
+    action: "create",
+    payload: { occurredOn },
+  });
+
+  revalidatePath("/");
+  revalidatePath("/d/[slug]", "page");
+
+  return bang;
+}
@@ -0,0 +1,39 @@
+import { count, desc, eq } from "drizzle-orm";
+import { db } from "@/lib/db";
+import { users } from "@/modules/_core/schema";
+import { bangEvents } from "../schema";
+
+export type BangStatsDto = {
+  total: number;
+  recent: RecentBangDto[];
+};
+
+export type RecentBangDto = {
+  id: string;
+  occurredOn: string;
+  recordedByName: string | null;
+};
+
+export async function getBangStats(householdId: string, limit: number): Promise<BangStatsDto> {
+  const [totalRow] = await db
+    .select({ total: count() })
+    .from(bangEvents)
+    .where(eq(bangEvents.householdId, householdId));
+
+  const recent = await db
+    .select({
+      id: bangEvents.id,
+      occurredOn: bangEvents.occurredOn,
+      recordedByName: users.name,
+    })
+    .from(bangEvents)
+    .leftJoin(users, eq(bangEvents.recordedBy, users.id))
+    .where(eq(bangEvents.householdId, householdId))
+    .orderBy(desc(bangEvents.occurredOn), desc(bangEvents.createdAt))
+    .limit(limit);
+
+  return {
+    total: totalRow?.total ?? 0,
+    recent,
+  };
+}
@@ -2,16 +2,32 @@

 import { useState, useTransition } from "react";
 import { useRouter } from "next/navigation";
-import { deleteContainer } from "../server/actions";
+import { ShareButton } from "@/components/share-button";
+import { ShareLinkList } from "@/components/share-link-list";
+import type { EntityShareLink } from "@/modules/_core/share";
+import {
+  addContainerImage,
+  deleteContainer,
+  removeContainerImage,
+  setContainerPrimaryImage,
+} from "../server/actions";
 import { ContainerForm } from "./container-form";
 import type { ContainerDetailDto } from "../server/queries";

-type Props = { container: ContainerDetailDto };
+type Tab = "info" | "gallery";

-export function ContainerDetail({ container }: Props) {
+type Props = {
+  container: ContainerDetailDto;
+  shareLinks: EntityShareLink[];
+};
+
+export function ContainerDetail({ container, shareLinks }: Props) {
+  const [tab, setTab] = useState<Tab>("info");
  const [editing, setEditing] = useState(false);
  const [confirming, setConfirming] = useState(false);
  const [isPending, startTransition] = useTransition();
+  const [galleryError, setGalleryError] = useState<string | null>(null);
+  const [uploadingImage, setUploadingImage] = useState(false);
  const router = useRouter();

  function handleDelete() {
@@ -22,6 +38,41 @@ export function ContainerDetail({ container }: Props) {
    });
  }

+  async function handleImageUpload(e: React.ChangeEvent<HTMLInputElement>) {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    setGalleryError(null);
+    setUploadingImage(true);
+    try {
+      const fd = new FormData();
+      fd.append("file", file);
+      const res = await fetch("/api/uploads", { method: "POST", body: fd });
+      if (!res.ok) throw new Error("Upload failed");
+      const data = (await res.json()) as { url: string };
+      await addContainerImage({ id: container.id, url: data.url });
+      router.refresh();
+    } catch {
+      setGalleryError("Image upload failed.");
+    } finally {
+      setUploadingImage(false);
+      e.target.value = "";
+    }
+  }
+
+  function handleRemoveImage(url: string) {
+    startTransition(async () => {
+      await removeContainerImage({ id: container.id, url });
+      router.refresh();
+    });
+  }
+
+  function handleSetPrimary(url: string) {
+    startTransition(async () => {
+      await setContainerPrimaryImage({ id: container.id, url });
+      router.refresh();
+    });
+  }
+
  return (
    <div className="flex flex-col gap-6">
      {container.coverImageUrl && (
@@ -38,28 +89,36 @@ export function ContainerDetail({ container }: Props) {
          <p className="text-sm text-[var(--ink-mute)] capitalize mt-1">{container.type}</p>
          {container.locationNotes && <p className="text-sm mt-2">{container.locationNotes}</p>}
        </div>
-        <div className="flex gap-2 shrink-0">
-          <button className="btn btn-ghost btn-sm" onClick={() => setEditing(true)}>
-            Edit
-          </button>
-          {confirming ? (
-            <div className="flex gap-1">
-              <button className="btn btn-danger btn-sm" onClick={handleDelete} disabled={isPending}>
-                Confirm
-              </button>
-              <button
-                className="btn btn-ghost btn-sm"
-                onClick={() => setConfirming(false)}
-                disabled={isPending}
-              >
-                Cancel
-              </button>
-            </div>
-          ) : (
-            <button className="btn btn-ghost btn-sm" onClick={() => setConfirming(true)}>
-              Delete
+        <div className="flex flex-col items-end gap-2 shrink-0">
+          <div className="flex gap-2">
+            <ShareButton entityType="garden.container" entityId={container.id} />
+            <button className="btn btn-ghost btn-sm" onClick={() => setEditing((v) => !v)}>
+              Edit
            </button>
-          )}
+            {confirming ? (
+              <div className="flex gap-1">
+                <button
+                  className="btn btn-danger btn-sm"
+                  onClick={handleDelete}
+                  disabled={isPending}
+                >
+                  Confirm
+                </button>
+                <button
+                  className="btn btn-ghost btn-sm"
+                  onClick={() => setConfirming(false)}
+                  disabled={isPending}
+                >
+                  Cancel
+                </button>
+              </div>
+            ) : (
+              <button className="btn btn-ghost btn-sm" onClick={() => setConfirming(true)}>
+                Delete
+              </button>
+            )}
+          </div>
+          <ShareLinkList links={shareLinks} />
        </div>
      </div>

@@ -77,51 +136,131 @@ export function ContainerDetail({ container }: Props) {
        </div>
      )}

-      <div>
-        <div className="flex items-center justify-between mb-3">
-          <h2 className="text-lg font-semibold">Plants ({container.plantCount})</h2>
-          <a
-            href={`/garden/plants/new?containerId=${container.id}`}
-            className="btn btn-ghost btn-sm"
+      {/* Tabs */}
+      <div className="flex gap-6 border-b border-[var(--ink-faint)]">
+        {(["info", "gallery"] as Tab[]).map((t) => (
+          <button
+            key={t}
+            onClick={() => setTab(t)}
+            className={`pb-2 text-sm font-medium capitalize transition-colors ${
+              tab === t
+                ? "border-b-2 border-[var(--ink)] text-[var(--ink)]"
+                : "text-[var(--ink-mute)] hover:text-[var(--ink)]"
+            }`}
          >
-            + Add plant
-          </a>
-        </div>
-        {container.plants.length === 0 ? (
-          <p className="text-sm text-[var(--ink-mute)]">No plants in this container yet.</p>
-        ) : (
-          <div className="grid gap-2 sm:grid-cols-2">
-            {container.plants.map((p) => (
-              <a
-                key={p.id}
-                href={`/garden/plants/${p.id}`}
-                className="card p-3 hover:bg-[var(--surface-2)] transition-colors"
-              >
-                <div className="flex items-center gap-3">
-                  {p.primaryImageUrl && (
-                    <img
-                      src={p.primaryImageUrl}
-                      alt=""
-                      className="w-10 h-10 rounded-full object-cover shrink-0"
-                    />
-                  )}
-                  <div>
-                    <p className="font-medium text-sm">{p.name}</p>
-                    {p.scientificName && (
-                      <p className="text-xs text-[var(--ink-mute)] italic">{p.scientificName}</p>
-                    )}
-                  </div>
-                  <span
-                    className={`ml-auto text-xs badge ${p.healthStatus === "healthy" ? "badge-success" : "badge-warning"}`}
-                  >
-                    {p.healthStatus}
-                  </span>
-                </div>
-              </a>
-            ))}
-          </div>
-        )}
+            {t}
+          </button>
+        ))}
      </div>
+
+      {/* Info */}
+      {tab === "info" && (
+        <div>
+          <div className="flex items-center justify-between mb-3">
+            <h2 className="text-lg font-semibold">Plants ({container.plantCount})</h2>
+            <a
+              href={`/garden/plants/new?containerId=${container.id}`}
+              className="btn btn-ghost btn-sm"
+            >
+              + Add plant
+            </a>
+          </div>
+          {container.plants.length === 0 ? (
+            <p className="text-sm text-[var(--ink-mute)]">No plants in this container yet.</p>
+          ) : (
+            <div className="grid gap-2 sm:grid-cols-2">
+              {container.plants.map((p) => (
+                <a
+                  key={p.id}
+                  href={`/garden/plants/${p.id}`}
+                  className="card p-3 hover:bg-[var(--surface-2)] transition-colors"
+                >
+                  <div className="flex items-center gap-3">
+                    {p.primaryImageUrl && (
+                      <img
+                        src={p.primaryImageUrl}
+                        alt=""
+                        className="w-10 h-10 rounded-full object-cover shrink-0"
+                      />
+                    )}
+                    <div>
+                      <p className="font-medium text-sm">{p.name}</p>
+                      {p.scientificName && (
+                        <p className="text-xs text-[var(--ink-mute)] italic">{p.scientificName}</p>
+                      )}
+                    </div>
+                    <span
+                      className={`ml-auto text-xs badge ${p.healthStatus === "healthy" ? "badge-success" : "badge-warning"}`}
+                    >
+                      {p.healthStatus}
+                    </span>
+                  </div>
+                </a>
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Gallery */}
+      {tab === "gallery" && (
+        <div className="flex flex-col gap-4">
+          {container.images.length === 0 ? (
+            <p className="text-sm text-[var(--ink-mute)]">No photos yet.</p>
+          ) : (
+            <div className="grid grid-cols-3 gap-2">
+              {container.images.map((url) => (
+                <div key={url} className="relative group">
+                  <img src={url} alt="" className="w-full aspect-square object-cover rounded-lg" />
+                  <div className="absolute inset-0 bg-black/40 opacity-0 group-hover:opacity-100 rounded-lg flex items-center justify-center gap-3 transition-opacity">
+                    <button
+                      onClick={() => handleSetPrimary(url)}
+                      disabled={isPending}
+                      title="Set as cover"
+                      className={`text-lg leading-none ${url === container.coverImageUrl ? "text-yellow-400" : "text-white"}`}
+                    >
+                      ★
+                    </button>
+                    <button
+                      onClick={() => handleRemoveImage(url)}
+                      disabled={isPending}
+                      title="Remove"
+                      className="text-white text-lg leading-none"
+                    >
+                      ✕
+                    </button>
+                  </div>
+                  {url === container.coverImageUrl && (
+                    <span className="absolute top-1 left-1 text-xs px-1 bg-black/60 text-yellow-300 rounded">
+                      Cover
+                    </span>
+                  )}
+                </div>
+              ))}
+            </div>
+          )}
+
+          {galleryError && <p className="text-sm text-red-500">{galleryError}</p>}
+
+          <div className="flex items-center gap-3">
+            {container.images.length < 10 && (
+              <label className="btn btn-ghost btn-sm cursor-pointer">
+                {uploadingImage ? "Uploading…" : "Upload photo"}
+                <input
+                  type="file"
+                  accept="image/*"
+                  className="hidden"
+                  onChange={handleImageUpload}
+                  disabled={uploadingImage}
+                />
+              </label>
+            )}
+            <span className="text-xs text-[var(--ink-mute)]">
+              {container.images.length}/10 photos
+            </span>
+          </div>
+        </div>
+      )}
    </div>
  );
 }
@@ -6,6 +6,9 @@ import { useRouter } from "next/navigation";
 import { deletePlant, addPlantImage, removePlantImage, setPrimaryImage } from "../server/actions";
 import type { CalendarDto } from "../server/calendar-bridge";
 import type { CareLogDto, CareScheduleDto, PlantDetailDto } from "../server/queries";
+import { ShareButton } from "@/components/share-button";
+import { ShareLinkList } from "@/components/share-link-list";
+import type { EntityShareLink } from "@/modules/_core/share";
 import { CareHistoryList } from "./care-history-list";
 import { CareLogForm } from "./care-log-form";
 import { CareScheduleEditor } from "./care-schedule-editor";
@@ -17,6 +20,7 @@ type Props = {
  careLogs: CareLogDto[];
  careSchedules: CareScheduleDto[];
  calendars: CalendarDto[];
+  shareLinks: EntityShareLink[];
 };

 function InfoRow({
@@ -43,7 +47,7 @@ function healthBadgeClass(status: string): string {
  return "badge-warning";
 }

-export function PlantDetail({ plant, careLogs, careSchedules, calendars }: Props) {
+export function PlantDetail({ plant, careLogs, careSchedules, calendars, shareLinks }: Props) {
  const [tab, setTab] = useState<Tab>("info");
  const [confirming, setConfirming] = useState(false);
  const [isPending, startTransition] = useTransition();
@@ -122,28 +126,36 @@ export function PlantDetail({ plant, careLogs, careSchedules, calendars }: Props
          </div>
        </div>

-        <div className="flex gap-2 shrink-0">
-          <Link href={`/garden/plants/${plant.id}/edit`} className="btn btn-ghost btn-sm">
-            Edit
-          </Link>
-          {confirming ? (
-            <div className="flex gap-1">
-              <button className="btn btn-danger btn-sm" onClick={handleDelete} disabled={isPending}>
-                Confirm
+        <div className="flex flex-col items-end gap-2 shrink-0">
+          <div className="flex gap-2">
+            <ShareButton entityType="garden.plant" entityId={plant.id} />
+            <Link href={`/garden/plants/${plant.id}/edit`} className="btn btn-ghost btn-sm">
+              Edit
+            </Link>
+            {confirming ? (
+              <div className="flex gap-1">
+                <button
+                  className="btn btn-danger btn-sm"
+                  onClick={handleDelete}
+                  disabled={isPending}
+                >
+                  Confirm
+                </button>
+                <button
+                  className="btn btn-ghost btn-sm"
+                  onClick={() => setConfirming(false)}
+                  disabled={isPending}
+                >
+                  Cancel
+                </button>
+              </div>
+            ) : (
+              <button className="btn btn-ghost btn-sm" onClick={() => setConfirming(true)}>
+                Delete
              </button>
-              <button
-                className="btn btn-ghost btn-sm"
-                onClick={() => setConfirming(false)}
-                disabled={isPending}
-              >
-                Cancel
-              </button>
-            </div>
-          ) : (
-            <button className="btn btn-ghost btn-sm" onClick={() => setConfirming(true)}>
-              Delete
-            </button>
-          )}
+            )}
+          </div>
+          <ShareLinkList links={shareLinks} />
        </div>
      </div>

@@ -114,9 +114,28 @@ const gardenManifest: ModuleManifest = {
        const d = data as ContainerShareData;
        return (
          <div className="flex flex-col gap-3">
+            {d.coverImageUrl && (
+              <img
+                src={d.coverImageUrl}
+                alt=""
+                className="w-full max-h-48 object-cover rounded-lg"
+              />
+            )}
            <h2 className="text-xl font-bold">{d.name}</h2>
            <p className="text-sm capitalize text-[var(--ink-mute)]">{d.type}</p>
            {d.locationNotes && <p className="text-sm">{d.locationNotes}</p>}
+            {d.images.length > 1 && (
+              <div className="grid grid-cols-3 gap-2 mt-1">
+                {d.images.slice(1).map((url) => (
+                  <img
+                    key={url}
+                    src={url}
+                    alt=""
+                    className="w-full aspect-square object-cover rounded"
+                  />
+                ))}
+              </div>
+            )}
            {d.plants.length > 0 && (
              <div>
                <p className="text-sm font-medium mb-1">Plants</p>
@@ -23,6 +23,7 @@ export const gardenContainers = pgTable(
    type: text("type").notNull().default("other"),
    locationNotes: text("location_notes"),
    coverImageUrl: text("cover_image_url"),
+    images: jsonb("images").notNull().default([]).$type<string[]>(),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
  },
@@ -93,6 +93,80 @@ export async function deleteContainer(input: { id: string }) {
  revalidatePath("/garden");
 }

+export async function addContainerImage(input: { id: string; url: string }) {
+  const parsed = z.object({ id: z.string().uuid(), url: z.string().min(1) }).parse(input);
+  const { household } = await getCurrentSession();
+  await assertCanAccessContainer(parsed.id, household.id);
+
+  const [row] = await db
+    .select({ images: gardenContainers.images, coverImageUrl: gardenContainers.coverImageUrl })
+    .from(gardenContainers)
+    .where(eq(gardenContainers.id, parsed.id))
+    .limit(1);
+
+  if (!row) throw new Error("Container not found");
+  if (row.images.length >= 10) throw new Error("Maximum 10 images allowed");
+
+  const newImages = [...row.images, parsed.url];
+  await db
+    .update(gardenContainers)
+    .set({
+      images: newImages,
+      coverImageUrl: row.images.length === 0 ? parsed.url : row.coverImageUrl,
+      updatedAt: new Date(),
+    })
+    .where(eq(gardenContainers.id, parsed.id));
+
+  revalidatePath(`/garden/containers/${parsed.id}`);
+}
+
+export async function removeContainerImage(input: { id: string; url: string }) {
+  const parsed = z.object({ id: z.string().uuid(), url: z.string() }).parse(input);
+  const { household } = await getCurrentSession();
+  await assertCanAccessContainer(parsed.id, household.id);
+
+  const [row] = await db
+    .select({ images: gardenContainers.images, coverImageUrl: gardenContainers.coverImageUrl })
+    .from(gardenContainers)
+    .where(eq(gardenContainers.id, parsed.id))
+    .limit(1);
+
+  if (!row) throw new Error("Container not found");
+
+  const newImages = row.images.filter((u) => u !== parsed.url);
+  const wasPrimary = row.coverImageUrl === parsed.url;
+  const newCover = wasPrimary ? (newImages[0] ?? null) : row.coverImageUrl;
+
+  await db
+    .update(gardenContainers)
+    .set({ images: newImages, coverImageUrl: newCover, updatedAt: new Date() })
+    .where(eq(gardenContainers.id, parsed.id));
+
+  revalidatePath(`/garden/containers/${parsed.id}`);
+}
+
+export async function setContainerPrimaryImage(input: { id: string; url: string }) {
+  const parsed = z.object({ id: z.string().uuid(), url: z.string() }).parse(input);
+  const { household } = await getCurrentSession();
+  await assertCanAccessContainer(parsed.id, household.id);
+
+  const [row] = await db
+    .select({ images: gardenContainers.images })
+    .from(gardenContainers)
+    .where(eq(gardenContainers.id, parsed.id))
+    .limit(1);
+
+  if (!row) throw new Error("Container not found");
+  if (!row.images.includes(parsed.url)) throw new Error("Image not in container gallery");
+
+  await db
+    .update(gardenContainers)
+    .set({ coverImageUrl: parsed.url, updatedAt: new Date() })
+    .where(eq(gardenContainers.id, parsed.id));
+
+  revalidatePath(`/garden/containers/${parsed.id}`);
+}
+
 async function assertCanAccessContainer(id: string, householdId: string) {
  const [row] = await db
    .select({ id: gardenContainers.id })
@@ -118,8 +192,8 @@ const plantInput = z.object({
  fertilizingNotes: z.string().trim().max(2000).nullable().optional(),
  notes: z.string().trim().max(2000).nullable().optional(),
  acquisitionDate: z.string().nullable().optional(),
-  images: z.array(z.string().url()).max(10).default([]),
-  primaryImageUrl: z.string().url().nullable().optional(),
+  images: z.array(z.string().min(1)).max(10).default([]),
+  primaryImageUrl: z.string().min(1).nullable().optional(),
 });

 export async function createPlant(input: z.input<typeof plantInput>) {
@@ -230,7 +304,7 @@ export async function deletePlant(input: { id: string }) {
 }

 export async function addPlantImage(input: { id: string; url: string }) {
-  const parsed = z.object({ id: z.string().uuid(), url: z.string().url() }).parse(input);
+  const parsed = z.object({ id: z.string().uuid(), url: z.string().min(1) }).parse(input);
  const { household } = await getCurrentSession();
  await assertCanAccessPlant(parsed.id, household.id);

@@ -10,6 +10,7 @@ export type ContainerDto = {
  type: string;
  locationNotes: string | null;
  coverImageUrl: string | null;
+  images: string[];
  plantCount: number;
  createdAt: string;
  updatedAt: string;
@@ -39,6 +40,7 @@ export async function listContainers(): Promise<ContainerDto[]> {
      type: gardenContainers.type,
      locationNotes: gardenContainers.locationNotes,
      coverImageUrl: gardenContainers.coverImageUrl,
+      images: gardenContainers.images,
      createdAt: gardenContainers.createdAt,
      updatedAt: gardenContainers.updatedAt,
      plantCount: sql<number>`count(${gardenPlants.id})::int`,
@@ -51,6 +53,7 @@ export async function listContainers(): Promise<ContainerDto[]> {

  return rows.map((r) => ({
    ...r,
+    images: r.images ?? [],
    plantCount: r.plantCount ?? 0,
    createdAt: r.createdAt.toISOString(),
    updatedAt: r.updatedAt.toISOString(),
@@ -68,6 +71,7 @@ export async function getContainer(id: string): Promise<ContainerDetailDto | nul
      type: gardenContainers.type,
      locationNotes: gardenContainers.locationNotes,
      coverImageUrl: gardenContainers.coverImageUrl,
+      images: gardenContainers.images,
      createdAt: gardenContainers.createdAt,
      updatedAt: gardenContainers.updatedAt,
      plantCount: sql<number>`(select count(*)::int from garden_plants where container_id = ${gardenContainers.id})`,
@@ -98,6 +102,7 @@ export async function getContainer(id: string): Promise<ContainerDetailDto | nul
    type: container.type,
    locationNotes: container.locationNotes,
    coverImageUrl: container.coverImageUrl,
+    images: container.images ?? [],
    plantCount: container.plantCount ?? 0,
    createdAt: container.createdAt.toISOString(),
    updatedAt: container.updatedAt.toISOString(),
@@ -8,6 +8,7 @@ export type ContainerShareData = {
  type: string;
  locationNotes: string | null;
  coverImageUrl: string | null;
+  images: string[];
  plants: { id: string; name: string; scientificName: string | null }[];
 };

@@ -74,6 +75,7 @@ export async function loadContainerForShare(id: string): Promise<ContainerShareD
    type: container.type,
    locationNotes: container.locationNotes,
    coverImageUrl: container.coverImageUrl,
+    images: container.images ?? [],
    plants,
  };
 }
@@ -4,9 +4,11 @@ import calendarManifest from "./calendar/manifest";
 import listsManifest from "./lists/manifest";
 import notesManifest from "./notes/manifest";
 import gardenManifest from "./garden/manifest";
+import bangsManifest from "./bangs/manifest";

 registerModule(coreManifest);
 registerModule(calendarManifest);
 registerModule(listsManifest);
 registerModule(notesManifest);
 registerModule(gardenManifest);
+registerModule(bangsManifest);
Author	SHA1	Message	Date
ginnoir	10cad3df17	chore: release v0.4.8 Release / build-and-push (push) Has been cancelled Details	2026-06-02 20:26:57 -05:00
ginnoir	77db935329	chore: register 0018_container_images in drizzle migration journal	2026-06-02 20:19:57 -05:00
ginnoir	c6a34f7471	feat: share links visible on plants/containers; container image gallery - Fix ShareButton silently swallowing errors from createShareLink; now shows inline error text so failures are visible to the user - Add getShareLinksForEntity server action and EntityShareLink type to _core/share.ts - Add ShareLinkList component — renders active share links per entity with per-row Revoke; renders nothing when empty - Wire ShareLinkList into plant and container detail pages (loaded server-side in parallel with the entity fetch) - Add images jsonb column to garden_containers schema + migration 0018 - Add addContainerImage / removeContainerImage / setContainerPrimaryImage server actions mirroring the plant image pattern (10-image cap, first upload auto-sets cover) - Update ContainerDetailDto, listContainers, getContainer to include images - Rewrite ContainerDetail with Info/Gallery tabs; Gallery tab mirrors plant gallery (3-col grid, star/X overlays, upload button, counter) - Update ContainerShareData and container renderSharedView to show cover image hero and secondary image grid on public share pages	2026-06-02 20:15:29 -05:00
ginnoir	076e35aced	docs: add contributing guide, env reference, and operations runbook	2026-06-02 19:53:18 -05:00
ginnoir	8bf00c326d	docs: update decisions index and task index for garden module and adr backfill Populates the decisions index with the two existing ADRs (list SSE/notify, release workflow). Adds task 09 to the phase 1 list and adds the phase 8 garden module task entries to the task index.	2026-06-02 19:52:55 -05:00
ginnoir	6a1ec8bb7b	docs: add professional readme with full feature coverage and release pipeline hook Replaces the 8-line placeholder with a complete README covering all four modules, platform capabilities, quick start, dev setup, configuration reference, and deployment links. Badges use dynamic shields.io URLs so version/CI status update automatically on each release. Wires README review into the release pipeline via a release-it before:git:release hook and a new item in the pre-deploy checklist.	2026-06-02 19:52:24 -05:00
ginnoir	fe4673f1cd	chore: replace personal domains and ips with generic placeholders	2026-06-02 19:33:49 -05:00
ginnoir	4ec1f34150	chore: gitignore maintainer deploy scripts, scrub personal domain from dev.mjs	2026-06-02 19:30:27 -05:00
ginnoir	7938425850	chore: gitignore maintainer-specific production deploy files deploy/compose.yaml, deploy/Caddyfile, and deploy/Caddyfile.dev.snippet contain homelab-specific config and are not useful as public templates. Public-facing equivalents: compose.example.yaml and Caddyfile.snippet.	2026-06-02 19:22:31 -05:00
ginnoir	13d94b3751	chore(deploy): separate maintainer config from public deployment templates - rename Caddyfile.snippet → Caddyfile (maintainer's full production file) - restore Caddyfile.snippet as a minimal public reference (famapp blocks only) - add compose.example.yaml: standalone famapp + authentik template for new deployers; compose.yaml remains the maintainer's homelab monolith - update deploy/README.md: file table, setup steps referencing example files - apply-compose.ps1: point Caddy push at deploy/Caddyfile (not snippet)	2026-06-02 19:19:27 -05:00
ginnoir	aae3e30843	fix(deploy): separate reactive resume auth_secret from famapp - rename AUTH_SECRET to RESUME_AUTH_SECRET in production .env and compose app service — famapp's AUTH_SECRET is now unambiguous - remove orphaned stale AUTH_SECRET entry from .env - apply-compose.ps1: pull + restart famapp immediately after pushing compose rather than waiting for watchtower; uses dc alias via bash -ic - update .env.production.example to reflect corrected variable names	2026-06-02 19:12:34 -05:00
ginnoir	23a14e1650	chore: replace placeholder deploy config with actual production files - deploy/compose.yaml: replace generated placeholder with actual monolith compose (Foundry, Caddy, media stack, famapp, Authentik, Watchtower, etc.) - deploy/Caddyfile.snippet: replace with full production Caddyfile - .env.production.example: update variable names to match production (famapp_MINIO_ROOT_USER/PASSWORD/BUCKET, CF_API_TOKEN, etc.) - scripts/apply-compose.ps1: add -Compose/-Caddy flags; push Caddyfile and reload caddy in addition to compose restart	2026-06-02 19:03:53 -05:00
ginnoir	cce3bac5b2	chore: repo cleanup and prod sync tooling - Remove stale deploy/docker-entrypoint.sh (Dockerfile copies root version) - Remove scripts/seed.ts (superseded by seed.mjs) - Add src/app/error.tsx and global-error.tsx (untracked error boundaries) - Gitignore deploy/.prod/ for synced production configs - Add scripts/sync-prod.ps1 to pull compose/env/Caddyfile from valhalla - Add scripts/apply-compose.ps1 to push compose changes and restart services	2026-06-02 18:51:59 -05:00
ginnoir	31c5805b34	chore: release v0.4.7	2026-06-02 18:30:48 -05:00
ginnoir	989bae8f1e	feat(garden): add share button to plant and container detail views	2026-06-02 18:30:28 -05:00
ginnoir	090366422d	chore: release v0.4.6 Release / build-and-push (push) Has been cancelled Details	2026-06-02 18:16:26 -05:00
ginnoir	4049a73c6b	fix(garden): accept relative urls for plant image uploads Zod v4 changed .url() to use the WHATWG URL spec, which rejects relative paths like /api/uploads/... that our upload API returns. Relax image URL validators to z.string().min(1) since these are internal paths.	2026-06-02 18:15:12 -05:00
ginnoir	272d3cbbe6	chore: release v0.4.5 Release / build-and-push (push) Has been cancelled Details	2026-06-02 04:27:39 -05:00
ginnoir	b5a966e3a9	feat(bangs): add bang counter dashboard widget Adds a new "bangs" module with a dashboard widget that tracks household bang events. The widget shows the total count, a configurable recent-bang list, and an "Add Bang" button that accepts a backdatable date. On submission, a full celebration sequence fires: screen flash, widget shake, count pop animation, synthesized firework sound (Web Audio API), 50 full-screen emoji particles via portal, canvas-confetti star bursts, side cannons, and a timed sequence of 7 firework bursts. - New bang_events table (migration 0017) - canvas-confetti dependency for fireworks/confetti effects - CSS keyframe animations: shake, countPop, emojiFloat - Fixes pre-existing Drizzle snapshot chain collision (0007/0008) - Adds OpenPlantBook env vars to compose.yaml	2026-06-02 04:26:22 -05:00
				`@@ -0,0 +1 @@`
				`ALTER TABLE "garden_containers" ADD COLUMN "images" jsonb DEFAULT '[]'::jsonb NOT NULL;`