v5.0 Introduce centralized homepage & portrait photo management

docs/roadmap_plan.md

@@ -114,28 +114,26 @@ Deferred out of this release:
 
 ## V5.0 — Unified Photos Table (major data-model change)
 
-Per your feedback, this replaces the earlier "Track B" idea with a single
-shared model: a **`photos` table** holding an image reference plus a text
-`description` field, used by **both** the homepage gallery and Person
-portraits — rather than building two separate, one-off metadata layers.
+V5.0 standardizes homepage images and Person portraits into one shared `photo`
+table and one storage layout.
 
-Rough shape (subject to the further discussion you flagged before any
-implementation):
-- `photos`: id, image path/reference, description, and whatever
-  owner/context linkage is needed (e.g. a polymorphic or nullable
-  `person_id` plus a `context`/`kind` discriminator such as `"homepage"` vs
-  `"portrait"` — exact shape is an open design question, not decided here).
-- Person gets **multiple portraits** instead of the current single
-  `portrait_path` string column — needs a migration to move existing
-  single-portrait data into the new table.
-- Homepage images gain **descriptions**, using the same table instead of a
-  separate sidecar/caption mechanism.
-- Because this is a genuine shared-schema decision (one table, two
-  consumers, plus a migration of existing single-portrait data), this is
-  correctly a 5.x "major change" rather than a small add-on — **flagged for
-  a follow-up design discussion before implementation starts**, specifically
-  on the exact `photos` table shape and how "which photos belong to which
-  person/context" should be modeled.
+Finalized shape:
+- `photo`: `id`, nullable `person_id`, `path`, `description`, `is_primary`,
+  timestamps.
+- `person_id IS NULL` = homepage photos; non-null = Person photos.
+- `is_primary` is the featured/first photo for that owner (homepage or Person).
+- No separate context enum; ownership is derived from `person_id`.
+- All image files are stored under `UPLOAD_DIR/photos/{photo_id}{suffix}`.
+- `Person.portrait_path` is removed.
+- `HOMEPAGE_DIR` is retired; homepage markdown remains file-backed at
+  `UPLOAD_DIR/homepage.md`.
+
+Migration policy for legacy installs:
+- Export/import rebuild remains the migration mechanism.
+- Legacy `person.portrait_path` values are backfilled into `photo` rows.
+- Legacy homepage images under `UPLOAD_DIR/homepage` are backfilled into
+  homepage `photo` rows.
+- Legacy homepage markdown is relocated to `UPLOAD_DIR/homepage.md`.
 
 ---