From 5cb819f25d7387c750bd482caa5bef824f413ed4 Mon Sep 17 00:00:00 2001
From: "Tewodros A. Asfaw" <1649769+DigitalTsotsi@users.noreply.github.com>
Date: Fri, 7 Aug 2026 20:42:17 +0200
Subject: [PATCH] Add a daily article publisher action for the blog

---
 .github/workflows/ci.yml              |  21 ++
 .github/workflows/publish-article.yml |  62 ++++++
 .gitignore                            |   5 +
 publisher/README.md                   |  59 ++++++
 publisher/__init__.py                 |   7 +
 publisher/config.py                   |  63 ++++++
 publisher/content.py                  | 126 ++++++++++++
 publisher/index_update.py             |  30 +++
 publisher/publish.py                  |  87 ++++++++
 publisher/render.py                   | 136 +++++++++++++
 publisher/topics.py                   | 272 ++++++++++++++++++++++++++
 requirements-dev.txt                  |   2 +
 requirements.txt                      |   1 +
 run_publish.py                        |  43 ++++
 test.sh                               |   5 +
 tests/__init__.py                     |   0
 tests/test_content.py                 |  61 ++++++
 tests/test_index_update.py            |  35 ++++
 tests/test_publish.py                 |  83 ++++++++
 tests/test_render.py                  |  56 ++++++
 tests/test_topics.py                  |  49 +++++
 21 files changed, 1203 insertions(+)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .github/workflows/publish-article.yml
 create mode 100644 .gitignore
 create mode 100644 publisher/README.md
 create mode 100644 publisher/__init__.py
 create mode 100644 publisher/config.py
 create mode 100644 publisher/content.py
 create mode 100644 publisher/index_update.py
 create mode 100644 publisher/publish.py
 create mode 100644 publisher/render.py
 create mode 100644 publisher/topics.py
 create mode 100644 requirements-dev.txt
 create mode 100644 requirements.txt
 create mode 100644 run_publish.py
 create mode 100644 test.sh
 create mode 100644 tests/__init__.py
 create mode 100644 tests/test_content.py
 create mode 100644 tests/test_index_update.py
 create mode 100644 tests/test_publish.py
 create mode 100644 tests/test_render.py
 create mode 100644 tests/test_topics.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..54340ab
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,21 @@
+name: ci
+
+on:
+  push:
+    branches: [main, dev_asfa]
+  pull_request:
+    branches: [main]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install dependencies
+        run: pip install -r requirements-dev.txt
+      - name: Run tests
+        run: bash test.sh
diff --git a/.github/workflows/publish-article.yml b/.github/workflows/publish-article.yml
new file mode 100644
index 0000000..db6fd3a
--- /dev/null
+++ b/.github/workflows/publish-article.yml
@@ -0,0 +1,62 @@
+name: publish-article
+
+on:
+  schedule:
+    - cron: "23 7 * * *"   # daily at 07:23 UTC
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Render the article and log it without opening a pull request"
+        required: false
+        type: boolean
+        default: false
+      topic_slug:
+        description: "Force a specific topic slug (optional)"
+        required: false
+        type: string
+        default: ""
+
+concurrency:
+  group: vmx_blog_publish
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Generate the article
+        id: gen
+        env:
+          BRIGHT_DATA_API_KEY: ${{ secrets.BRIGHT_DATA_API_KEY }}
+          SERP_API_KEY: ${{ secrets.SERP_API_KEY }}
+          TOPIC_SLUG: ${{ inputs.topic_slug }}
+          DRY_RUN: ${{ inputs.dry_run && '1' || '0' }}
+        run: python run_publish.py
+      - name: Open a pull request
+        if: ${{ steps.gen.outputs.created == 'true' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: ${{ steps.gen.outputs.branch }}
+          TITLE: ${{ steps.gen.outputs.title }}
+        run: |
+          set -euo pipefail
+          git config user.name "vmodal-blog-bot"
+          git config user.email "vmodal-blog-bot@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add articles index.html
+          git commit -m "Add article: $TITLE"
+          git push --force-with-lease origin "$BRANCH"
+          gh pr create --base main --head "$BRANCH" \
+            --title "New blog article: $TITLE" \
+            --body "Automated draft of a new blog article for review. Merge to publish it to the site, or close to skip it."
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b79f891
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+.env
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
diff --git a/publisher/README.md b/publisher/README.md
new file mode 100644
index 0000000..865c207
--- /dev/null
+++ b/publisher/README.md
@@ -0,0 +1,59 @@
+# Daily article publisher
+
+A scheduled GitHub Action that adds a new article to the blog each day. It picks a
+topic, generates the article text, renders it into the site's HTML template, writes it
+into `articles/`, links it from `index.html`, and opens a pull request with the change
+for review. Nothing goes live until that pull request is merged.
+
+## How it works
+
+1. `run_publish.py` selects a topic from `publisher/topics.py`. It prefers a topic that
+   has not been published yet, then rotates through the list, so articles stay varied.
+2. It generates the body text, preferring Bright Data's Google AI Mode, falling back to
+   SerpApi's Google AI Overview, and finally to the topic's own self-contained body, so
+   a well-formed article is produced even before any key is configured.
+3. It renders a standalone page under `articles/YYYYMMDD-<slug>.html` using the same
+   template as the existing articles and adds a list item to the top of `index.html`.
+4. The workflow commits the change on a new branch and opens a pull request. A run is
+   idempotent per day: if today's article already exists, it does nothing.
+
+## Configuration
+
+Set these as repository secrets (**Settings → Secrets and variables → Actions**).
+Both are optional; with neither set, the publisher uses each topic's built-in body.
+
+| Secret | Purpose |
+| --- | --- |
+| `BRIGHT_DATA_API_KEY` | Bright Data Google AI Mode content (preferred) |
+| `SERP_API_KEY` | SerpApi Google AI Overview content (fallback) |
+
+For the workflow to open pull requests, **Settings → Actions → General → Workflow
+permissions** must allow GitHub Actions to create and approve pull requests.
+
+## Running it manually
+
+From the **Actions** tab, pick **publish-article** and **Run workflow**. Tick the
+dry-run box to render and log an article without opening a pull request, or set a topic
+slug to force a specific topic.
+
+From the command line:
+
+```bash
+gh workflow run publish-article.yml                       # real run, opens a PR
+gh workflow run publish-article.yml -f dry_run=true       # render and log only
+gh workflow run publish-article.yml -f topic_slug=edge-inference
+```
+
+## Running locally
+
+```bash
+pip install -r requirements-dev.txt
+bash test.sh                 # offline tests
+DRY_RUN=1 python run_publish.py   # render an article and log it, write nothing
+```
+
+## Adding or editing topics
+
+Topics live in `publisher/topics.py`. Each has a stable slug, a title, tags, a one-line
+summary, the search prompt sent to the AI source, and a self-contained fallback body.
+Add an entry to the `TOPICS` list to expand the rotation.
diff --git a/publisher/__init__.py b/publisher/__init__.py
new file mode 100644
index 0000000..79ef928
--- /dev/null
+++ b/publisher/__init__.py
@@ -0,0 +1,7 @@
+"""Daily article publisher for the V-Modal AI Blog.
+
+Picks a topic, generates the article text from Google's AI answer (Bright Data's
+Google AI Mode, with SerpApi's Google AI Overview as a fallback, and a self-contained
+fallback when neither is configured), renders it into the site's HTML template, writes
+it into `articles/`, and links it from `index.html`.
+"""
diff --git a/publisher/config.py b/publisher/config.py
new file mode 100644
index 0000000..18a7079
--- /dev/null
+++ b/publisher/config.py
@@ -0,0 +1,63 @@
+"""Runtime configuration for the article publisher.
+
+Values come from environment variables. In Actions they are provided as repository
+secrets; for local runs a .env file (gitignored) is loaded here if present. Nothing in
+this module ever writes secrets to disk or logs them.
+"""
+import os
+from dataclasses import dataclass
+
+
+def load_dotenv(path=".env"):
+    """Load KEY=VALUE lines from a .env file into os.environ (does not overwrite
+    variables that are already set). Missing file is a no-op. No dependency needed."""
+    if not os.path.isfile(path):
+        return
+    with open(path, "r", encoding="utf-8") as fh:
+        for raw in fh:
+            line = raw.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, value = line.partition("=")
+            key = key.strip()
+            value = value.strip().strip('"').strip("'")
+            if key and key not in os.environ:
+                os.environ[key] = value
+
+
+@dataclass
+class Config:
+    brightdata_api_key: str = ""
+    serpapi_key: str = ""
+    articles_dir: str = "articles"
+    index_path: str = "index.html"
+    # Optional: force a specific topic by slug instead of the automatic rotation.
+    topic_slug: str = ""
+    dry_run: bool = False
+
+    @property
+    def brightdata_enabled(self) -> bool:
+        return bool(self.brightdata_api_key)
+
+    @property
+    def serpapi_enabled(self) -> bool:
+        return bool(self.serpapi_key)
+
+
+def _truthy(value: str) -> bool:
+    return str(value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def load_config(env=None) -> Config:
+    """Build a Config from the environment (after loading .env for local runs)."""
+    if env is None:
+        load_dotenv()
+        env = os.environ
+    return Config(
+        brightdata_api_key=env.get("BRIGHT_DATA_API_KEY", "").strip(),
+        serpapi_key=env.get("SERP_API_KEY", "").strip(),
+        articles_dir=(env.get("ARTICLES_DIR") or "articles").strip(),
+        index_path=(env.get("INDEX_PATH") or "index.html").strip(),
+        topic_slug=env.get("TOPIC_SLUG", "").strip(),
+        dry_run=_truthy(env.get("DRY_RUN")),
+    )
diff --git a/publisher/content.py b/publisher/content.py
new file mode 100644
index 0000000..10b4bf6
--- /dev/null
+++ b/publisher/content.py
@@ -0,0 +1,126 @@
+"""Generate the article text for a topic.
+
+Content generation prefers Bright Data's Google AI Mode API when configured, and
+otherwise falls back to SerpApi's Google AI Overview (a two-step call: a Google search
+yields an ai_overview, either inline or via a short-lived page_token that is then
+fetched from the AI-overview engine). Google only returns an AI answer for some
+queries, so when there is none (or neither provider is configured) we fall back to the
+topic's own self-contained body so the publisher always produces a complete article.
+"""
+from typing import Any, Dict
+
+import requests
+
+SERPAPI_SEARCH = "https://serpapi.com/search"
+
+# Bright Data Google AI Mode dataset (synchronous scrape endpoint).
+BRIGHTDATA_SCRAPE = "https://api.brightdata.com/datasets/v3/scrape"
+BRIGHTDATA_AIMODE_DATASET = "gd_mcswdt6z2elth3zqr2"
+# Keys most likely to hold the AI answer in Bright Data's response, in priority order.
+_AIMODE_TEXT_KEYS = (
+    "answer_text", "answer", "ai_overview", "overview",
+    "markdown", "text", "content", "response", "result",
+)
+
+
+def _overview_text(ai_overview: Dict[str, Any]) -> str:
+    """Flatten SerpApi ai_overview.text_blocks into plain text (markdown-ish)."""
+    parts = []
+    for block in ai_overview.get("text_blocks") or []:
+        snippet = str(block.get("snippet") or "").strip()
+        if snippet:
+            parts.append(snippet)
+        for item in block.get("list") or []:
+            s = str(item.get("snippet") or "").strip()
+            if s:
+                parts.append(f"- {s}")
+    return "\n".join(parts).strip()
+
+
+def fetch_ai_overview(query: str, api_key: str, get=requests.get) -> str:
+    """Return Google's AI Overview text for `query`, or "" when there is none."""
+    if not api_key:
+        return ""
+    resp = get(SERPAPI_SEARCH, params={"engine": "google", "q": query, "api_key": api_key}, timeout=30)
+    resp.raise_for_status()
+    data = resp.json() or {}
+    ai = data.get("ai_overview") or {}
+    text = _overview_text(ai)
+    if text:
+        return text
+    token = str(ai.get("page_token") or "").strip()
+    if not token:
+        return ""
+    resp2 = get(
+        SERPAPI_SEARCH,
+        params={"engine": "google_ai_overview", "page_token": token, "api_key": api_key},
+        timeout=30,
+    )
+    resp2.raise_for_status()
+    data2 = resp2.json() or {}
+    return _overview_text(data2.get("ai_overview") or {})
+
+
+def _extract_aimode_text(data) -> str:
+    """Best-effort pull of the readable AI answer out of Bright Data's response.
+
+    The scrape endpoint returns a list of result objects; the exact schema for the
+    Google AI Mode dataset varies, so walk it and take the first non-empty string under
+    a known answer key (recursing into nested dicts/lists)."""
+    items = data if isinstance(data, list) else [data]
+    for item in items:
+        if isinstance(item, str):
+            if item.strip():
+                return item.strip()
+            continue
+        if not isinstance(item, dict):
+            continue
+        for key in _AIMODE_TEXT_KEYS:
+            val = item.get(key)
+            if isinstance(val, str) and val.strip():
+                return val.strip()
+            if isinstance(val, (list, dict)):
+                nested = _extract_aimode_text(val if isinstance(val, list) else [val])
+                if nested:
+                    return nested
+    return ""
+
+
+def fetch_ai_mode(query: str, api_key: str, post=requests.post) -> str:
+    """Return Google AI Mode text for `query` via Bright Data, or "" when unavailable.
+    `post` is injectable for tests."""
+    if not api_key:
+        return ""
+    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
+    payload = {
+        "input": [{"url": "https://google.com/aimode", "prompt": query, "hl": "en", "country": ""}],
+        "limit_per_input": None,
+    }
+    resp = post(
+        BRIGHTDATA_SCRAPE,
+        params={"dataset_id": BRIGHTDATA_AIMODE_DATASET, "notify": "false", "include_errors": "true"},
+        headers=headers, json=payload, timeout=60,
+    )
+    resp.raise_for_status()
+    return _extract_aimode_text(resp.json())
+
+
+def generate_article_body(topic, config, get=requests.get, post=requests.post) -> str:
+    """Return the article body (markdown-ish text) for a topic.
+
+    Uses the Google AI answer when available (Bright Data preferred, SerpApi as a
+    fallback), otherwise the topic's own self-contained body. Never raises on a
+    missing or failing provider."""
+    query = topic.prompt
+    overview = ""
+    if getattr(config, "brightdata_enabled", False):
+        try:
+            overview = fetch_ai_mode(query, config.brightdata_api_key, post=post)
+        except Exception:
+            overview = ""
+    if not overview and getattr(config, "serpapi_enabled", False):
+        try:
+            overview = fetch_ai_overview(query, config.serpapi_key, get=get)
+        except Exception:
+            overview = ""
+    return overview.strip() if overview else topic.fallback_body()
diff --git a/publisher/index_update.py b/publisher/index_update.py
new file mode 100644
index 0000000..dbd0ba5
--- /dev/null
+++ b/publisher/index_update.py
@@ -0,0 +1,30 @@
+"""Insert a new article's list item into index.html.
+
+The homepage lists articles inside `<ul class="article-list">`. A new article is
+added as the first item so the newest is shown at the top, leaving the rest of the
+page untouched.
+"""
+
+LIST_OPEN = '<ul class="article-list">'
+
+
+class IndexFormatError(ValueError):
+    """Raised when index.html does not contain the expected article list."""
+
+
+def insert_article(index_html: str, li_html: str, href: str = "") -> str:
+    """Return index_html with li_html inserted as the first list item.
+
+    If `href` is given and already present in the page, the html is returned
+    unchanged (idempotent — a re-run does not duplicate the entry)."""
+    if href and f'"{href}"' in index_html:
+        return index_html
+    pos = index_html.find(LIST_OPEN)
+    if pos == -1:
+        raise IndexFormatError(f"could not find {LIST_OPEN!r} in index.html")
+    # Insert right after the end of the line that opens the list.
+    line_end = index_html.find("\n", pos)
+    if line_end == -1:
+        raise IndexFormatError("malformed article list in index.html")
+    insert_at = line_end + 1
+    return index_html[:insert_at] + li_html + "\n" + index_html[insert_at:]
diff --git a/publisher/publish.py b/publisher/publish.py
new file mode 100644
index 0000000..49a2a88
--- /dev/null
+++ b/publisher/publish.py
@@ -0,0 +1,87 @@
+"""Tie the pieces together: pick a topic, generate the body, render the files.
+
+`publish()` is pure with respect to time and network (both are injectable) so it can
+be exercised offline. It writes the new article and the updated index only on a real
+run; a dry run returns the rendered output without touching disk.
+"""
+import os
+from datetime import datetime, timezone
+
+import requests
+
+from . import content as content_mod
+from . import render
+from . import topics as topics_mod
+from .index_update import insert_article
+
+
+def _existing_article_files(articles_dir: str):
+    if not os.path.isdir(articles_dir):
+        return []
+    return sorted(f for f in os.listdir(articles_dir) if f.endswith(".html"))
+
+
+def used_slugs(files, topic_list):
+    used = set()
+    for f in files:
+        for t in topic_list:
+            if f.endswith(f"-{t.slug}.html"):
+                used.add(t.slug)
+    return used
+
+
+def pick_topic(config, files):
+    if config.topic_slug:
+        t = topics_mod.get_topic(config.topic_slug)
+        if t is None:
+            raise ValueError(f"unknown TOPIC_SLUG: {config.topic_slug!r}")
+        return t
+    every = topics_mod.all_topics()
+    return topics_mod.select_topic(used_slugs(files, every), rotation_index=len(files))
+
+
+def publish(config, now=None, get=requests.get, post=requests.post) -> dict:
+    dt = now or datetime.now(timezone.utc)
+    files = _existing_article_files(config.articles_dir)
+
+    # One article per day: an automatic run does nothing once today's article exists.
+    # A manually forced topic (TOPIC_SLUG) is still allowed through.
+    today_prefix = dt.strftime("%Y%m%d") + "-"
+    todays = [f for f in files if f.startswith(today_prefix)]
+    if todays and not config.topic_slug:
+        return {"status": "exists", "topic": "", "title": "",
+                "filename": todays[0],
+                "path": os.path.join(config.articles_dir, todays[0])}
+
+    topic = pick_topic(config, files)
+    filename = render.article_filename(dt, topic.slug)
+    article_path = os.path.join(config.articles_dir, filename)
+    href = f"articles/{filename}"
+    branch = f"article/{dt.strftime('%Y%m%d')}-{topic.slug}"
+
+    if os.path.exists(article_path):
+        return {"status": "exists", "topic": topic.slug, "title": topic.title,
+                "filename": filename, "path": article_path, "branch": branch}
+
+    body = content_mod.generate_article_body(topic, config, get=get, post=post)
+    page_html = render.render_article_page(topic, body, dt)
+    li_html = render.render_index_li(topic, dt, filename)
+
+    with open(config.index_path, "r", encoding="utf-8") as fh:
+        index_html = fh.read()
+    new_index = insert_article(index_html, li_html, href=href)
+
+    result = {"topic": topic.slug, "title": topic.title, "filename": filename,
+              "path": article_path, "href": href, "branch": branch,
+              "page_html": page_html, "index_html": new_index}
+
+    if config.dry_run:
+        result["status"] = "dry-run"
+        return result
+
+    with open(article_path, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(page_html)
+    with open(config.index_path, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(new_index)
+    result["status"] = "published"
+    return result
diff --git a/publisher/render.py b/publisher/render.py
new file mode 100644
index 0000000..82517a2
--- /dev/null
+++ b/publisher/render.py
@@ -0,0 +1,136 @@
+"""Render a topic and its generated body into the site's HTML.
+
+The output matches the existing hand-written articles: a standalone page under
+`articles/` using the shared template, plus a list item for `index.html`. The body
+text (from the AI source or the topic fallback) is markdown-ish, so a small,
+dependency-free converter turns ## / ### headings, bullet lists, and paragraphs into
+the same tags the existing articles use.
+"""
+import re
+
+MONTHS = ["", "January", "February", "March", "April", "May", "June", "July",
+          "August", "September", "October", "November", "December"]
+
+
+def _escape(text: str) -> str:
+    return text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def _inline(text: str) -> str:
+    """Escape HTML, then apply inline markdown: `code`, **bold**, *em* / _em_."""
+    out = _escape(text)
+    out = re.sub(r"`([^`]+)`", r"<code>\1</code>", out)
+    out = re.sub(r"\*\*([^*]+)\*\*", r"<strong>\1</strong>", out)
+    out = re.sub(r"\*([^*]+)\*", r"<em>\1</em>", out)
+    out = re.sub(r"_([^_]+)_", r"<em>\1</em>", out)
+    return out
+
+
+def _is_bullet(line: str) -> bool:
+    s = line.lstrip()
+    return s.startswith("- ") or s.startswith("* ")
+
+
+def render_body_html(markdown_text: str, indent: str = "      ") -> str:
+    """Convert markdown-ish body text into the article's inner HTML."""
+    lines = (markdown_text or "").replace("\r\n", "\n").split("\n")
+    blocks = []
+    para: list = []
+    bullets: list = []
+
+    def flush_para():
+        if para:
+            blocks.append(f"{indent}<p>{_inline(' '.join(para).strip())}</p>")
+            para.clear()
+
+    def flush_bullets():
+        if bullets:
+            items = "\n".join(f"{indent}  <li>{_inline(b)}</li>" for b in bullets)
+            blocks.append(f"{indent}<ul>\n{items}\n{indent}</ul>")
+            bullets.clear()
+
+    for raw in lines:
+        line = raw.rstrip()
+        stripped = line.strip()
+        if not stripped:
+            flush_para()
+            flush_bullets()
+            continue
+        if stripped.startswith("### "):
+            flush_para(); flush_bullets()
+            blocks.append(f"{indent}<h3>{_inline(stripped[4:].strip())}</h3>")
+        elif stripped.startswith("## "):
+            flush_para(); flush_bullets()
+            blocks.append(f"{indent}<h2>{_inline(stripped[3:].strip())}</h2>")
+        elif stripped.startswith("# "):
+            flush_para(); flush_bullets()
+            blocks.append(f"{indent}<h2>{_inline(stripped[2:].strip())}</h2>")
+        elif _is_bullet(stripped):
+            flush_para()
+            bullets.append(stripped[2:].strip())
+        else:
+            flush_bullets()
+            para.append(stripped)
+
+    flush_para()
+    flush_bullets()
+    return "\n\n".join(blocks)
+
+
+def month_year(dt) -> str:
+    return f"{MONTHS[dt.month]} {dt.year}"
+
+
+def meta_line(dt, tags) -> str:
+    parts = [month_year(dt)] + list(tags or [])
+    return " &middot; ".join(parts)
+
+
+def article_filename(dt, slug: str) -> str:
+    return f"{dt.strftime('%Y%m%d')}-{slug}.html"
+
+
+def render_article_page(topic, body_markdown: str, dt) -> str:
+    body_html = render_body_html(body_markdown)
+    meta = meta_line(dt, topic.tags)
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>{_escape(topic.title)} &ndash; VModal Blog</title>
+  <link rel="stylesheet" href="../style.css" />
+</head>
+<body>
+  <header>
+    <a href="../index.html">V-Modal AI Blog</a>
+  </header>
+
+  <main>
+    <a class="back-link" href="../index.html">&larr; Back to all articles</a>
+
+    <div class="article-body">
+      <h1>{_escape(topic.title)}</h1>
+      <p style="color:#888; font-size:0.9rem; margin-bottom:1.5rem;">{meta}</p>
+
+{body_html}
+    </div>
+  </main>
+
+  <footer>
+    &copy; {dt.year} VModal Blog
+  </footer>
+</body>
+</html>
+"""
+
+
+def render_index_li(topic, dt, filename: str) -> str:
+    meta = meta_line(dt, topic.tags)
+    return (
+        "      <li>\n"
+        f"        <a href=\"articles/{filename}\">{_escape(topic.title)}</a>\n"
+        f"        <div class=\"summary\">{_escape(topic.summary)}</div>\n"
+        f"        <div class=\"meta\">{meta}</div>\n"
+        "      </li>"
+    )
diff --git a/publisher/topics.py b/publisher/topics.py
new file mode 100644
index 0000000..397f6d6
--- /dev/null
+++ b/publisher/topics.py
@@ -0,0 +1,272 @@
+"""The catalogue of blog topics and the rotation that picks one per run.
+
+Each topic carries a stable slug (used in the file name and to detect repeats), a
+title, tags, a one-line summary for the index, the search prompt sent to the AI
+content source, and a self-contained fallback body used when no AI answer is
+available. The fallback bodies are written in the same markdown-ish form the AI
+sources return (## headings, paragraphs, and - bullet lists) so a single renderer
+handles both.
+"""
+from dataclasses import dataclass, field
+from typing import List
+
+
+@dataclass(frozen=True)
+class Topic:
+    slug: str
+    title: str
+    tags: List[str]
+    summary: str
+    prompt: str
+    intro: str
+    sections: List[tuple] = field(default_factory=list)
+
+    def fallback_body(self) -> str:
+        parts = [self.intro.strip()]
+        for heading, body in self.sections:
+            parts.append(f"## {heading}\n\n{body.strip()}")
+        return "\n\n".join(p for p in parts if p).strip()
+
+
+TOPICS: List[Topic] = [
+    Topic(
+        slug="multimodal-embeddings",
+        title="Joint Embedding Spaces for Multimodal Search",
+        tags=["AI", "Search"],
+        summary="How shared vector spaces let a single query reach across text, images, and audio.",
+        prompt="How do joint embedding spaces power multimodal search across text, images, and audio? Cover contrastive training and nearest-neighbour retrieval.",
+        intro=(
+            "Multimodal search rests on a simple idea: project every modality into one "
+            "shared vector space where similar things land close together, regardless of "
+            "whether they started as text, an image, or a sound. Once everything is a "
+            "vector, retrieval becomes a nearest-neighbour lookup."
+        ),
+        sections=[
+            ("Why a shared space",
+             "A shared space lets a text query match an image, or an image match a sound, "
+             "without any hand-built mapping between them. The model learns the alignment "
+             "from data, so a photo of a red bicycle and the phrase \"red bicycle\" end up "
+             "as neighbours."),
+            ("How the alignment is learned",
+             "Contrastive training does the work. The model is shown matched and mismatched "
+             "pairs and learns to pull matches together while pushing mismatches apart:\n\n"
+             "- Supervision comes from naturally occurring pairs, such as images and their captions.\n"
+             "- No manual labelling is needed, so the approach scales to hundreds of millions of pairs.\n"
+             "- The same recipe extends to audio, depth, and other modalities."),
+            ("Turning embeddings into search",
+             "At query time the system encodes the query with the same model and looks up "
+             "the closest vectors in an index. The quality of the embedding decides the "
+             "ceiling on relevance; the index decides how fast you reach it."),
+        ],
+    ),
+    Topic(
+        slug="video-retrieval",
+        title="Searching Video by Content, Not Tags",
+        tags=["AI", "Video"],
+        summary="Moving past manual tags to retrieve the exact moment inside a long video.",
+        prompt="How does content-based video retrieval work, so a natural-language query can find a specific moment inside a long video?",
+        intro=(
+            "Tag-based video search only finds what someone remembered to label. "
+            "Content-based retrieval indexes what is actually happening on screen, so a "
+            "query like \"the moment the belt began to slip\" can land on the right few "
+            "seconds of footage."
+        ),
+        sections=[
+            ("Frames are not enough",
+             "A single frame rarely captures an action. Useful video retrieval reasons over "
+             "short spans of time, so it can tell a hand reaching for a cup from a hand "
+             "setting one down."),
+            ("The pipeline",
+             "A practical system breaks the problem into stages:\n\n"
+             "- Sample frames and short clips at a sensible rate rather than every frame.\n"
+             "- Encode each clip into an embedding that captures motion and context.\n"
+             "- Index the embeddings so a text or image query retrieves the nearest clips.\n"
+             "- Re-rank the top candidates with a heavier model for precision."),
+            ("Where it pays off",
+             "Security review, industrial monitoring, and media archives all share the same "
+             "need: find a specific event in hours of footage without watching all of it."),
+        ],
+    ),
+    Topic(
+        slug="audio-event-search",
+        title="Audio Event Search Beyond Speech-to-Text",
+        tags=["AI", "Audio"],
+        summary="Indexing environmental sound so a failing part or an alarm becomes searchable.",
+        prompt="How can audio search index environmental and non-speech sounds so specific acoustic events become searchable?",
+        intro=(
+            "Speech-to-text answers only \"what was said\". A large share of useful signal in "
+            "audio is non-verbal: a bearing starting to grind, glass breaking, a specific "
+            "alarm. Audio event search indexes those sounds directly."
+        ),
+        sections=[
+            ("From waveform to embedding",
+             "Raw audio is turned into a time-frequency representation and encoded into "
+             "embeddings that capture the character of a sound rather than its transcript. "
+             "Similar sounds sit close together in the resulting space."),
+            ("What it unlocks",
+             "Treating sound as a first-class, searchable type enables:\n\n"
+             "- Retrieval of unique acoustic signatures, such as a failing mechanical part.\n"
+             "- Alignment of sound events with a visual timeline for review.\n"
+             "- Alerting when a known event recurs in a live stream."),
+            ("Keeping it robust",
+             "Real environments are noisy. Training on varied backgrounds and normalising "
+             "levels keeps retrieval stable when the same event is recorded in different places."),
+        ],
+    ),
+    Topic(
+        slug="edge-inference",
+        title="Running Multimodal Models at the Edge",
+        tags=["AI", "Edge"],
+        summary="Why physical systems push inference onto the device, and how models are shrunk to fit.",
+        prompt="Why is on-device (edge) inference necessary for physical AI, and what techniques shrink multimodal models to run locally?",
+        intro=(
+            "For a drone dodging an obstacle or a robot on a factory floor, a round trip to "
+            "the cloud is too slow. Edge inference runs the model on the device itself, "
+            "trading raw model size for latency, reliability, and privacy."
+        ),
+        sections=[
+            ("The case for local compute",
+             "Processing high-fidelity video and audio centrally is costly and slow, and it "
+             "fails the moment the network does. Local compute gives:\n\n"
+             "- Low latency for real-time decisions.\n"
+             "- Offline reliability, independent of connectivity.\n"
+             "- Privacy, by keeping sensitive feeds on the device."),
+            ("Making models fit",
+             "Quantisation, pruning, and distillation reduce a model's size and cost while "
+             "keeping most of its accuracy. Hardware-aware tuning then matches the model to "
+             "the accelerator it will actually run on."),
+            ("A tiered approach",
+             "Many systems keep a small, fast model on the edge for the common case and "
+             "escalate rare, hard inputs to a larger model when a connection is available."),
+        ],
+    ),
+    Topic(
+        slug="streaming-sensor-fusion",
+        title="Aligning Streaming Sensor Data in Real Time",
+        tags=["AI", "Streaming"],
+        summary="How real-time pipelines align feeds that arrive at different rates before analysing them.",
+        prompt="How do real-time pipelines align and fuse streaming sensor data that arrives at different rates for physical AI systems?",
+        intro=(
+            "A physical system is fed by a continuous tide of raw data: camera frames, "
+            "microphones, and sensors, all arriving at different rates. Making sense of it "
+            "starts with alignment, not analysis."
+        ),
+        sections=[
+            ("Different feeds, different clocks",
+             "Cameras, audio arrays, and sensors sample at their own speeds. Before anything "
+             "can be fused, timestamped feeds have to be aligned onto a common timeline."),
+            ("Building the pipeline",
+             "Robust streaming pipelines lean on a few ideas:\n\n"
+             "- Event-driven processing instead of fixed batches.\n"
+             "- Buffering and windowing to align feeds that drift apart.\n"
+             "- Smart filtering, so only high-value data triggers heavy computation or storage."),
+            ("Why filtering matters",
+             "Storing and processing everything is wasteful. Deciding early what deserves "
+             "attention keeps a real-time system affordable and fast."),
+        ],
+    ),
+    Topic(
+        slug="ann-indexing",
+        title="Approximate Nearest-Neighbour Indexing at Scale",
+        tags=["AI", "Search"],
+        summary="The indexing structures that keep vector search fast across billions of items.",
+        prompt="How does approximate nearest-neighbour indexing keep vector search fast and accurate across billions of embeddings?",
+        intro=(
+            "Once every document is an embedding, search is a nearest-neighbour problem. "
+            "Exact search over billions of vectors is too slow, so production systems use "
+            "approximate indexes that trade a little recall for a large speed-up."
+        ),
+        sections=[
+            ("The exact-search wall",
+             "Comparing a query against every vector does not scale. Approximate nearest-"
+             "neighbour (ANN) indexes narrow the search to a promising subset first."),
+            ("Common index families",
+             "A few structures dominate practical systems:\n\n"
+             "- Graph indexes such as HNSW, which walk a navigable small-world graph.\n"
+             "- Inverted-file and clustering methods that route a query to a few partitions.\n"
+             "- Product quantisation, which compresses vectors so more fit in memory."),
+            ("Tuning the trade-off",
+             "Every ANN index exposes a recall-versus-speed knob. The right setting depends "
+             "on how costly a missed result is against how fast the query must return."),
+        ],
+    ),
+    Topic(
+        slug="physical-ai-perception",
+        title="Perception Loops for Physical AI",
+        tags=["AI", "Physical AI"],
+        summary="How embedded systems perceive, retrieve context, and act inside a tight loop.",
+        prompt="How does a physical AI system close the loop from multi-sensory perception to retrieving context and acting in real time?",
+        intro=(
+            "Physical AI is intelligence embedded in machines that act in the real world. "
+            "Its defining trait is a tight loop: perceive through many senses, retrieve "
+            "relevant context, decide, and act, over and over."
+        ),
+        sections=[
+            ("Perception is multi-sensory",
+             "A machine on a factory floor does not rely on video alone. It combines visual "
+             "frames, temperature, and vibration to understand a situation more completely "
+             "than any single sense allows."),
+            ("Retrieval closes the loop",
+             "Multimodal search acts as the machine's memory. Faced with a new situation it "
+             "can:\n\n"
+             "- Match the current state against past events.\n"
+             "- Retrieve the context needed to interpret what it is seeing.\n"
+             "- Feed that context into a split-second decision."),
+            ("Latency sets the limit",
+             "Because the loop drives physical action, its speed is a hard constraint. This "
+             "is what pushes so much of the perception stack onto the edge."),
+        ],
+    ),
+    Topic(
+        slug="cross-modal-retrieval",
+        title="Cross-Modal Retrieval: Text-to-Image and Back",
+        tags=["AI", "Search"],
+        summary="Describing a concept in one modality and retrieving matches in another.",
+        prompt="How does cross-modal retrieval let a text query return images, or an image query return text, using shared embeddings?",
+        intro=(
+            "Cross-modal retrieval is multimodal search at its most direct: describe "
+            "something in text and get back matching images, or hand the system an image and "
+            "get back the text that describes it. One shared space makes both directions the "
+            "same operation."
+        ),
+        sections=[
+            ("One space, two directions",
+             "Because text and images live in the same embedding space, \"text finds image\" "
+             "and \"image finds text\" are the same nearest-neighbour query run from either "
+             "starting point."),
+            ("Where the gap shows",
+             "The alignment is imperfect, and a few problems recur:\n\n"
+             "- A modality gap can leave text and image vectors in slightly different regions.\n"
+             "- Fine-grained details, such as counting or exact spatial relations, are hard.\n"
+             "- Web-trained models inherit the biases of their data.\n"
+             "Re-ranking the top candidates with a joint model recovers much of the lost precision."),
+            ("Putting it to work",
+             "Visual product search, caption retrieval, and content moderation all reduce to "
+             "the same cross-modal lookup once the embeddings are in place."),
+        ],
+    ),
+]
+
+
+def all_topics() -> List[Topic]:
+    return list(TOPICS)
+
+
+def get_topic(slug: str):
+    for t in TOPICS:
+        if t.slug == slug:
+            return t
+    return None
+
+
+def select_topic(used_slugs, rotation_index: int) -> Topic:
+    """Pick the next topic to publish.
+
+    Prefer the first topic whose slug has not been published yet (keeps variety);
+    once every topic has appeared, rotate deterministically by `rotation_index` so the
+    cycle repeats in order rather than sticking on one topic."""
+    used = set(used_slugs or [])
+    for t in TOPICS:
+        if t.slug not in used:
+            return t
+    return TOPICS[rotation_index % len(TOPICS)]
diff --git a/requirements-dev.txt b/requirements-dev.txt
new file mode 100644
index 0000000..26b77f6
--- /dev/null
+++ b/requirements-dev.txt
@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..f229360
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1 @@
+requests
diff --git a/run_publish.py b/run_publish.py
new file mode 100644
index 0000000..d6a3096
--- /dev/null
+++ b/run_publish.py
@@ -0,0 +1,43 @@
+"""Entry point for the daily article publisher.
+
+Reads configuration from the environment, publishes one article (or, in dry-run mode,
+renders it without writing), logs a summary, and — when running in GitHub Actions —
+exposes the result as step outputs so the workflow can open a pull request.
+"""
+import logging
+import os
+import sys
+
+from publisher.config import load_config
+from publisher.publish import publish
+
+log = logging.getLogger("vmx_blog")
+
+
+def _write_outputs(result):
+    out = os.environ.get("GITHUB_OUTPUT")
+    if not out:
+        return
+    created = "true" if result.get("status") == "published" else "false"
+    with open(out, "a", encoding="utf-8") as fh:
+        fh.write(f"created={created}\n")
+        fh.write(f"slug={result.get('topic', '')}\n")
+        fh.write(f"title={result.get('title', '')}\n")
+        fh.write(f"filename={result.get('filename', '')}\n")
+        fh.write(f"branch={result.get('branch', '')}\n")
+
+
+def main():
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
+    config = load_config()
+    result = publish(config)
+    status = result.get("status")
+    log.info("status=%s topic=%s file=%s", status, result.get("topic"), result.get("filename"))
+    if status == "dry-run":
+        log.info("DRY RUN, would publish:\n%s", result.get("page_html", ""))
+    _write_outputs(result)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/test.sh b/test.sh
new file mode 100644
index 0000000..e479806
--- /dev/null
+++ b/test.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# Run the offline test suite. Usage: bash test.sh [pytest args]
+set -euo pipefail
+cd "$(dirname "$0")"
+python -m pytest -v "$@"
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_content.py b/tests/test_content.py
new file mode 100644
index 0000000..9f3ea1a
--- /dev/null
+++ b/tests/test_content.py
@@ -0,0 +1,61 @@
+"""Content generation: provider preference and safe fallback."""
+from publisher import content as content_mod
+from publisher import topics as topics_mod
+from publisher.config import Config
+
+TOPIC = topics_mod.get_topic("multimodal-embeddings")
+
+
+class FakeResp:
+    def __init__(self, payload):
+        self._payload = payload
+
+    def raise_for_status(self):
+        pass
+
+    def json(self):
+        return self._payload
+
+
+def test_prefers_brightdata_when_configured():
+    cfg = Config(brightdata_api_key="bd", serpapi_key="serp")
+
+    def fake_post(url, **kwargs):
+        return FakeResp([{"answer_text": "bright data answer"}])
+
+    def fake_get(url, **kwargs):
+        raise AssertionError("serpapi should not be called when brightdata answers")
+
+    body = content_mod.generate_article_body(TOPIC, cfg, get=fake_get, post=fake_post)
+    assert body == "bright data answer"
+
+
+def test_falls_back_to_serpapi_when_brightdata_empty():
+    cfg = Config(brightdata_api_key="bd", serpapi_key="serp")
+
+    def fake_post(url, **kwargs):
+        return FakeResp([{"unrelated": "no answer here"}])
+
+    def fake_get(url, **kwargs):
+        payload = {"ai_overview": {"text_blocks": [{"snippet": "serpapi answer"}]}}
+        return FakeResp(payload)
+
+    body = content_mod.generate_article_body(TOPIC, cfg, get=fake_get, post=fake_post)
+    assert body == "serpapi answer"
+
+
+def test_falls_back_to_topic_body_when_no_provider():
+    cfg = Config()  # no keys
+    body = content_mod.generate_article_body(TOPIC, cfg)
+    assert body == TOPIC.fallback_body()
+    assert "## Why a shared space" in body
+
+
+def test_provider_error_does_not_raise():
+    cfg = Config(brightdata_api_key="bd", serpapi_key="serp")
+
+    def boom(url, **kwargs):
+        raise RuntimeError("network down")
+
+    body = content_mod.generate_article_body(TOPIC, cfg, get=boom, post=boom)
+    assert body == TOPIC.fallback_body()
diff --git a/tests/test_index_update.py b/tests/test_index_update.py
new file mode 100644
index 0000000..a0dbbd1
--- /dev/null
+++ b/tests/test_index_update.py
@@ -0,0 +1,35 @@
+"""Inserting an article into index.html."""
+import pytest
+
+from publisher.index_update import insert_article, IndexFormatError
+
+INDEX = """<html><body>
+  <main>
+    <ul class="article-list">
+      <li>
+        <a href="articles/old.html">Old</a>
+      </li>
+    </ul>
+  </main>
+</body></html>"""
+
+
+def test_inserts_as_first_item():
+    li = '      <li>\n        <a href="articles/new.html">New</a>\n      </li>'
+    out = insert_article(INDEX, li, href="articles/new.html")
+    new_pos = out.find("articles/new.html")
+    old_pos = out.find("articles/old.html")
+    assert new_pos != -1 and old_pos != -1
+    assert new_pos < old_pos  # newest first
+
+
+def test_idempotent_when_href_present():
+    li = '      <li>\n        <a href="articles/old.html">Old</a>\n      </li>'
+    out = insert_article(INDEX, li, href="articles/old.html")
+    assert out == INDEX
+    assert out.count("articles/old.html") == 1
+
+
+def test_raises_when_list_marker_missing():
+    with pytest.raises(IndexFormatError):
+        insert_article("<html><body>no list here</body></html>", "<li/>")
diff --git a/tests/test_publish.py b/tests/test_publish.py
new file mode 100644
index 0000000..a7df1ee
--- /dev/null
+++ b/tests/test_publish.py
@@ -0,0 +1,83 @@
+"""End-to-end publish flow (offline, no network, injected clock)."""
+import os
+from datetime import datetime, timezone
+
+from publisher.config import Config
+from publisher.publish import publish
+
+DT = datetime(2026, 8, 7, tzinfo=timezone.utc)
+
+INDEX_TEMPLATE = """<!DOCTYPE html>
+<html lang="en">
+<body>
+  <main>
+    <h2>List of Blog Articles</h2>
+    <ul class="article-list">
+      <li>
+        <a href="articles/202601-physical-ai-search.html">The Physical AI Software Stack</a>
+        <div class="summary">Existing.</div>
+        <div class="meta">Jan 2026 &middot; AI &middot; Search</div>
+      </li>
+    </ul>
+  </main>
+</body>
+</html>
+"""
+
+
+def _setup(tmp_path):
+    articles = tmp_path / "articles"
+    articles.mkdir()
+    (articles / "202601-physical-ai-search.html").write_text("old", encoding="utf-8")
+    index = tmp_path / "index.html"
+    index.write_text(INDEX_TEMPLATE, encoding="utf-8")
+    return Config(articles_dir=str(articles), index_path=str(index))
+
+
+def test_dry_run_writes_nothing(tmp_path):
+    cfg = _setup(tmp_path)
+    cfg.dry_run = True
+    before_index = (tmp_path / "index.html").read_text(encoding="utf-8")
+    result = publish(cfg, now=DT)
+    assert result["status"] == "dry-run"
+    assert not os.path.exists(result["path"])
+    assert (tmp_path / "index.html").read_text(encoding="utf-8") == before_index
+    assert result["page_html"].startswith("<!DOCTYPE html>")
+
+
+def test_real_run_writes_article_and_updates_index(tmp_path):
+    cfg = _setup(tmp_path)
+    result = publish(cfg, now=DT)
+    assert result["status"] == "published"
+    # First run picks the first unused topic.
+    assert result["topic"] == "multimodal-embeddings"
+    assert result["filename"] == "20260807-multimodal-embeddings.html"
+    # Article file written with the template.
+    page = open(result["path"], encoding="utf-8").read()
+    assert page.startswith("<!DOCTYPE html>")
+    assert "Joint Embedding Spaces" in page
+    # Index links the new article, newest first.
+    index = (tmp_path / "index.html").read_text(encoding="utf-8")
+    new_pos = index.find("20260807-multimodal-embeddings.html")
+    old_pos = index.find("202601-physical-ai-search.html")
+    assert new_pos != -1 and new_pos < old_pos
+
+
+def test_second_run_same_day_is_idempotent(tmp_path):
+    cfg = _setup(tmp_path)
+    publish(cfg, now=DT)
+    index_after_first = (tmp_path / "index.html").read_text(encoding="utf-8")
+    result2 = publish(cfg, now=DT)
+    assert result2["status"] == "exists"
+    # No duplicate list entry.
+    index_after_second = (tmp_path / "index.html").read_text(encoding="utf-8")
+    assert index_after_second == index_after_first
+    assert index_after_second.count("20260807-multimodal-embeddings.html") == 1
+
+
+def test_forced_topic_slug(tmp_path):
+    cfg = _setup(tmp_path)
+    cfg.topic_slug = "edge-inference"
+    result = publish(cfg, now=DT)
+    assert result["topic"] == "edge-inference"
+    assert result["filename"] == "20260807-edge-inference.html"
diff --git a/tests/test_render.py b/tests/test_render.py
new file mode 100644
index 0000000..3866dcb
--- /dev/null
+++ b/tests/test_render.py
@@ -0,0 +1,56 @@
+"""HTML rendering matches the site template."""
+from datetime import datetime, timezone
+
+from publisher import render
+from publisher import topics as topics_mod
+
+DT = datetime(2026, 8, 7, tzinfo=timezone.utc)
+
+
+def test_body_html_headings_paragraphs_and_lists():
+    md = "Intro paragraph.\n\n## A Section\n\nSome text.\n\n- one\n- two\n\n### Sub\n\nMore."
+    html = render.render_body_html(md)
+    assert "<p>Intro paragraph.</p>" in html
+    assert "<h2>A Section</h2>" in html
+    assert "<h3>Sub</h3>" in html
+    assert "<ul>" in html and "<li>one</li>" in html and "<li>two</li>" in html
+
+
+def test_body_html_inline_markup_and_escaping():
+    md = "Use **bold**, *em*, and `code` with a < b & c."
+    html = render.render_body_html(md)
+    assert "<strong>bold</strong>" in html
+    assert "<em>em</em>" in html
+    assert "<code>code</code>" in html
+    assert "&lt; b &amp; c" in html
+    assert "< b & c" not in html
+
+
+def test_filename_uses_yyyymmdd_and_slug():
+    assert render.article_filename(DT, "edge-inference") == "20260807-edge-inference.html"
+
+
+def test_meta_line_month_and_tags():
+    assert render.meta_line(DT, ["AI", "Search"]) == "August 2026 &middot; AI &middot; Search"
+
+
+def test_article_page_has_template_scaffold():
+    topic = topics_mod.get_topic("edge-inference")
+    page = render.render_article_page(topic, "## Local compute\n\nBody.", DT)
+    assert page.startswith("<!DOCTYPE html>")
+    assert '<link rel="stylesheet" href="../style.css" />' in page
+    assert '<a href="../index.html">V-Modal AI Blog</a>' in page
+    assert '<a class="back-link" href="../index.html">' in page
+    assert f"<h1>{topic.title}</h1>" in page
+    assert "August 2026 &middot; AI &middot; Edge" in page
+    assert "&copy; 2026 VModal Blog" in page
+    assert "<h2>Local compute</h2>" in page
+
+
+def test_index_li_links_and_summary():
+    topic = topics_mod.get_topic("ann-indexing")
+    li = render.render_index_li(topic, DT, "20260807-ann-indexing.html")
+    assert '<a href="articles/20260807-ann-indexing.html">' in li
+    assert topic.title in li
+    assert f'<div class="summary">{topic.summary}</div>' in li
+    assert '<div class="meta">August 2026 &middot; AI &middot; Search</div>' in li
diff --git a/tests/test_topics.py b/tests/test_topics.py
new file mode 100644
index 0000000..4368cce
--- /dev/null
+++ b/tests/test_topics.py
@@ -0,0 +1,49 @@
+"""Topic catalogue and rotation."""
+from publisher import topics as topics_mod
+
+
+def test_slugs_are_unique_and_nonempty():
+    slugs = [t.slug for t in topics_mod.all_topics()]
+    assert all(slugs)
+    assert len(slugs) == len(set(slugs))
+
+
+def test_every_topic_has_title_tags_and_prompt():
+    for t in topics_mod.all_topics():
+        assert t.title.strip()
+        assert t.tags
+        assert t.prompt.strip()
+        assert t.summary.strip()
+
+
+def test_fallback_body_is_complete_markdown():
+    t = topics_mod.get_topic("multimodal-embeddings")
+    body = t.fallback_body()
+    assert body.startswith(t.intro.strip()[:20])
+    # Every section heading appears as a markdown h2.
+    for heading, _ in t.sections:
+        assert f"## {heading}" in body
+
+
+def test_select_prefers_first_unused_topic():
+    first = topics_mod.all_topics()[0]
+    chosen = topics_mod.select_topic(used_slugs=set(), rotation_index=0)
+    assert chosen.slug == first.slug
+
+
+def test_select_skips_used_topics():
+    all_t = topics_mod.all_topics()
+    used = {all_t[0].slug, all_t[1].slug}
+    chosen = topics_mod.select_topic(used_slugs=used, rotation_index=0)
+    assert chosen.slug == all_t[2].slug
+
+
+def test_select_rotates_when_all_used():
+    all_t = topics_mod.all_topics()
+    used = {t.slug for t in all_t}
+    chosen = topics_mod.select_topic(used_slugs=used, rotation_index=len(all_t) + 2)
+    assert chosen.slug == all_t[2].slug
+
+
+def test_get_topic_unknown_returns_none():
+    assert topics_mod.get_topic("does-not-exist") is None