seedproject-web/agents/README.md

Comiida Content Pipeline

An agentic pipeline that plans a 3-month editorial calendar and drafts one SEO/EEAT restaurant article per day (English, for Medellín expats/tourists) with an AI cover image, queued for human approval before going live on the Astro site.

Engine: headless Claude Code (claude -p) + Higgsfield image MCP (authenticated at the claude.ai level — reachable headless, confirmed). See the design at /root/.claude/plans/init-elegant-giraffe.md.

Layout

• config.json — site, author, models, image, editorial mix/word-counts.
• .env — optional secrets (git-ignored). None required today (Higgsfield auth is global).
• prompts/ — system prompts: research.system.md, writer.system.md, image.md.
• scripts/ — research.mjs, write-daily.mjs, list-drafts.mjs, approve.mjs, lib/.
• calendar.json — the generated editorial calendar (created by research.mjs).
• drafts/<slug>/ — pending drafts (index.mdx, cover.jpg, sources.json).
• run.sh — cron-safe wrapper (sets PATH, loads .env).

Setup (one-time)

1. Add the real author to app/src/lib/blog-data.js and set author.slug/name in config.json to match (EEAT requires a real byline).
2. Image generation needs no key — it uses the Higgsfield claude.ai MCP. Check credits with the balance tool if generations start failing.

Usage

# Plan ~3 months (writes calendar.json). Default days = config.editorial.calendarDays.
./run.sh research.mjs [days]

# Draft the next due article into drafts/<slug>/ (auto-runs the SEO audit after).
./run.sh write-daily.mjs [slug]

# SEO Specialist audit (EEAT / spam-policy / on-page / AEO / readability).
# Writes <postDir>/seo-review.json. Default audits the draft; --published audits the live post.
./run.sh seo-review.mjs <slug> [--published]

# Auto-revise a failing draft until it passes the SEO gate (or maxReviseAttempts).
./run.sh revise.mjs <slug>

# News radar — discover timely Medellín food news/events → news-queue.json.
# (also runs automatically inside write-daily, once per day)
./run.sh news-radar.mjs

# Research — top up the evergreen backlog (additive merge into calendar.json).
# (also runs automatically inside write-daily when the planned backlog is low)
./run.sh research.mjs [count]

# Review the queue, then publish one manually (SEO-gated; --force overrides).
node scripts/list-drafts.mjs
./run.sh approve.mjs <slug> [--force]   # moves into the blog, builds, goes live

# Randomized auto-publisher (cron). Publishes ONE SEO-passing draft per day at a random time.
./run.sh publish-tick.mjs [--now]       # --now ignores the time gate (for testing)

Scheduling (managed in the aaPanel Cron UI; server clock is UTC)

Only two jobs are scheduled — research is now demand-driven (see below), not a cron.

0 11 * * *   run.sh write-daily.mjs    # daily 11:00 UTC (06:00 Bogotá) — news scan + refill + draft + SEO audit
*/15 * * * * run.sh publish-tick.mjs   # every 15m — publish 1 passing draft in the morning (random timestamp)

(aaPanel runs these in UTC; publish-tick computes its Bogotá floor time internally.)

Evergreen backlog is demand-driven (no monthly cron)

research.mjs is additive — it proposes evergreen topics and merges new ones into calendar.json (deduped, dates auto-assigned). write-daily auto-refills when the planned backlog drops below editorial.refillThreshold (guarded once/day), so the calendar stays stocked without thinking in "months." Run manually any time: ./run.sh research.mjs [count].

Concurrency safety

All calendar.json writes go through lib/calendar.mjs — an exclusive lockfile plus atomic read-modify-write (updateEntry/addEntry/mergeEntries). This prevents the lost-update race where a long write-daily run could clobber concurrent publish-tick / research writes.

Auto-publish: morning go-live, randomized timestamp (config.json → publish)

Posts go live in the morning (not a random hour all day), but each is stamped with a random earlier-today timestamp so published times aren't a fixed-minute fingerprint:

• 06:00 write-daily.mjs drafts the day's topic, runs the SEO audit, and auto-revises.
• publish-tick.mjs (every 15 min) publishes one SEO-passing draft on the first tick after the publish.notBefore floor (default 07:00 Bogotá — a buffer so the morning's fresh/news article is the one that goes live). The post's date is set to a random time between midnight and the publish moment (randomTimestampTodaySoFar — varied but never future). News drafts fast-track ahead of evergreen. One publish/day; idempotent; SEO-failing drafts wait for manual review. State in state/publish-YYYY-MM-DD.json.
• Set publish.auto=false to disable auto-publish and use manual approve.mjs.

Admin dashboard (read-only)

A small Node service (admin/server.mjs, no deps) shows the week's scheduled topics, the draft queue (with cover + preview), and the full calendar.

• Served at https://comiida.com/admin?key=<ADMIN_TOKEN> (Apache proxies /admin → 127.0.0.1:3010; token is in .env). A valid ?key= sets a 30-day cookie.
• Kept alive by supervisor: program comiidaAdmin (/www/server/panel/plugin/supervisor/profile/comiidaAdmin.ini). Manage with: supervisorctl -c /etc/supervisor/supervisord.conf {status|restart|stop} comiidaAdmin:comiidaAdmin_00.
• Read-only by design — approving still happens via ./run.sh approve.mjs <slug>.

Daily news radar (timely news/events)

scripts/news-radar.mjs + prompts/news-radar.system.md discover time-sensitive Medellín food items (openings/closings, festivals/events, awards, press) via WebSearch → news-queue.json (deduped vs published + calendar; stale fresh items pruned past news.recencyDays).

• Runs automatically at the start of write-daily.mjs, guarded once/day via state/news-YYYY-MM-DD.json (so the hourly test cron doesn't re-scan).
• News-first selection: the writer prefers the freshest queue item (by freshnessScore), injects it into calendar.json as a news:true entry, and drafts it; on a quiet day it falls back to the next evergreen calendar topic.
• Fast-track publishing: publish-tick.mjs releases news:true drafts before evergreen ones (still 1/day, still SEO-gated, still randomized timestamp) — so timely pieces go live the same day.
• Config: config.json → news { enabled, recencyDays, maxPerScan }.

Auto-revise loop

When a fresh draft fails the SEO gate, write-daily automatically runs scripts/revise.mjs: it feeds the audit's blocking + topFixes back to the writer (prompts/reviser.system.md), which edits the draft in place (finding real sources via WebSearch for uncited claims — never fabricating), then re-audits. Repeats until pass or seo.maxReviseAttempts (config). Config: seo.autoRevise, seo.maxReviseAttempts. Verified: a draft at fail/82 → pass/90 in one pass.

SEO Specialist agent

scripts/seo-review.mjs + prompts/seo-review.system.md audit an article across five weighted dimensions — EEAT (30), spam-policy compliance (20), on-page SEO (25), AEO/answer- engine (15), readability (10) — and write seo-review.json with per-dimension scores, a verdict (pass/revise/fail), blocking issues, and a ranked fix list.

• Runs automatically at the end of write-daily.mjs (verdict also stored on the calendar entry).
• Gates approve.mjs: approval is blocked when verdict==="fail" or overall < seo.minScore (config; default 85). Override with approve.mjs <slug> --force.
• Verdict + scores + fixes show in the /admin dashboard (draft cards and the draft preview).
• Reviewer model: models.reviewer in config.json.

EEAT guardrails (enforced in prompts)

Data-driven only; every claim cited; no fabricated first-person dining; real author byline; honest "AI-generated illustration" image credit.