From 6c213f4e7918f9082336e1fdab777136c1d73409 Mon Sep 17 00:00:00 2001
From: hbrain <hbrain@piagent.local>
Date: Tue, 2 Jun 2026 13:08:41 +0200
Subject: [PATCH] Updated readme:

 - unconditional map regeneration on Save changes
 - logging to /var/log/mvlog_map.log
---
 README.md | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 4de6bb8..b55835b 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ PHP web UI for publishing and managing MVLog videos on **bubulescu.org**.
 
 ## Main structure
 
-- `index.php` — public landing page (rendered videos)
+- `index.php` — public landing page (rendered videos and permalink pages)
 - `new.php` — authenticated admin UI
 - `feed.php` — RSS feed
 - `contact.php` — contact form
@@ -26,8 +26,8 @@ PHP web UI for publishing and managing MVLog videos on **bubulescu.org**.
 Important dirs:
 
 - `in-dir/` — input/article dirs
-- `out-dir/` — rendered videos
-- `thumbs/` — custom video poster images
+- `out-dir/` — rendered videos and article OG images (`<article_id>_og.jpg`)
+- `thumbs/` — legacy thumbnail cache / cleanup dir
 - `cache/` — metadata/search/push caches
 
 ## Public page (`index.php`)
@@ -40,9 +40,11 @@ Important dirs:
   - `location=...` / `place=...`
 - Case-insensitive + accent-insensitive matching
 - Shows title/date/location/teaser/description/quote_da
-- **No generated timestamp is shown on cards**
+- Article permalinks use `?id=<article_id>`; filename fallback is no longer used
+- Permalink pages hide the bottom page numbers
 - Optional map image per video (hidden when source article has `.mvlog-hide-map`)
-- Optional custom video poster from `thumbs/`
+- Video posters are resolved from the source image recorded in the thumbnail sidecar JSON; if the source image is missing, the `<video>` gets no poster
+- Permalink OG/Twitter images use `out-dir/<article_id>_og.jpg` when present; otherwise they fall back to `https://bubulescu.org/assets/img/bubulescuorg.jpg`
 
 ## Admin (`new.php`)
 
@@ -55,7 +57,7 @@ Tabs:
 
 Implemented behavior:
 
-- Article identity uses `.mvlog-id` (immutable ID), with legacy dir-name fallback
+- Article identity uses `.mvlog-id` / `article_id` as the stable canonical ID; legacy dir-name fallback only applies to older entries that are missing the ID
 - Draft metadata is read/written from `in-dir/<job>/data.txt`
 - Supports metadata fields: `title`, `teaser`, `quote_da`, `date`, `place`, `description`
 - Manual media reordering via `order.json` (AJAX action `reorder_file`)
@@ -64,7 +66,11 @@ Implemented behavior:
   - Render (`set_enabled`)
   - Show (`set_visible`)
   - Hide map (`set_map_hidden` -> `.mvlog-hide-map`)
-- Custom video poster selection from input images (`set_video_thumb`)
+- `Save changes` always regenerates the map PNG(s) for the article on every press, via `bin/gpsmap.py`
+- Map regeneration logs are written to `/var/log/mvlog_map.log`
+- Custom video poster selection uses the source image recorded in `<output>_thumb.json`; if the source image is missing, no poster file is used
+- `set_video_thumb` also writes an article-specific OG image to `out-dir/<article_id>_og.jpg`
+- Thumbnail provenance is stored in the thumb JSON sidecar (`article_id`, `input_dir`, `source_file`, `source_path`, `created_at`)
 - Describe button uses `lib/generate_data_sync.php`
 - Job status polling via `job_status.php` every 32s
 
@@ -95,6 +101,7 @@ Files:
 - `sw.js` — service worker fallback notification text
 
 Current text behavior:
+- Show notifications open the article permalink (`./?id=<article_id>`)
 - payload body: `New aticle @ MVL!`
 - SW fallback title/body: `MVL` / `New article @ MVL!`
 
@@ -128,4 +135,4 @@ return [
 
 - `contact.php` is currently in `.gitignore`.
 - Keep secrets out of git (`push.json`, private keys, auth secrets).
-- Worker/rendering is handled by separate movmaker worker project.
\ No newline at end of file
+- Worker/rendering is handled by separate movmaker worker project.