Shared Research-Driven Blog Publishing (@theme-tools/blog)
Canonical skill for producing, verifying, rendering, and authoring reference-grade editorial articles across the Megabyte Labs ecosystem (theme.tools, ui.theme.tools, and adopting site repositories).
Ownership & Package Boundaries
- Shared Package (
@theme-tools/blogintheme.tools/packages/blog): Owns the 14 Zod v4 contracts (./schema), 15-idea topic strategy (./topic-strategy), DataForSEO v3 client and capture validator (./dataforseo), SSRF-safe evidence & citation ledger (./evidence), 30 visual applicationsE01–E30(./visuals), shared editorial components (./components), zero-editor-runtime static HTML renderer (./renderer), lazy-loaded Plate/Slate authoring shell (./editor), 9-stage editorial workflow & 12-check release gate (./workflow), 3-slot scheduler (./publishing), RBAC & OAuth/magic-link security (./auth), analytics (./analytics), and legacy MDX/HTML migration (./migration). - Component Workshop (
ui.theme.tools/apps/ui): Documents and exercises all shared blog components and adversarial edge-case fixtures (stories/BlogComponents.stories.tsx) across light and dark themes. - Adopting Site Repository (
apps/web): Owns tenant editorial charter,/blogand/blog/:slugroutes, Cloudflare Worker edge metadata/JSON-LD injection, RSS/sitemap generation, and role-gated lazy loading ofLazyPlateEditor.
Non-Negotiable Operational Defaults
- Three Daily Publishing Slots (Per Configured Site): Default schedule is
09:00,14:00, and19:00inAmerica/New_York(DST-aware UTC conversion viaresolveLocalSlotToUtc), backed by a minimum 6-article release-eligible ready buffer (I01–I06). Never multiply slots across unconfigured domains. - 2,000+ Substantive Editorial Words (
D01–D03): Every new generated article must contain at least 2,000 substantive editorial words (normally2,000–3,000, or>3,000when depth warrants). Navigation, bibliography, table cells, captions, code blocks, alt text, and boilerplate are excluded fromcomputeSubstantiveWordCount. Historical imported articles preserve their original length (H28). - ~12 Substantive Visual Placements (
E01–E30): Plan approximately 12 distinct visual placements (typically 8–12 approved custom images plus deterministic charts, comparison tables, interactive calculators, and authentic product captures). Never count crops or decorative dividers as original visuals. - Live or Valid Cached DataForSEO v3 Brief (
B01–B30): Production release requires a verifiedDataForSeoProviderCapture(isFixture: false). Fixture briefs permit local development and draft authoring but are hard-blocked byrunQualityAndReleaseGate(check #3). Treat keyword density strictly as an editorial diagnostic (0.4%–2.2%), never a mechanical stuffing target. - Claim-Level Evidence & Citations (
C01–C30): Every externally verifiable factual, numerical, benchmark, or pricing claim must map to an inspectedSourceVersionandEvidenceReferencevia an inlineCitationNode([n]) linking to the bottomBibliographyWidget. - Documented Review Policy (
I15–I17): Scheduled publishing requires an approvedReviewRecordmatching the site'sReviewPolicy(human_batch,automation_assisted, orauthorized_autonomous) bound to the exactcontentHash,bibliographyHash, andvisualSetHash. - Authentication vs. Authorization (
G04–G05,K01–K11): Sign-in via Google, GitHub, or email magic link identifies a user; only active site members withauthor,editor,publisher, orownerroles see the prominent+ New articlehomepage button or load the Plate/Slate editor chunk.
Mandatory 9-Stage Workflow for Every Article
Execute these stages in order and persist stage transitions in EditorialWorkflowLedger:
- Stage 1 — Charter & Budget Hydration: Load
SiteEditorialCharter, existing inventory, andMicroUsdBudgetManagerremaining daily/monthly micro-USD cap. - Stage 2 — 15-Idea Research Slate: Propose 15 distinct article candidates (
IdeaCandidateSchema) with reader problem, search intent, original contribution, evidence sources, visual opportunities, and overlap metrics. Rank viacomputeWeightedEditorialScoreand persist the decision record (A07–A10). - Stage 3 — Overlap Check & Atomic Reservation: Check candidate #1 against published, draft, scheduled, and reserved topics (
evaluateCandidateOverlap). Fall back to candidate #2..#15 if blocked, and atomically reserve viaAtomicTopicReservationStore(A11–A14). - Stage 4 — DataForSEO v3 Keyword & SERP Brief: Query DataForSEO Labs (
keyword_suggestions,related_keywords,bulk_keyword_difficulty,search_intent—omittinglocation_codeonsearch_intentperB08) and live Google Organic SERP (B09–B10). Build aKeywordBriefviabuildVerifiedDataForSeoBriefFromCapture. - Stage 5 — Primary Evidence & Claim Ledger: Fetch primary sources through
validateSafeExternalUrl(SSRF guard) andsanitizeRetrievedPassage(prompt-injection stripping). Record immutableSourceVersion,EvidenceReference, andClaimRecordentries. - Stage 6 — Visual Plan (
E01–E30): Plan ~12 visual placements across the 30 cataloged visual applications (VISUAL_APPLICATION_CATALOG), pairing custom brand art briefs (createBrandArtBrief) with deterministicFiniteChart,ComparisonTable,CalculatorBlock, and authentic captures. - Stage 7 — Canonical Plate Document Authoring: Write the 2,000–3,000+ word article directly as a
ValidatedPlateDocumentwithCitationNodeinline links, TL;DR answer card, worked examples, failure modes, and bottomBibliographyWidget. - Stage 8 — 12-Point Release Gate: Run
runQualityAndReleaseGateto verify schema validity,>= 2,000substantive words, non-fixture DataForSEO freshness, 100% claim/citation resolution, visual completeness, anti-slop writing quality, metadata parity, accessibility, andReviewRecorddigest match. - Stage 9 — Slot Assignment & Atomic Publish: Claim the next
America/New_Yorkslot (09:00,14:00,19:00), switch the immutablepublishedRevisionIdpointer atomically, run post-publish smoke checks, and emit sitemap/RSS updates.
Progressive-Disclosure References
Load only the reference file needed for your active stage:
references/topic-selection.md— 15-idea slate prompt, weighted scoring formula, overlap thresholds, and atomic reservation (A01–A30).references/dataforseo.md— DataForSEO v3 endpoint payloads,search_intentschema rules, SERP overlap clustering, caching TTLs, and micro-USD cost tracking (B01–B30).references/evidence-and-citations.md— URL canonicalization, SSRF & prompt-injection guards, claim ledger schema, inline[n]citations, and bibliography rendering (C01–C30).references/editorial-writing.md— 2,000+ substantive word counter exclusions, anti-padding & anti-slop rules, section rhythm, and E-E-A-T disclosures (D01–D30).references/visual-production.md— Catalog of all 30 visual applications (E01–E30), brand art briefs, model tier routing, chart accessibility, and authentic captures (E01–F30).references/plate-authoring.md— Canonical Plate/Slate node schemas, custom blocks,+ New articlehomepage button, lazy-loading boundary, and optimistic concurrency (G01–H30).references/publishing-operations.md— Three daily slots (09:00,14:00,19:00 America/New_York), 6-article buffer, RBAC matrix, OAuth/magic-link security, budgets, and rollbacks (I01–K30).references/examples.md— Golden 2,000+ word reference article specification vs. rejected padding/unverified-claim counterexample (L10–L11).requirement-manifest.json— Complete 360-item (A01–L30) machine-readable requirement trace.
Cross-Linked Canonical Skills (L14)
- Brand voice, anti-slop copy, and baseline SEO floors:
../23-content-seo/SKILL.mdand../09-brand-and-content-system/SKILL.md - Design tokens, OKLCH contrast, and component states:
../10-experience-and-design-system/SKILL.md - Site generation & Cloudflare Workers deployment:
../15-site-generation/SKILL.mdand../06-build-and-slice-loop/blog-and-content-engine.md