# EXPLAINERS + GUIDES (one run, then exit)

Job: publish 2 to 3 evergreen pages per run that each answer one question people actually search for. Site only: these never go to X, LinkedIn or dev.to.

Why: one data article brought 259 of 677 weekly visitors, and search became the second biggest referrer. Every evergreen page that answers a real question is another door from Google, Bing, DuckDuckGo and AI answer engines.

## What a page is
- Explainer (/explainers/<slug>/): answers ONE question ("why are crates.io download counts inflated"). 600 to 1,500 words. Opens with "Short answer:" (2 to 3 sentences), then a "Key numbers" or "Key facts" table (What | Number | Source), the explanation, "Common misconceptions" (each one: the claim in bold quotes, then the record), an optional "Our take" labeled as opinion, and Related links.
- Guide (/guides/<slug>/): a how-to. Front matter `steps` (3+), `time` (hands-on minutes) and `needs` (what the reader must have before step 1). Headings `## Step N: title` for every step. A `## What goes wrong` section for the errors people hit.

## Cadence
- Hourly, 2 to 3 pages per run, hard cap 30 a day (count today's site-explainer and site-guide entries in posts.json).
- Never pad to hit a count. Search engines demote sites that mass-produce thin pages, and that would cost the traffic this section exists for. No near-duplicates.

## Where topics come from
1. Every published article: each has 3 to 10 sub-questions worth their own page. The article links to each explainer inline; each explainer links back and to 2+ siblings.
2. The articles being written today.
3. Our own projects: the steps, commands and screenshots already exist in notes and repos.
4. Keep QUEUE.md (topic | type | search phrase checked with autocomplete | parent article | status). Refill it every run so it always holds 20+.

## Quality bar
- Every fact true, current, dated and linked to a primary source. Disproven claims get a myth-check: state the claim, show the record, say what part is true.
- One real search phrase per page (autocomplete check). Title about 60 chars, description 140 to 160 chars, no em dashes.
- Hero image plus at least 2 more visuals: our own screenshots, charts from the data, diagrams, or freely licensed photos credited and linked under the image. Never present a generated image as a real photo. No personal data in screenshots.
- At least 3 internal links and one matching offer or free tool where it genuinely fits.
- FAQPage JSON-LD on explainers, HowTo structure on guides.
- Economics or market pages say "not financial advice" once.

## Publishing
- Staged pages go in agents/explainers/staging/<slug>/ with front matter the importer expects; run the importer's --check first. sources.md holds public links only (no local paths, no private emails).
- Batch the run's pages into ONE build and deploy. Take the site build lock, follow SITE_PUBLISH.md, ping IndexNow, verify 200 + listed on the section index + in the sitemap.
- Log each in posts.json (platform site-explainer or site-guide, ts, url, kw, words) and mark it done in QUEUE.md.
- Finish with the titles, URLs, word counts and today's count.

Never sign out, never hunt for credentials, never close tabs you did not open.