Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
4c80b27
refactor(pipeline): remove pauseForBrief so research always stops at …
snowopsdev Nov 10, 2026
2c55d30
fix(cms): recover content runs whose worker died
snowopsdev Nov 10, 2026
0b8473f
feat(pipeline): gate `pipeline run` on setup and register it as a loc…
snowopsdev Nov 10, 2026
0c0459b
fix(cms): normalise article slugs and make them unique
snowopsdev Nov 10, 2026
ade854a
fix(cms): clear stale publishAt on already-published articles
snowopsdev Nov 10, 2026
462983b
test(cms): expect the de-duplicated slug in the article event payload
snowopsdev Nov 10, 2026
80bcec0
fix(cms): say why a run lost its lease
snowopsdev Nov 10, 2026
8fef0e8
fix(pipeline): commit article writes only while the run owns its row
snowopsdev Nov 10, 2026
49ee574
fix(cms): release a stuck job only when recovery's own run transition…
snowopsdev Nov 10, 2026
07f0bec
fix(cms): fail a content run that errors before its worker claims it
snowopsdev Nov 10, 2026
966042c
fix(cms): keep de-duplicated article slugs clear of existing ones
snowopsdev Nov 10, 2026
842191b
fix: one tolerant mock/live rule that never throws at import
snowopsdev Nov 10, 2026
ab50dfa
fix(pipeline): leave a cost row for billed failures and name truncati…
snowopsdev Nov 10, 2026
8ca5d8a
fix(pipeline): stop an unreadable SERP before paying for corpus extra…
snowopsdev Nov 10, 2026
4d1d17a
fix(cms): correct the Claude Sonnet 5 catalog price to $2/$10
snowopsdev Nov 10, 2026
cf58a0e
test(pipeline): fix runMode test typing
snowopsdev Nov 10, 2026
b784068
fix(cms): default extraction and setup assist to the generate model
snowopsdev Nov 10, 2026
24edeb4
test(pipeline): match the MOCK_MODE problem wording
snowopsdev Nov 10, 2026
bf41bd0
fix(pipeline): create discovered topics under the run fence
snowopsdev Nov 10, 2026
cde431f
fix(pipeline): name an OpenAI refusal instead of reporting no text
snowopsdev Nov 10, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ SITE_URL=http://localhost:3000
SEED_ADMIN_PASSWORD=

# LLM API keys. Each live model id picks its API provider by prefix: claude-* ->
# Anthropic, gpt-* / o-numbered / chatgpt-* -> OpenAI. With MOCK_MODE=false every
# Anthropic, gpt-* / o-numbered / chatgpt-* -> OpenAI. With live mode every
# configured model must use an API-backed provider with its key set.
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
Expand All @@ -37,9 +37,11 @@ PIPELINE_MODEL_BRIEF_ANGLE=
# Admin topic-discovery fit labels only; not a content-run blocker. Same
# small-model default as the brief angles
TOPIC_RELEVANCE_MODEL=
# Brand-guide extraction. Blank: the generate model, so a workspace that writes
# with an OpenAI model is not asked for an Anthropic key
BRAND_VOICE_EXTRACT_MODEL=
# Drafts onboarding steps (audiences, positioning, evidence bank); falls back to
# BRAND_VOICE_EXTRACT_MODEL before the platform default
# BRAND_VOICE_EXTRACT_MODEL, then to the generate model
SETUP_ASSIST_MODEL=

# Ahrefs API key for keyword/SERP research
Expand All @@ -57,7 +59,10 @@ TARGET_DOMAIN=example.com
# These are also .env.example placeholders and are treated as unset.
COMPETITOR_DOMAINS=competitor-a.com,competitor-b.com

# When true, pipeline stages return canned responses instead of calling paid APIs
# true/1/yes: canned responses, no paid API calls. false/0/no: live. Unset or
# empty: live only when ANTHROPIC_API_KEY or OPENAI_API_KEY is set, else mock.
# Any other value runs mock and shows up as a problem in the admin. Nothing
# throws at start-up; live runs are refused until each model's key is set.
MOCK_MODE=true

# --- Information-gain policy -------------------------------------------------
Expand Down
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Everything that decides how Datum writes sits in the admin nav's **Setup** and *

- **Setup checklist** (`/admin/ops/setup`) — seven steps, and `/admin` keeps showing it until the four required ones are done and the workspace holds at least one piece. Four are required, and a content run refuses to start without them: a workspace with a target domain (`/admin/ops/setup/workspace`), an active brand voice, at least one active audience (`/admin/ops/setup/audiences`), and at least one template (`/admin/ops/templates`). Three are recommended: your positioning (`/admin/ops/setup/positioning`) and an evidence bank (`/admin/ops/setup/evidence`) change what a draft may claim, and **Models** (below) picks which model runs each stage. The workspace, audience and positioning steps each have **Draft with AI** and **Refine with AI**, and the evidence bank offers the assistant on two of its three tabs; every reply drafts one section of one asset, so you read it before accepting it. They work from your own site: **Fetch site pages** reads your home page and up to seven marketing pages linked from it. **Start with the demo workspace** fills every required and recommended step but Templates and Models with the Kettle & Burr home-espresso demo in one click. See [`docs/tenant-context.md`](docs/tenant-context.md).
- **Brand voice** (`/admin/ops/setup/brand-voice`) — a workspace-wide voice every generated title, description, FAQ, and body follows, layered on top of `docs/style-guide.md`. Set it up with a nine-step onboarding stepper or by uploading an existing brand guide (`.md`/`.txt`/`.pdf`/`.docx`) for one-call extraction into a draft you review before activating. An active voice is required for content runs. Seed a demo voice with `npm run seed -- --with-brand-voice`.
- **Models** (`/admin/globals/llm-settings`) — eleven choices: one for each of the eight pipeline stages that call a model (generate, fact check, qualitative review, claim extraction, information-gain judge, evidence verification, evidence check, brief angles), plus brand-voice extraction, the setup assistant, and admin topic relevance. Pick a model here, or leave it blank to fall back to the matching `PIPELINE_MODEL_*` / `BRAND_VOICE_EXTRACT_MODEL` / `SETUP_ASSIST_MODEL` env var, or to `claude-opus-5` if neither is set. Brief angles and topic relevance are the exception: unset, they use the small model of the generate model's provider (`claude-haiku-4-5`, or `gpt-5.4-mini` when generate is a `gpt-*` model). Each live model needs its provider's API key (`ANTHROPIC_API_KEY` for `claude-*`, `OPENAI_API_KEY` for `gpt-*`, `o`-numbered and `chatgpt-*` models) wherever that call runs; see the env var split below.
- **Models** (`/admin/globals/llm-settings`) — eleven choices: one for each of the eight pipeline stages that call a model (generate, fact check, qualitative review, claim extraction, information-gain judge, evidence verification, evidence check, brief angles), plus brand-voice extraction, the setup assistant, and admin topic relevance. Pick a model here, or leave it blank to fall back to the matching `PIPELINE_MODEL_*` / `BRAND_VOICE_EXTRACT_MODEL` / `SETUP_ASSIST_MODEL` env var, or to `claude-opus-5` if neither is set. Brief angles and topic relevance are the exception: unset, they use the small model of the generate model's provider (`claude-haiku-4-5`, or `gpt-5.4-mini` when generate is a `gpt-*` model). Brand-voice extraction and the setup assistant, unset, use the generate model itself. Each live model needs its provider's API key (`ANTHROPIC_API_KEY` for `claude-*`, `OPENAI_API_KEY` for `gpt-*`, `o`-numbered and `chatgpt-*` models) wherever that call runs; see the env var split below.
- **Sources** (`/admin/collections/evidence-sources`) and **Source review** (`/admin/ops/governance/source-review`) — Sources holds the domain rules you have already rated and is what scoring reads. Source review is the queue behind it: the domains the pipeline cited or saw ranking that nobody has rated yet. An unrated domain can't back a claim nobody else is making, so an article resting on one gets blocked; rate the ones you trust and the next run counts them. See [`docs/information-gain.md`](docs/information-gain.md).
- **Scoring policy** (`/admin/globals/information-gain-policy`) — the thresholds that decide whether a scored draft passes, needs revision, needs your call, or is blocked. Every run stamps the policy version onto the score it writes. See [`docs/information-gain.md`](docs/information-gain.md).
Delivery settings sit apart from all of that, because no run reads them: **Webhooks** (`/admin/globals/webhook-settings`) sends a signed `article.status_changed` POST on every status transition, falling back to `WEBHOOK_URL` and `WEBHOOK_SECRET`. Nothing is sent until both a URL and a secret resolve. See [`docs/operations.md`](docs/operations.md).
Expand Down Expand Up @@ -94,7 +94,7 @@ The seed creates this account for local development. Change its password before

### Pipeline mock mode

Mock mode needs no API keys. Set `MOCK_MODE=true`, as shown in `.env.example`, and Datum uses fixtures instead of calling Ahrefs or Anthropic.
Mock mode needs no API keys. Set `MOCK_MODE=true`, as shown in `.env.example`, and Datum uses fixtures instead of calling Ahrefs or Anthropic. `pipeline:run` obeys the same setup gate as the admin, so a fresh database needs a workspace first: `npm run seed -- --with-brand-voice` writes the demo one.

```bash
npm run pipeline:fetch -- --template Listicle --count 3
Expand All @@ -106,7 +106,7 @@ npm run pipeline:report -- --period week

`/admin` opens on the setup checklist and keeps showing it until the four required steps are done and the workspace holds at least one piece; the three recommended steps never block it. If you would rather look around first, **Start with the demo workspace** fills every required and recommended step but Templates and Models from the Kettle & Burr home-espresso fixtures in one click; it only ever fills what is still blank, so pressing it twice is safe. Templates are seeded. Missing live-provider keys show as a banner for whoever deploys — they never block an editor.

Then **New content** (`/admin/ops/new`) shows the same blockers as a notice if anything required is still missing; otherwise pick the kind of piece (a template card), say what it is about — suggested topics from Ahrefs, or a keyword you already know — and create it. Research starts on its own; the piece opens; when research is done a **brief** appears with the angle, audience and sections. Edit it, approve it, and Datum writes the draft, runs the checks and scores it. **Content** (`/admin/ops/content`) is the one list: every piece on a five-step stepper (Research → Brief → Writing → Review → Publish), who it is waiting on, and the one thing to do next. A stalled piece — waiting on a person rather than a run — carries a **Run next stage** button on its own page and a **Run** button on the board; select several and **Run selected** advances them together. Each of those queues the article as a `pipeline-runs` row, executed as a native Payload `content-run` task, so `npm run jobs:run --workspace cms` (or dev's in-process worker) is what actually processes it; a bar at the bottom of every admin page shows what the model is doing while a run is in flight. `pipeline:run` reaches the same stages directly from the CLI, outside that queue, and is no longer the only way to move a stalled piece forward. Live mode asks for a paid-provider confirmation before the expensive half starts.
Then **New content** (`/admin/ops/new`) shows the same blockers as a notice if anything required is still missing; otherwise pick the kind of piece (a template card), say what it is about — suggested topics from Ahrefs, or a keyword you already know — and create it. Research starts on its own; the piece opens; when research is done a **brief** appears with the angle, audience and sections. Edit it, approve it, and Datum writes the draft, runs the checks and scores it. **Content** (`/admin/ops/content`) is the one list: every piece on a five-step stepper (Research → Brief → Writing → Review → Publish), who it is waiting on, and the one thing to do next. A stalled piece — waiting on a person rather than a run — carries a **Run next stage** button on its own page and a **Run** button on the board; select several and **Run selected** advances them together. Each of those queues the article as a `pipeline-runs` row, executed as a native Payload `content-run` task, so `npm run jobs:run --workspace cms` (or dev's in-process worker) is what actually processes it; a bar at the bottom of every admin page shows what the model is doing while a run is in flight. `pipeline:run` reaches the same stages directly from the CLI, outside that queue, and is no longer the only way to move a stalled piece forward; it registers itself as a `cli` run under the same lock, so it refuses while another run is active, and admin and selected runs refuse the articles it is carrying until it finishes. Live mode asks for a paid-provider confirmation before the expensive half starts.

Local development runs all three job queues in process: `content` and `webhooks` every two seconds, `scheduled` every ten. Production intentionally disables in-process autorun, so a durable worker or scheduler has to invoke each one:

Expand All @@ -116,9 +116,9 @@ npm run jobs:webhooks --workspace cms # webhook deliveries
npm run jobs:scheduled --workspace cms # due publishes, daily suggestion scan
```

Each invocation of the first command processes one queued content run; schedule it repeatedly for continuous processing. Run the other two every minute or faster. Use these scripts, not a bare `payload jobs:run`: the Payload CLI does not set `NODE_ENV`, and without `NODE_ENV=production` it runs the development schema push against your database on every invocation. The scripts turn that push off. [`docs/operations.md`](docs/operations.md) has the cadence, the delivery contract and the fixed limits.
Each invocation of the first command processes one queued content run; schedule it repeatedly for continuous processing. Run the other two every minute or faster: the `scheduled` queue also runs `recover-stale-runs`, which fails a run whose worker stopped sending heartbeats for 15 minutes and frees the content queue behind it. Use these scripts, not a bare `payload jobs:run`: the Payload CLI does not set `NODE_ENV`, and without `NODE_ENV=production` it runs the development schema push against your database on every invocation. The scripts turn that push off. [`docs/operations.md`](docs/operations.md) has the cadence, the delivery contract and the fixed limits.

For live API calls, set `MOCK_MODE=false` and provide the key for each chosen model's provider (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`). Ahrefs also needs `AHREFS_API_KEY` plus a target domain and competitors, which come from the **Workspace** setup page (`/admin/ops/setup/workspace`); `TARGET_DOMAIN` and `COMPETITOR_DOMAINS` are its fallback. See [`.env.example`](.env.example).
For live API calls, set `MOCK_MODE=false` and provide the key for each chosen model's provider (`ANTHROPIC_API_KEY` or `OPENAI_API_KEY`). The admin and the pipeline share one rule for mock versus live and never fail to start because of it: with `MOCK_MODE=false` and a missing key the admin stays up, the setup banner lists the key, and a run is refused until it is set. Admin-side model calls (brand-voice extraction, setup assistant, topic fit) follow the workspace mode and, live without that model's key, fail naming the key rather than returning demo data. Ahrefs also needs `AHREFS_API_KEY` plus a target domain and competitors, which come from the **Workspace** setup page (`/admin/ops/setup/workspace`); `TARGET_DOMAIN` and `COMPETITOR_DOMAINS` are its fallback. See [`.env.example`](.env.example).

## Environment variables

Expand All @@ -136,11 +136,11 @@ Copy [`.env.example`](.env.example) and [`cms/.env.example`](cms/.env.example)
| `TOPIC_RELEVANCE_MODEL` | CMS-only audience-fit labels for topic discovery; no CLI scoring or content-run key requirement. |
| `TARGET_DOMAIN` | Fallback for the Workspace global's target domain. The admin field wins; a mock run falls back again to a demo domain. The `.env.example` placeholder (`example.com`) is treated as unset rather than a real domain. |
| `COMPETITOR_DOMAINS` | Comma-separated fallback for the Workspace global's competitor list, same rule. The `.env.example` placeholders (`competitor-a.com`, `competitor-b.com`) are likewise treated as unset. |
| `MOCK_MODE` | `true` to use fixtures instead of paid APIs |
| `MOCK_MODE` | `true` to use fixtures instead of paid APIs, `false` for live. Unset, it is live only when `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` is set. An unrecognised value runs mock and is reported as a setup problem |
| `SEED_ADMIN_PASSWORD` | Password for the seeded admin user |
| `PIPELINE_MODEL_GENERATE` / `_FACT_CHECK` / `_QUALITATIVE_REVIEW` / `_CLAIM_EXTRACTION` / `_INFORMATION_GAIN_JUDGE` / `_EVIDENCE_VERIFICATION` / `_EVIDENCE_CHECK` / `_BRIEF_ANGLE` | Fallback model for each of the eight pipeline stages that call a model, when the [Models](#setup-and-governance) admin field is blank |
| `BRAND_VOICE_EXTRACT_MODEL` | Fallback model for brand-guide upload extraction, same rule |
| `SETUP_ASSIST_MODEL` | Fallback model for the setup assistant. Falls back to `BRAND_VOICE_EXTRACT_MODEL` before the platform default. |
| `BRAND_VOICE_EXTRACT_MODEL` | Fallback model for brand-guide upload extraction, same rule. Unset, the generate model |
| `SETUP_ASSIST_MODEL` | Fallback model for the setup assistant. Falls back to `BRAND_VOICE_EXTRACT_MODEL`, then the generate model. |
| `INFORMATION_GAIN_*` | Threshold overrides used when the Scoring policy global is blank. See [`docs/information-gain.md`](docs/information-gain.md). |
| `WEBHOOK_URL` / `WEBHOOK_SECRET` | Fallback for the Webhooks global. Nothing is delivered until both resolve. See [`docs/operations.md`](docs/operations.md). |
| `PAYLOAD_AUTO_LOGIN` (cms/.env only) | `true` to skip the admin login form in local dev; never honoured when `NODE_ENV=production` |
Expand All @@ -165,7 +165,7 @@ For running the test suites. Set these in your shell, not in a committed `.env`.
| `npm run dev` | CMS Next.js dev server |
| `npm run seed` | Create or update templates, evidence-source rules, and the admin user. Add `-- --with-brand-voice` to also seed the Kettle & Burr home-espresso demo workspace: an active brand voice, the workspace profile, two audiences, a position, and an evidence bank. |
| `npm run pipeline:fetch -- --template NAME_OR_ID` | Create templated articles from content-gap keywords |
| `npm run pipeline:run` | Advance every eligible article one stage set: research (stops at the brief), then generate → QA → scoring for approved briefs |
| `npm run pipeline:run` | Advance every eligible article one stage set: research (stops at the brief), then generate → QA → scoring for approved briefs. Refused until setup is finished or while another run is active |
| `npm run pipeline:report` | Print the QA and spending report |
| `npm run jobs:run --workspace cms` | Process one queued content run. The production content worker. |
| `npm run typecheck` / `lint` / `test` | Workspace checks described in [CONTRIBUTING.md](CONTRIBUTING.md) |
Expand Down
6 changes: 4 additions & 2 deletions cms/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ NODE_OPTIONS="--no-deprecation --no-experimental-strip-types"
# BRAND_VOICE_EXTRACT_MODEL, SETUP_ASSIST_MODEL, WEBHOOK_URL, WEBHOOK_SECRET,
# SITE_URL, and the INFORMATION_GAIN_* fallbacks (admin-queued runs score in
# this process; they are listed in the root .env.example).
# See the root .env.example for what each does.
# See the root .env.example for what each does. MOCK_MODE: true or false (unset
# is live only when a provider key is set; an unrecognised value runs mock).
MOCK_MODE=true
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
Expand All @@ -39,8 +40,9 @@ PIPELINE_MODEL_EVIDENCE_CHECK=
PIPELINE_MODEL_BRIEF_ANGLE=
# Admin topic-discovery fit labels only; same small-model default
TOPIC_RELEVANCE_MODEL=
# Blank: the generate model
BRAND_VOICE_EXTRACT_MODEL=
# Falls back to BRAND_VOICE_EXTRACT_MODEL when blank
# Falls back to BRAND_VOICE_EXTRACT_MODEL, then the generate model, when blank
SETUP_ASSIST_MODEL=
# Status-event webhooks. Fallbacks for the Webhooks global (/admin/globals/webhook-settings);
# nothing is delivered until both a URL and a secret resolve. See docs/operations.md.
Expand Down
8 changes: 7 additions & 1 deletion cms/src/collections/Articles.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import {
invalidateStaleInformationGain,
} from '../lib/articleReviewGate'
import { stampPublication } from '../lib/articlePublication'
import { uniqueArticleSlug } from '../lib/articleSlug'

/**
* Shown on every field in `SCORED_CONTENT_FIELDS` that an editor can reach in
Expand All @@ -27,6 +28,9 @@ const SCORED_FIELD_DESCRIPTION =
export const Articles: CollectionConfig = {
slug: 'articles',
hooks: {
// Before validation, so the unique index only ever sees a normalised slug
// that is already free.
beforeValidate: [uniqueArticleSlug],
// `gateArchivedStatus` runs first: an archived piece refuses every move,
// so nothing below needs to reason about one. Then
// `invalidateStaleInformationGain`, because it is a *dependency*:
Expand Down Expand Up @@ -84,8 +88,10 @@ export const Articles: CollectionConfig = {
admin: { description: SCORED_FIELD_DESCRIPTION },
},
{
// Normalised and de-duplicated by `uniqueArticleSlug`; the index makes a
// duplicate that slips past it (two concurrent writes) an error.
name: 'slug',
index: true,
unique: true,
type: 'text',
},
{
Expand Down
Loading
Loading