---
name: opencm_blog
description: Plan, generate (FR + 4 translations), publish atomically, and verify OpenCM blog articles with immediate error reporting.
version: 4.0.0
author: Remi + Hermes
license: MIT
metadata:
  hermes:
    tags: [blog, opencm, publishing, seo, api, translations, multilingual]
prerequisites:
  files:
    - ~/.hermes/.env
---

# OpenCM Blog Publisher

Manage articles for `opencm.eu` using the **real** API spec. Every article is published in French (canonical) + EN, ES, IT, DE in a single atomic POST.

## Hard rules

1. Never claim success unless `POST` returned `201` AND `GET /api/articles/{slug}/fr` confirms the article.
2. Report every error immediately with the exact code and message.
3. Never reuse a burned slug — generate a fresh one.
4. `sourceLang: "fr"` must be set on every article.
5. Translations go into the `translations` field of the POST body — not separate PUTs.

## Publish workflow (per article)

1. Load today's entry from the weekly calendar JSON.
2. Verify slug is not already taken (regenerate if needed using keyword, not title).
3. Generate canonical French article via LLM (min 900 words, SEO structure).
4. Generate EN + ES + IT + DE translations in **one LLM call**.
5. **One POST** with `sourceLang`, `translations`, and all canonical fields.
6. Verify via `GET /api/articles/{slug}/fr` (O(1), not a full list scan).
7. Update calendar entry status + save JSON + re-render Markdown.
8. Send Telegram with full report including per-language translation status.

## API endpoints used

| Method | Path | When |
|---|---|---|
| `GET` | `/api/articles` | Weekly calendar — get taken slugs |
| `POST` | `/api/articles` | Publish article + all translations |
| `GET` | `/api/articles/{slug}/fr` | Post-creation verification |
| `PUT` | `/api/articles/{slug}/{lang}` | Manual translation fix only |

## Key API constraints (from spec)

- `slug`: lowercase-kebab-case, ≤ 120 chars, globally unique — **burned on first use**.
- `keywords`: max 30 entries, each ≤ 80 chars.
- `title`: ≤ 300 chars. `description`: ≤ 600 chars.
- `translations.<lang>`: needs all 3 of `title`, `description`, `content`.
- Do NOT include `sourceLang` as a translation key (API returns 409).
- `409` on slug = burned, generate new one — **never retry same slug**.

## SEO keyword pool

130+ keywords organized across 9 categories. Scripts rotate through them weekly, skipping keywords whose slug matches an existing article.

Categories in use: `Guide` · `Business` · `Produit` · `Tutoriel` · `Actus`

Key topics: alternatives (Hootsuite, Loomly, Planable, Agorapulse, Buffer…), white-label, portail client, tarifs freelance, calendrier éditorial, automatisation, gestion Instagram/LinkedIn/Facebook/TikTok, reporting, analytics, lancer agence CM.

## Runtime files

| File | Location |
|---|---|
| `common.py` | `~/blog-automation/common.py` |
| `generate_weekly_calendar.py` | `~/blog-automation/generate_weekly_calendar.py` |
| `publish_daily_article.py` | `~/blog-automation/publish_daily_article.py` |
| Weekly calendar (JSON) | `~/.hermes/data/opencm_blog/weekly-calendar-YYYY-MM-DD.json` |
| Weekly calendar (MD) | `~/.hermes/data/opencm_blog/weekly-calendar-YYYY-MM-DD.md` |
| Logs | `~/.hermes/data/opencm_blog/*.log` |

## Cron schedule

```
0 9 * * 0   generate_weekly_calendar.py   # Every Sunday 09:00
0 11 * * *  publish_daily_article.py      # Every day 11:00
```

## Required env vars (`~/.hermes/.env`)

- `OPENCM_BLOG_API_TOKEN` — Bearer token
- `TELEGRAM_BOT_TOKEN` + `TELEGRAM_HOME_CHANNEL` — for alerts
- `OPENAI_API_KEY` — fallback LLM when OpenIntelligence is unavailable

## Manual commands

```bash
# Generate this week's calendar now
python3 ~/blog-automation/generate_weekly_calendar.py

# Publish today's article now
python3 ~/blog-automation/publish_daily_article.py

# View logs
tail -50 ~/.hermes/data/opencm_blog/daily-publish.log
tail -20 ~/.hermes/data/opencm_blog/weekly-calendar.log
```