From a9b14b8f738b0ee7cc7a3734ce5902f7736a8201 Mon Sep 17 00:00:00 2001
From: Deeman <hendriknote@gmail.com>
Date: Tue, 24 Feb 2026 20:51:29 +0100
Subject: [PATCH] docs: update CHANGELOG + PROJECT.md for pSEO Engine

Records all Phase 1 deliverables: content gaps, data freshness,
health checks, generation job monitoring, 45 tests, bug fixes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CHANGELOG.md | 10 ++++++++++
 PROJECT.md   |  2 ++
 2 files changed, 12 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8184e00..0e4a58b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ## [Unreleased]
 
 ### Added
+- **pSEO Engine admin tab** (`/admin/pseo`) — operational visibility for the programmatic SEO system:
+  - **Content gap detection** — queries DuckDB serving tables vs SQLite articles to find rows with no matching article per language; per-template HTMX-loaded gap list
+  - **Data freshness signals** — compares `_serving_meta.json` export timestamp vs `MAX(updated_at)` in articles; per-template status: 🟢 Fresh / 🟡 Stale / 🟣 No articles / ⚫ No data
+  - **Article health checks** (HTMX partial) — hreflang orphans (EN exists, DE missing), missing HTML build files, broken `[scenario:slug]` references in article markdown
+  - **Generation job monitoring** — live progress bars polling every 2s while jobs run; stops polling on completion; error drilldown via `<details>`; dedicated `/admin/pseo/jobs` list page
+  - **`_serving_meta.json`** — written by `export_serving.py` after atomic rename; records `exported_at_utc` and per-table row counts; drives freshness signals in pSEO Engine dashboard
+  - **Progress tracking columns** on `tasks` table (migration 0021): `progress_current`, `progress_total`, `error_log`; `generate_articles()` writes progress every 50 articles and on completion
+  - 45 new tests covering all health functions + pSEO routes (access control, rendering, gap detection, generate-gaps POST, job status HTMX polling)
+
+
 - **Dual market score system** — split the single market score into two branded scores:
   - **padelnomics Marktreife-Score™** (market maturity): existing score, refined — only for cities
     with ≥1 padel venue. Adds ×0.85 saturation discount when `venues_per_100k > 8`.
diff --git a/PROJECT.md b/PROJECT.md
index 2bb85a1..c1bf877 100644
--- a/PROJECT.md
+++ b/PROJECT.md
@@ -107,6 +107,7 @@
 - [x] Task queue management (list, retry, delete)
 - [x] Lead funnel stats on admin dashboard
 - [x] Email hub (`/admin/emails`) — sent log, inbox, compose, audiences, delivery event tracking via Resend webhooks
+- [x] **pSEO Engine tab** (`/admin/pseo`) — content gap detection, data freshness signals, article health checks (hreflang orphans, missing build files, broken scenario refs), generation job monitoring with live progress bars
 
 ### SEO & Legal
 - [x] Sitemap (both language variants, `<lastmod>` on all entries)
@@ -136,6 +137,7 @@
 ## In Progress 🔄
 
 - [ ] **Dual market score system** — Marktreife-Score + Marktpotenzial-Score + expanded data pipeline (merging to master)
+- [ ] **pSEO Engine** — implemented (worktree `pseo-engine`), pending merge to master
 
 ---