ContentEngine — Technical Addendum #2

Content Type Templates, Schema Library, Refresh System & Validation Architecture

Field	Value
Author	Alton Wells
Date	March 2026
Status	Draft for Review
Parent Spec	ContentEngine Technical Specification v3
Depends On	Addendum #1 (LangExtract Implementation)
Scope	Content type definitions, structural templates, JSON-LD schema library, author entity specs, refresh queue system, SEO validation engine v2

1. Purpose & Scope

This addendum defines the complete content production framework for ContentEngine: what content types the system produces, how each type is structurally templated, what schema markup each type carries, how content freshness is managed, and how the SEO validation engine enforces quality at the deployment gate.

1.1 What This Addendum Covers

Eight content type definitions with structural templates, required elements, and SEO rules
Complete JSON-LD schema library mapped per content type
Author entity specifications for three authors (Alton, Stan, Auctor)
Organization entity specification for Consul
Refresh queue system: scoring model, tiers, calendar integration, 90-day evaluation cycle
SEO Validation Engine v2: BLOCKING/WARNING/INFO severity tiers with 16 checks
Content depth validation check (brief-to-draft structural coverage)
Historical validation score tracking schema

1.2 What This Addendum Does Not Cover

Topic cluster definitions (deferred until competitive analysis is complete)
Image generation pipeline (manual placement for MVP; pipeline is a future addendum)
Agent prompt engineering (separate addendum)
Filesystem-as-context architecture (deferred per parent spec)

1.3 Industry Context

Consul is a B2B SaaS AI executive assistant targeting CEOs and founders at a $200/month price point. Content must build trust with high-ticket decision-makers. The vertical is "AI productivity / executive operations" — not YMYL, but E-E-A-T signals are critical because the buyer is sophisticated and skeptical. Schema strategy reflects this: we optimize for commercial intent SERPs, AI Overview citations, and authority signals.

2. Content Type Registry

ContentEngine produces eight content types. Each type has a distinct structural template, schema mapping, internal linking profile, image density rule, and refresh cadence.

2.1 Type Overview

Type ID	Type Name	Build Pattern	Typical Length	Primary Schema	Refresh Cadence
`blog_post`	Blog Post	Recurring production	1,500–2,500 words	`BlogPosting`	90-day evaluation
`listicle`	Listicle	Recurring production	1,500–3,000 words	`Article` + `ItemList`	90-day evaluation
`guide`	Comprehensive Guide	Recurring production	3,000–5,000 words	`Article` (long-form)	90-day evaluation
`how_to`	How-To / Tutorial	Recurring production	2,000–4,000 words	`HowTo`	90-day evaluation
`comparison`	Comparison	Recurring production	2,000–4,000 words	`Article` + `ItemList` or `Product`	90-day evaluation
`case_study`	Case Study	Irregular, customer-driven	1,500–2,500 words	`Article` + `Review`	Annual
`pillar`	Pillar / Hub Page	One-time per cluster	2,500–4,000 words	`CollectionPage`	Quarterly
`glossary`	Glossary / Definition	One-time batch	500–1,200 words	`DefinedTerm` + `FAQPage`	Only when definitions evolve

2.2 Comparison Sub-Variants

The comparison type covers two structural variants. The Brief Agent specifies which variant applies based on the target keyword.

Variant	Trigger Keywords	Structure	Schema
Head-to-Head ("vs")	"X vs Y", "X alternative", "X compared to Y"	Two-option deep comparison with criteria matrix	`Article` with embedded `Product` entities using `isSimilarTo`
Roundup	"Best X tools", "Top X for Y", "X options for Y"	Multi-option ranked list with per-option sections	`Article` + `ItemList` with `ListItem` entries

3. Content Type Template Specifications

Each content type has a required structural scaffold. The Writer Agent must follow this scaffold exactly. The SEO Validation Engine checks structural compliance.

3.1 Blog Post (`blog_post`)

Purpose: Topical authority pieces targeting informational and commercial-informational keywords. The workhorse content type.

Target length: 1,500–2,500 words

Required structural scaffold:

# [H1: Title containing primary keyword]

[TL;DR Box: 3-5 bullet point key takeaways in a styled callout.
 Maps to `speakable` schema. First bullet answers the core question directly.
 Total length: 80-120 words.]

[Hero image: AI-generated, contextually relevant to topic]

[Opening paragraph: 2-3 sentences. Primary keyword in first sentence.
 Establishes the problem or question. Hooks the reader.]

## [H2: Section 1 — secondary keyword or subtopic]

[2-4 paragraphs, 200-400 words per section]
[IMAGE marker if section exceeds 400 words]
[Internal link within contextual sentence]

## [H2: Section 2]
...

## [H2: Section N — typically 4-6 H2 sections total]

### [H3 subsections as needed — no H3 without parent H2]

## Frequently Asked Questions

[Minimum 3 Q&A pairs. Questions sourced from PAA extraction data
 in the content brief. Each answer: 2-4 sentences, concise,
 citation-ready for AI engines.]

### [Q1: Question text as H3]
[Answer paragraph]

### [Q2]
...

## [Closing section: Summary, next steps, or CTA]

[Final paragraph with internal link to related pillar or guide content]

SEO rules specific to blog posts:

Internal links: minimum 1 per 400 words, minimum 4 total
External links: minimum 1 authoritative source
Image density: minimum 3 images (hero + 2 body), 1 per 800 words
FAQ: required, minimum 3 Q&A pairs
ToC: required if word count exceeds 1,500 words
Primary keyword density: 0.8%–2.0%

3.2 Listicle (`listicle`)

Purpose: High-shareability content targeting "best of," "top N," and curated list queries. Strong for backlink acquisition and social distribution.

Target length: 1,500–3,000 words (scales with list size)

Required structural scaffold:

# [H1: "N [Noun] for [Audience/Use Case]" or "Top N [Things]"]

[TL;DR Box: Numbered quick-pick list (top 3-5 from the full list)
 with one-sentence reason per pick. Maps to `speakable`.]

[Hero image]

[Opening paragraph: Why this list matters. What criteria were used.
 Primary keyword in first sentence.]

## [Table of Contents — auto-generated, anchor-linked]

## [H2: 1. List Item Name]

[Overview paragraph: what it is, why it's on the list]
[Key details: 2-3 supporting points]
[Pros/cons or key features if applicable]
[IMAGE: screenshot, product image, or relevant visual]
[Internal link if we have related content]

## [H2: 2. List Item Name]
...

## [H2: N. List Item Name]

## How We Evaluated [Topic]

[Methodology paragraph: explains selection criteria.
 Builds E-E-A-T credibility. 150-250 words.]

## Frequently Asked Questions

[Minimum 3 Q&A pairs, sourced from PAA data]

### [Q1]
[Answer]

## Final Thoughts

[Summary with recommendation tiers:
 "Best overall," "Best for budget," "Best for [use case]"]
[Internal link to related guide or pillar]

SEO rules specific to listicles:

Internal links: minimum 1 per 500 words, minimum 3 total
External links: minimum 1 per list item (to the thing being listed, if external)
Image density: 1 per list item (minimum), hero image required
FAQ: optional but recommended (minimum 3 if included)
ToC: required (always exceeds 1,500 words with 5+ items)
Primary keyword density: 0.5%–1.5%
Each list item H2 must be numbered and descriptively named

3.3 Comprehensive Guide (`guide`)

Purpose: Pillar-supporting deep-dive content targeting high-volume informational keywords. The authority builder. Designed for AI Overview citation eligibility.

Target length: 3,000–5,000 words

Required structural scaffold:

# [H1: "The Complete Guide to [Topic]" or "[Topic]: Everything You Need to Know"]

[TL;DR Box: 5-7 bullet point key takeaways. First bullet is a
 one-sentence definition or core answer. Maps to `speakable`.
 Total length: 100-150 words.]

[Hero image]

[Opening paragraph: Defines the topic. States why it matters now.
 Primary keyword in first sentence. Author credibility signal
 ("Based on our experience building Consul..." or similar).]

## Table of Contents
[Auto-generated, anchor-linked, levels H2 and H3]

## What Is [Topic]?

[Definition section: 2-3 paragraphs. First paragraph is a
 citation-ready definition (2-3 sentences, under 60 words,
 designed to be extractable by AI engines and featured snippets).
 Remaining paragraphs expand with context.]
[IMAGE: explanatory diagram or visual]

## Why [Topic] Matters [for Audience]

[Problem/opportunity framing. 200-400 words.
 Statistics and citations from brief's external resources.]

## [H2: Core Concept Section 1]

### [H3: Subtopic A]
[200-300 words per H3]
[Internal link]

### [H3: Subtopic B]
[IMAGE if section exceeds 600 words without one]

## [H2: Core Concept Section 2]
...

## [H2: Core Concept Section N — typically 5-8 H2 sections]

## How to Get Started with [Topic]

[Actionable next steps. 3-5 numbered steps.
 Internal links to how-to content or product.]

## Frequently Asked Questions

[Minimum 5 Q&A pairs for guides. Sourced from PAA data.
 Answers are concise and citation-ready.]

### [Q1: Question]
[Answer: 2-4 sentences]
...

## Conclusion

[Summary paragraph. Internal link to pillar page.
 CTA: "Learn more about how Consul handles [topic]" or similar.]

SEO rules specific to guides:

Internal links: minimum 1 per 300 words, minimum 8 total
External links: minimum 3 authoritative sources with citations
Image density: minimum 5 images, 1 per 700 words
FAQ: required, minimum 5 Q&A pairs
ToC: required (always exceeds 1,500 words)
Primary keyword density: 0.5%–1.5%
Must contain at least one citation-ready definition block (under 60 words, standalone paragraph)
H3 sections required under at least 3 H2 sections

3.4 How-To / Tutorial (`how_to`)

Purpose: Step-by-step instructional content targeting "how to" queries. Highest schema richness (HowTo markup). Strong featured snippet and AI Overview candidate.

Target length: 2,000–4,000 words

Required structural scaffold:

# [H1: "How to [Action] [with/for Context]"]

[TL;DR Box: Numbered quick-step summary (abbreviated version
 of the full steps, 1 sentence each). Maps to `speakable`.
 Total length: 80-120 words.]

[Hero image: shows the end result or the process overview]

[Opening paragraph: What you'll learn. What you'll need.
 Expected time/difficulty. Primary keyword in first sentence.]

## What You'll Need (Prerequisites)

[Bulleted list of requirements, tools, or knowledge needed.
 Keep concise — each item 1 sentence max.]

## Table of Contents

## [H2: Step 1 — Action Verb + Description]

[Detailed instructions for this step. 200-400 words.
 Sub-steps as H3 if this step has multiple parts.]
[IMAGE: screenshot or visual showing this step]
[Pro tip or common mistake callout if applicable]

## [H2: Step 2 — Action Verb + Description]
...

## [H2: Step N]

## Troubleshooting Common Issues

[3-5 common problems with solutions.
 Each as H3 under this section.
 Targets "why isn't [thing] working" PAA queries.]

### [Problem 1]
[Solution: 2-3 sentences]

## Frequently Asked Questions

[Minimum 3 Q&A pairs sourced from PAA data]

## What's Next?

[Next steps after completing the tutorial.
 Internal links to advanced content or related guides.
 CTA to Consul if applicable.]

SEO rules specific to how-tos:

Internal links: minimum 1 per 400 words, minimum 5 total
External links: minimum 1 (tool or resource referenced in steps)
Image density: minimum 1 per step, minimum 4 total (hero + step images)
FAQ: required, minimum 3 Q&A pairs
Troubleshooting section: required
ToC: required
Primary keyword density: 0.8%–2.0%
Every step H2 must begin with an action verb
HowTo schema: every step must map to a HowToStep with name, text, and image

3.5 Comparison (`comparison`)

Purpose: Decision-stage content targeting commercial and transactional keywords. Two sub-variants: head-to-head (vs) and roundup. Critical for bottom-funnel capture.

Target length: 2,000–4,000 words

3.5.1 Head-to-Head Variant

Required structural scaffold:

# [H1: "[Product A] vs [Product B]: [Differentiator or Audience Context]"]

[TL;DR Box: Quick verdict (3-4 sentences).
 "Choose [A] if you need X. Choose [B] if you need Y."
 Maps to `speakable`.]

[Hero image: side-by-side visual or comparison graphic]

[Opening paragraph: Why this comparison matters.
 Who should read this. Primary keyword in first sentence.]

## Quick Comparison Table

[Feature comparison table with rows for key criteria
 and columns for Product A, Product B, and "Winner" or "Best For".
 This table maps to structured data and is a featured snippet target.]

## Table of Contents

## [H2: Product A] Overview

[200-300 word overview. What it is, who it's for, key strengths.]
[IMAGE: product screenshot or logo]

## [H2: Product B] Overview

[Same structure as Product A]

## [H2: Comparison Criterion 1 — e.g., "Ease of Use"]

[Head-to-head analysis for this criterion.
 Specific examples, not vague claims.
 Verdict sentence at end of section.]

## [H2: Comparison Criterion 2]
...

## [H2: Comparison Criterion N — typically 4-6 criteria]

## Pricing Comparison

[Side-by-side pricing with plan details.
 Value-for-money analysis, not just numbers.]

## Our Verdict

[3-4 paragraphs. Recommendation segmented by use case.
 "For [use case A], choose [Product]. For [use case B], choose [other]."
 Internal link to Consul if we're one of the compared products.]

## Frequently Asked Questions

[Minimum 3 Q&A pairs. Target "is [A] better than [B]" style queries.]

3.5.2 Roundup Variant

Uses the same scaffold as the Listicle type (Section 3.2) but with comparison-specific language: criteria matrix at top, per-option deep dives, and a verdict section instead of "Final Thoughts." Schema uses ItemList with ListItem entries.

SEO rules specific to comparisons:

Internal links: minimum 1 per 400 words, minimum 4 total
External links: minimum 1 per product compared (to their homepage or pricing page)
Image density: minimum 1 per product compared, plus hero and comparison table
FAQ: required, minimum 3 Q&A pairs
Comparison table: required (featured snippet target)
ToC: required
Primary keyword density: 0.5%–1.5%
Products must be described with specific, verifiable details (no vague claims)

3.6 Case Study (`case_study`)

Purpose: Social proof and trust-building content. Demonstrates real results from Consul users. Lower SEO volume value but critical for conversion and E-E-A-T.

Target length: 1,500–2,500 words

Required structural scaffold:

# [H1: "How [Customer/Company] [Achieved Outcome] with Consul"]

[Results Box: 3 key metrics in a styled callout.
 e.g., "50% reduction in email time | 3 hours saved daily | 2x meeting efficiency"
 Maps to `speakable`.]

[Hero image: customer headshot or company logo with context]

[Opening paragraph: One-sentence hook with the key result.
 Customer context (industry, size, role). Primary keyword.]

## The Challenge

[What problem was the customer facing?
 Specific pain points. Quantify where possible.
 200-300 words.]

## Why They Chose Consul

[Decision process. What alternatives were considered.
 What made Consul the choice. 150-250 words.]

## The Solution

[How Consul was implemented. Specific features used.
 Timeline. 200-400 words.]
[IMAGE: workflow diagram or product screenshot in context]

## The Results

[Quantified outcomes. Before/after comparisons.
 Each result as a sub-section or bold callout.
 300-500 words.]

### [Result 1: Metric + Context]
### [Result 2]
### [Result 3]

## [Customer Name]'s Perspective

[Direct quote from the customer. 2-4 sentences.
 This maps to `Review` schema.]

## Key Takeaways

[3-5 bullet points summarizing lessons.
 Generalizable insights, not just product promotion.]

[CTA: "See how Consul can help your team" + internal link]

SEO rules specific to case studies:

Internal links: minimum 3 (to product, related guide, and pillar)
External links: link to customer's website (with their permission)
Image density: minimum 3 (hero, solution diagram, results chart)
FAQ: not required
ToC: optional (most case studies are under 2,500 words)
Primary keyword density: 0.3%–1.0% (lower — these are narrative, not keyword-driven)
Must contain at least one direct customer quote
Must contain at least 2 quantified results

3.7 Pillar / Hub Page (`pillar`)

Purpose: Cluster parent page that links to all child content within a topic pillar. The topical authority anchor. Optimized for broad, high-volume keywords.

Target length: 2,500–4,000 words

Build pattern: One-time build per topic cluster. Updated quarterly or when new child content is published (add link to new child page).

Required structural scaffold:

# [H1: "[Topic]: The Complete Resource"]

[TL;DR Box: 5-7 bullet takeaways covering the full topic scope.
 Maps to `speakable`. 100-150 words.]

[Hero image]

[Opening paragraph: Broad topic definition. Why it matters.
 Audience framing. Primary keyword in first sentence.
 Author credibility signal.]

## Table of Contents
[Anchor-linked, H2 and H3 levels]

## What Is [Topic]?

[Foundational definition section. 300-500 words.
 Citation-ready definition in first paragraph.
 IMAGE: concept diagram or overview visual]

## [H2: Subtopic Cluster 1 — e.g., "Email Management"]

[Overview paragraph: 150-250 words. Covers the subtopic broadly.
 Does NOT go deep — that's what child content does.]

**Key resources:**
[Internal links to 3-5 child content pieces in this subtopic.
 Each link has a one-sentence description.
 These are the cluster links that build topical authority.]

### [H3: Key concept within this subtopic — brief coverage]

## [H2: Subtopic Cluster 2]
...

## [H2: Subtopic Cluster N — typically 4-7 clusters]

## How to Get Started

[Practical entry point. 200-300 words.
 Links to beginner-level child content.]

## Frequently Asked Questions

[Minimum 5 Q&A pairs covering the broad topic.
 These are GLOBAL FAQs about the topic, not piece-specific.]

## Related Resources

[Curated list of 5-10 most important child pages
 organized by audience need or experience level.]

SEO rules specific to pillar pages:

Internal links: minimum 15 (this is the linking hub — every child page must be linked)
External links: minimum 3 authoritative sources
Image density: minimum 4 (hero, concept diagram, 2+ section images)
FAQ: required, minimum 5 Q&A pairs (global/topic-level FAQs)
ToC: required
Primary keyword density: 0.5%–1.0%
Every H2 subtopic section must contain at least 2 internal links to child content
Page must be updated when new child content is published in the cluster
CollectionPage schema with hasPart referencing all child pages

3.8 Glossary / Definition Page (`glossary`)

Purpose: Targets "what is [term]" queries. Designed for featured snippet capture, AI Overview citation, and voice search. Builds topical authority at the concept level.

Target length: 500–1,200 words

Build pattern: Batch build (20-40 terms initially), then add terms as new concepts emerge. Refresh only when definitions evolve.

Required structural scaffold:

# [H1: "What Is [Term]? Definition, Examples & Guide"]

[Definition Box: 1-2 sentence definition in a styled callout.
 Under 50 words. Optimized for featured snippet extraction
 and AI Overview citation. Maps to `speakable`.]

[Hero image: conceptual visual for the term]

[Opening paragraph: Expanded definition. 3-4 sentences.
 Primary keyword in first sentence.
 "In the context of [domain]..." framing.]

## How [Term] Works

[Explanation section. 200-400 words.
 Practical, concrete explanation.
 Example or analogy included.]
[IMAGE: diagram or visual explanation]

## Why [Term] Matters

[Business value / relevance. 150-250 words.
 Connects to the reader's context.]

## [Term] Examples

[2-3 concrete examples with brief descriptions.
 100-200 words total.]

## [Term] vs [Related Term]

[If a commonly confused related term exists.
 Brief comparison. 100-200 words.
 Internal link to the related term's glossary page.]

## Frequently Asked Questions

[Minimum 3 Q&A pairs. Target PAA queries.
 "Is [term] the same as [other term]?"
 "Who uses [term]?" etc.]

## Related Terms

[List of 3-5 related glossary terms as internal links.
 Builds the glossary cross-linking mesh.]

## Learn More

[Internal link to the relevant guide or pillar page.]

SEO rules specific to glossary pages:

Internal links: minimum 5 (related terms + parent guide/pillar)
External links: minimum 1 authoritative definition source
Image density: minimum 2 (hero + explanatory diagram)
FAQ: required, minimum 3 Q&A pairs
ToC: not required (pages are short)
Primary keyword density: 1.0%–2.5%
Must contain a citation-ready definition block (under 50 words, standalone paragraph in callout)
DefinedTerm schema is required
speakable must point to the definition box

4. JSON-LD Schema Library

Every page published by ContentEngine carries structured JSON-LD markup in the <head>. Schema is generated programmatically from content metadata and template structure — not manually authored. The CMS (Next.js + Supabase) injects schema at render time.

4.1 Schema Architecture

Each page carries a @graph array containing multiple schema entities. This is the Google-recommended approach for complex pages.

Base graph (present on every page):

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "Organization", ... },
    { "@type": "WebSite", ... },
    { "@type": "WebPage", ... },
    { "@type": "[ContentTypeSchema]", ... },
    { "@type": "Person", ... },
    { "@type": "BreadcrumbList", ... }
  ]
}

4.2 Organization Entity (Global — Every Page)

This entity is configured once in system settings and injected on every page via the publisher property.

{
  "@type": "Organization",
  "@id": "https://consul.ai/#organization",
  "name": "[PLACEHOLDER: Legal entity name]",
  "alternateName": "Consul",
  "url": "https://consul.ai",
  "logo": {
    "@type": "ImageObject",
    "@id": "https://consul.ai/#logo",
    "url": "https://consul.ai/images/logo.png",
    "contentUrl": "https://consul.ai/images/logo.png",
    "width": "[PLACEHOLDER]",
    "height": "[PLACEHOLDER]",
    "caption": "Consul - AI Executive Assistant"
  },
  "image": { "@id": "https://consul.ai/#logo" },
  "description": "Consul is a trust-first AI executive assistant that closes coordination loops across email, calendar, and messaging.",
  "foundingDate": "[PLACEHOLDER: YYYY]",
  "numberOfEmployees": {
    "@type": "QuantitativeValue",
    "value": "[PLACEHOLDER]"
  },
  "sameAs": [
    "[PLACEHOLDER: LinkedIn URL]",
    "[PLACEHOLDER: Twitter/X URL]",
    "[PLACEHOLDER: YouTube URL if applicable]"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer support",
    "email": "[PLACEHOLDER: support email]"
  }
}

Action item: Fill in all PLACEHOLDER values before first publication. Store these in a site_config table in Supabase, not hardcoded.

4.3 WebSite Entity (Global — Every Page)

{
  "@type": "WebSite",
  "@id": "https://consul.ai/#website",
  "url": "https://consul.ai",
  "name": "Consul",
  "description": "AI Executive Assistant for CEOs and Founders",
  "publisher": { "@id": "https://consul.ai/#organization" },
  "inLanguage": "en-US"
}

4.4 Author Entities

Three author entities are defined. Each maps to a dedicated author profile page on the site.

4.4.1 Alton Wells

{
  "@type": "Person",
  "@id": "https://consul.ai/authors/alton-wells/#person",
  "name": "Alton Wells",
  "url": "https://consul.ai/authors/alton-wells/",
  "image": {
    "@type": "ImageObject",
    "url": "https://consul.ai/images/authors/alton-wells.jpg",
    "caption": "Alton Wells"
  },
  "jobTitle": "[PLACEHOLDER: Title]",
  "worksFor": { "@id": "https://consul.ai/#organization" },
  "knowsAbout": [
    "AI executive assistants",
    "email automation",
    "calendar management",
    "AI delegation",
    "productivity systems",
    "SaaS product development"
  ],
  "sameAs": [
    "[PLACEHOLDER: LinkedIn URL]",
    "[PLACEHOLDER: Twitter/X URL]",
    "[PLACEHOLDER: Personal site URL if applicable]"
  ],
  "description": "[PLACEHOLDER: 1-2 sentence bio for schema]"
}

4.4.2 Stan [Last Name]

Same structure as Alton. All PLACEHOLDER fields must be filled per individual.

{
  "@type": "Person",
  "@id": "https://consul.ai/authors/stan//#person",
  "name": "Stan [PLACEHOLDER: Last Name]",
  "url": "https://consul.ai/authors/stan/",
  "image": { ... },
  "jobTitle": "[PLACEHOLDER]",
  "worksFor": { "@id": "https://consul.ai/#organization" },
  "knowsAbout": [ ... ],
  "sameAs": [ ... ],
  "description": "[PLACEHOLDER]"
}

4.4.3 Auctor (AI Editorial Author)

Auctor is presented transparently as an AI editorial assistant. The profile and schema reflect this.

{
  "@type": "Person",
  "@id": "https://consul.ai/authors/auctor/#person",
  "name": "Auctor",
  "url": "https://consul.ai/authors/auctor/",
  "image": {
    "@type": "ImageObject",
    "url": "https://consul.ai/images/authors/auctor.jpg",
    "caption": "Auctor - Consul Editorial AI"
  },
  "jobTitle": "AI Editorial Assistant",
  "worksFor": { "@id": "https://consul.ai/#organization" },
  "knowsAbout": [
    "AI productivity tools",
    "email management",
    "scheduling automation",
    "executive workflows",
    "content research"
  ],
  "description": "Auctor is Consul's AI editorial assistant. Articles by Auctor are researched and drafted using AI, then reviewed, enriched with original insights, and approved by Alton Wells or Stan before publication."
}

4.5 Author Profile Page Specification

Each of the three authors has a dedicated page at /authors/[slug]/. These pages are critical for E-E-A-T signals.

Required content blocks per author profile page:

Hero section: Headshot (or avatar for Auctor), full name, title, one-line tagline
Bio section: 2-3 paragraphs covering credentials, expertise areas, and connection to Consul. For Auctor, this section transparently describes the human-AI editorial process: "Articles by Auctor are researched and drafted using AI, then reviewed and enriched by [Alton/Stan] before publication. Every piece undergoes human editorial review, fact-checking, and the addition of original experience and insights."
Expertise tags: Visual display of knowsAbout topics as clickable tags linking to relevant pillar pages
Social links: All sameAs URLs displayed as icons
Recent articles: Dynamic feed of the 10 most recent articles by this author, pulled from our_pages table filtered by author_id
Article count and topic breakdown: "X articles published across [topics]"

Schema on author profile page:

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "ProfilePage", ... },
    { "@type": "Person", ... (full entity from above) },
    { "@type": "Organization", ... },
    { "@type": "BreadcrumbList", ... }
  ]
}

4.6 Content Type Schema Mapping

4.6.1 Blog Post Schema

{
  "@type": "BlogPosting",
  "@id": "https://consul.ai/blog/[slug]/#article",
  "headline": "[meta title]",
  "name": "[H1 title]",
  "description": "[meta description]",
  "datePublished": "[ISO 8601]",
  "dateModified": "[ISO 8601]",
  "author": { "@id": "https://consul.ai/authors/[author-slug]/#person" },
  "publisher": { "@id": "https://consul.ai/#organization" },
  "mainEntityOfPage": { "@id": "https://consul.ai/blog/[slug]/" },
  "image": {
    "@type": "ImageObject",
    "url": "[hero image URL]",
    "width": "[width]",
    "height": "[height]"
  },
  "wordCount": "[actual word count]",
  "articleSection": "[topic cluster name]",
  "keywords": "[primary keyword, secondary keyword 1, secondary keyword 2]",
  "inLanguage": "en-US",
  "isPartOf": { "@id": "https://consul.ai/#website" },
  "about": [
    {
      "@type": "Thing",
      "name": "[primary topic]",
      "sameAs": "[Wikipedia URL if applicable]"
    }
  ],
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".tldr-box", ".article-headline"]
  }
}

Additional schema when FAQ section is present:

{
  "@type": "FAQPage",
  "@id": "https://consul.ai/blog/[slug]/#faq",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "[Question text]",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "[Answer text]"
      }
    }
  ]
}

4.6.2 Guide Schema

Uses Article (not BlogPosting) with articleBody scope and richer hasPart for section structure:

{
  "@type": "Article",
  "@id": "https://consul.ai/guides/[slug]/#article",
  "headline": "...",
  "datePublished": "...",
  "dateModified": "...",
  "author": { "@id": "..." },
  "publisher": { "@id": "..." },
  "wordCount": "...",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".tldr-box", ".definition-box", ".article-headline"]
  },
  "hasPart": [
    {
      "@type": "WebPageElement",
      "name": "[H2 section title]",
      "cssSelector": "#[section-anchor-id]"
    }
  ]
}

Guides always carry FAQPage schema (minimum 5 Q&A pairs).

4.6.3 How-To Schema

This is the richest single-page schema. Every step maps to a HowToStep.

{
  "@type": "HowTo",
  "@id": "https://consul.ai/tutorials/[slug]/#howto",
  "name": "[H1 title]",
  "description": "[meta description]",
  "datePublished": "...",
  "dateModified": "...",
  "author": { "@id": "..." },
  "publisher": { "@id": "..." },
  "totalTime": "PT[estimated minutes]M",
  "estimatedCost": {
    "@type": "MonetaryAmount",
    "currency": "USD",
    "value": "0"
  },
  "supply": [],
  "tool": [
    {
      "@type": "HowToTool",
      "name": "[tool from prerequisites section]"
    }
  ],
  "step": [
    {
      "@type": "HowToStep",
      "name": "[Step H2 title]",
      "text": "[Step content — first paragraph only for schema]",
      "url": "https://consul.ai/tutorials/[slug]/#step-1",
      "image": {
        "@type": "ImageObject",
        "url": "[step image URL]"
      }
    }
  ],
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".tldr-box", ".article-headline"]
  }
}

How-Tos always carry FAQPage schema (minimum 3 Q&A pairs).

4.6.4 Listicle Schema

{
  "@type": "Article",
  "@id": "https://consul.ai/blog/[slug]/#article",
  "headline": "...",
  "author": { "@id": "..." },
  "publisher": { "@id": "..." },
  "datePublished": "...",
  "dateModified": "...",
  "speakable": { ... }
}

Plus ItemList for the ranked items:

{
  "@type": "ItemList",
  "@id": "https://consul.ai/blog/[slug]/#list",
  "name": "[H1 title]",
  "numberOfItems": "[count]",
  "itemListOrder": "https://schema.org/ItemListOrderDescending",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "[Item name]",
      "url": "[external URL to the item, or anchor link to section]"
    }
  ]
}

4.6.5 Comparison Schema (Head-to-Head)

Uses Article as the base, with embedded Product entities connected via isSimilarTo:

{
  "@type": "Article",
  "headline": "...",
  "author": { "@id": "..." },
  "mentions": [
    {
      "@type": "SoftwareApplication",
      "@id": "#product-a",
      "name": "[Product A]",
      "applicationCategory": "BusinessApplication",
      "operatingSystem": "[platforms]",
      "url": "[product URL]",
      "isSimilarTo": { "@id": "#product-b" }
    },
    {
      "@type": "SoftwareApplication",
      "@id": "#product-b",
      "name": "[Product B]",
      "applicationCategory": "BusinessApplication",
      "url": "[product URL]",
      "isSimilarTo": { "@id": "#product-a" }
    }
  ]
}

When Consul is one of the compared products, add offers and aggregateRating (when available from third-party platforms):

{
  "@type": "SoftwareApplication",
  "name": "Consul",
  "applicationCategory": "BusinessApplication",
  "operatingSystem": "Web, iOS",
  "offers": {
    "@type": "Offer",
    "price": "200.00",
    "priceCurrency": "USD",
    "priceValidUntil": "[YYYY-MM-DD]",
    "availability": "https://schema.org/OnlineOnly"
  }
}

Note: aggregateRating is deferred until third-party review platforms (G2, Capterra) are set up. The schema hook is defined here; the data will be populated when available. On-site testimonials use individual Review schema (see Case Study below), not aggregateRating.

4.6.6 Comparison Schema (Roundup)

Same as Listicle (Article + ItemList) with itemListElement entries linking to each reviewed product.

4.6.7 Case Study Schema

{
  "@type": "Article",
  "@id": "https://consul.ai/case-studies/[slug]/#article",
  "headline": "...",
  "author": { "@id": "..." },
  "publisher": { "@id": "..." },
  "datePublished": "...",
  "dateModified": "...",
  "about": {
    "@type": "SoftwareApplication",
    "name": "Consul",
    "@id": "https://consul.ai/#software"
  },
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".results-box", ".article-headline"]
  }
}

Plus Review schema from the customer quote:

{
  "@type": "Review",
  "@id": "https://consul.ai/case-studies/[slug]/#review",
  "author": {
    "@type": "Person",
    "name": "[Customer name]",
    "jobTitle": "[Customer title]",
    "worksFor": {
      "@type": "Organization",
      "name": "[Customer company]"
    }
  },
  "reviewBody": "[Customer quote text]",
  "itemReviewed": {
    "@type": "SoftwareApplication",
    "name": "Consul",
    "@id": "https://consul.ai/#software"
  }
}

4.6.8 Pillar Page Schema

{
  "@type": "CollectionPage",
  "@id": "https://consul.ai/topics/[slug]/#page",
  "name": "[H1 title]",
  "description": "[meta description]",
  "author": { "@id": "..." },
  "publisher": { "@id": "..." },
  "datePublished": "...",
  "dateModified": "...",
  "mainEntity": {
    "@type": "Thing",
    "name": "[Topic name]",
    "description": "[Topic definition]"
  },
  "hasPart": [
    {
      "@type": "WebPage",
      "name": "[Child page title]",
      "url": "[Child page URL]"
    }
  ],
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".tldr-box", ".article-headline"]
  }
}

hasPart is dynamically populated from the content relationship graph — all pages with a child_of edge pointing to this pillar's topic cluster are included.

4.6.9 Glossary Page Schema

{
  "@type": "DefinedTerm",
  "@id": "https://consul.ai/glossary/[slug]/#term",
  "name": "[Term]",
  "description": "[Definition from definition box — under 50 words]",
  "inDefinedTermSet": {
    "@type": "DefinedTermSet",
    "name": "Consul Glossary",
    "url": "https://consul.ai/glossary/"
  }
}

Plus FAQPage schema for the FAQ section, and Article as the base content type.

speakable points to the definition box CSS selector.

4.7 BreadcrumbList Schema (Global — Every Page)

Generated dynamically from the URL path. Present on every page.

{
  "@type": "BreadcrumbList",
  "@id": "https://consul.ai/[path]/#breadcrumb",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://consul.ai/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "[Section]",
      "item": "https://consul.ai/[section]/"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "[Page Title]",
      "item": "https://consul.ai/[section]/[slug]/"
    }
  ]
}

4.8 SoftwareApplication Schema (Consul Product Entity)

This entity represents the Consul product itself. Referenced by case studies, comparisons, and product-adjacent content.

{
  "@type": "SoftwareApplication",
  "@id": "https://consul.ai/#software",
  "name": "Consul",
  "description": "AI executive assistant that manages email, calendar, and scheduling for CEOs and founders.",
  "applicationCategory": "BusinessApplication",
  "operatingSystem": "Web, iOS",
  "url": "https://consul.ai",
  "offers": {
    "@type": "AggregateOffer",
    "lowPrice": "50.00",
    "highPrice": "200.00",
    "priceCurrency": "USD",
    "offerCount": 2,
    "offers": [
      {
        "@type": "Offer",
        "name": "Founding Member",
        "price": "50.00",
        "priceCurrency": "USD",
        "availability": "https://schema.org/LimitedAvailability",
        "description": "Lifetime founding member discount"
      },
      {
        "@type": "Offer",
        "name": "Standard",
        "price": "200.00",
        "priceCurrency": "USD",
        "availability": "https://schema.org/OnlineOnly"
      }
    ]
  },
  "creator": { "@id": "https://consul.ai/#organization" },
  "featureList": [
    "Automated email triage and drafting",
    "AI-powered scheduling and calendar management",
    "Daily briefings via email and iMessage",
    "Multi-interface access (Web, Email, iMessage)",
    "24/7 automated workflows"
  ]
}

4.9 Speakable Implementation

The speakable property identifies content sections most relevant for text-to-speech and AI extraction. It is not visually rendered — it is encoded in schema only.

CSS selectors referenced by speakable must exist in the page markup:

Selector	Maps To	Present On
`.tldr-box`	TL;DR / Key Takeaways callout box	Blog, listicle, guide, how-to, pillar
`.definition-box`	Definition callout (under 50/60 words)	Guide, glossary
`.results-box`	Key metrics callout	Case study
`.article-headline`	H1 element	All content types
`.comparison-table`	Quick comparison table	Comparison (head-to-head)

The Writer Agent outputs these as markdown callout blocks. The CMS renderer maps them to the correct HTML elements with the specified CSS classes.

5. Refresh Queue System

5.1 Design Principles

Every piece of content is re-evaluated on a maximum 90-day cycle. Re-evaluation does NOT mean automatic refresh — it means the system scores refresh urgency and only pieces crossing a threshold enter the active refresh queue. High-performing content gets its next evaluation pushed out (up to 150 days). The goal is ensuring every published page is either performing well or actively being improved.

5.2 Refresh Urgency Score

Each page receives a composite urgency score calculated from five weighted signals. Score range: 0-100.

Signal	Weight	Data Source	Scoring Logic
Position Decay	30%	GSC `our_page_performance`	Score = (position drop over trailing 30 days / 10) × 100, capped at 100. A 5-position drop = 50. No drop = 0.
Traffic Decline	25%	GSC `our_page_performance`	Score = (% impression decline, trailing 30d vs prior 30d) × 100, capped at 100. 40% decline = 40. Growth = 0.
Content Age	20%	`our_pages.last_updated` / `dateModified`	Score = (days since last update / 90) × 100, capped at 100. 90+ days = 100. Just updated = 0.
Competitive Displacement	15%	Graph `outperforms` edges, `competitor_changes`	Score = count of new/worsened `outperforms` edges for this page's target keyword × 25, capped at 100.
Factual Staleness	10%	`our_page_extractions` (claim entities with dated statistics)	Score = (count of claims referencing years older than current year / total claims) × 100.

Composite urgency score = weighted sum of all five signals.

5.3 Refresh Thresholds and Evaluation Scheduling

Urgency Score	Action	Next Evaluation
0–25	No action. Content is performing well.	Push to 150 days from now
26–50	Flag for monitoring. Surface in dashboard as "watch list."	Re-evaluate in 60 days
51–70	Queue for light refresh.	After refresh completes
71–85	Queue for moderate refresh.	After refresh completes
86–100	Queue for heavy refresh. Prioritize immediately.	After refresh completes

5.4 Refresh Tiers

Tier	Scope	Brief Required?	Writer Agent Instructions	Estimated Human Review Time
Light	Update statistics, fix broken links, update `dateModified`, refresh any outdated claims. No structural changes.	No brief. Agent receives the page + extraction data showing stale claims.	"Update the following factual claims with current data. Fix any broken links. Do not change structure, tone, or headings."	5 minutes
Moderate	Restructure sections, add new content informed by competitive changes, update schema, add/improve FAQ with current PAA data.	Abbreviated brief (outline changes only, not full brief).	"Apply the following structural changes to the existing content. Add the following new sections. Update FAQ with these questions."	15 minutes
Heavy	Near-complete rewrite triggered by major rank collapse, topic shift, or competitive leapfrog.	Full brief (same as new content).	Same as new content creation — full Writer Agent pass.	20-30 minutes (same as new content)

5.5 Calendar Integration

Refreshes are mixed into the content calendar at a 70/30 ratio (new content / refreshes). The Strategy Agent manages this allocation.

Rules:

The Strategy Agent sees the refresh queue as a prioritized list alongside new content opportunities.
When planning a production cycle, the agent allocates approximately 70% of capacity slots to new content and 30% to refreshes.
Refresh items are sorted by urgency score (highest first).
Light refreshes consume 0.25 capacity units (minimal human review). Moderate refreshes consume 0.5 units. Heavy refreshes consume 1.0 units (same as new content).
As the content library grows, the ratio naturally shifts — more pages means more refresh candidates. The 70/30 is a starting target; the Strategy Agent can adjust based on queue depth.
If the refresh queue is empty or all scores are below threshold, 100% of capacity goes to new content.

5.6 Refresh Tracking Schema

CREATE TABLE refresh_evaluations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    page_id UUID NOT NULL REFERENCES our_pages(id),
    evaluated_at TIMESTAMP DEFAULT now(),
    urgency_score FLOAT NOT NULL,
    position_decay_score FLOAT NOT NULL,
    traffic_decline_score FLOAT NOT NULL,
    content_age_score FLOAT NOT NULL,
    competitive_displacement_score FLOAT NOT NULL,
    factual_staleness_score FLOAT NOT NULL,
    action_taken VARCHAR(20) NOT NULL,  -- 'none', 'watch', 'light', 'moderate', 'heavy'
    next_evaluation_date DATE NOT NULL,
    refresh_plan_item_id UUID REFERENCES content_plan_items(id),  -- links to the refresh work item if queued
    notes TEXT
);

CREATE INDEX idx_refresh_page ON refresh_evaluations(page_id);
CREATE INDEX idx_refresh_next ON refresh_evaluations(next_evaluation_date);

When a refresh is queued, a content_plan_items row is created with a new status enum value:

ALTER TYPE content_plan_item_status ADD VALUE 'refresh_light';
ALTER TYPE content_plan_item_status ADD VALUE 'refresh_moderate';
ALTER TYPE content_plan_item_status ADD VALUE 'refresh_heavy';

This integrates refreshes into the existing calendar UI and workflow pipeline.

5.7 Refresh-Specific SEO Rules

When a page is refreshed, the following SEO requirements apply:

dateModified in schema MUST be updated to the refresh publication date.
datePublished MUST remain the original publication date (never change).
The URL/slug MUST NOT change. If a slug change is absolutely necessary (rare), a 301 redirect from old to new URL must be created and the validation engine must verify the redirect is in place.
The canonical URL must remain the same page URL.
All existing internal links pointing TO this page from other pages must be verified (the Publishing Agent checks inbound links_to graph edges).
If the refresh adds new sections, the Publishing Agent must run the should_link_to analysis to identify existing pages that should link to the refreshed page's new content.
After refresh publication, the same post-publish pipeline fires: LangExtract re-extraction, summary regeneration, graph edge rebuild.

6. SEO Validation Engine v2

6.1 Architecture Overview

The validation engine runs as deterministic code — no LLM involved. It operates like a CI/CD deployment gate: every content piece must pass all BLOCKING checks before publication. WARNING and INFO checks are logged, tracked, and surfaced in the dashboard but do not block publication.

6.2 Severity Tiers

Tier	Behavior	Analogy
BLOCKING	Publication halted. Auto-fix attempted (max 3 cycles). If still failing, escalate to human with specific failure report.	Failing test in CI — merge blocked.
WARNING	Logged in validation report. Surfaced in dashboard. Tracked historically. Does not block publication but contributes to content health score.	Linting warning — merge allowed, tech debt tracked.
INFO	Logged for analytics. Never blocks. Used for trending analysis and optimization over time.	Code coverage metrics — informational only.

6.3 Complete Check Registry

BLOCKING Checks (Must Pass)

Check B1: Meta Title

Length: 50-60 characters
Contains primary keyword
Unique across all our_pages (checked against our_page_seo.meta_title)
Will not truncate in SERPs (validated via pixel-width estimation, max 580px)
Auto-fixable: Yes (truncation adjustment, keyword insertion)

Check B2: Meta Description

Length: 150-160 characters
Contains primary keyword
Contains value proposition or call-to-action language
Unique across all our_pages
Auto-fixable: Yes

Check B3: Heading Hierarchy

Exactly one H1
H1 contains primary keyword
No skipped heading levels (H1 → H3 without H2)
Logical nesting throughout
H2s use secondary keywords from brief where natural
Auto-fixable: Partial (can fix skipped levels, cannot fix missing keyword)

Check B4: Primary Keyword Presence

Primary keyword appears in: meta title, H1, first 100 words, at least one H2, meta description
All five placements are required
Auto-fixable: Partial

Check B5: Keyword Density

Primary keyword density: within range specified per content type (see Section 3)
No keyword stuffing patterns (3+ identical keyword phrases within 200 words)
Auto-fixable: No (requires content rewriting)

Check B6: Internal Linking Minimum

Meets minimum link count for content type (varies — see Section 3)
All internal links resolve to published pages (verified against our_pages table)
Anchor text is descriptive (no "click here", "read more", "this article")
Anchor text is diversified (no more than 30% exact-match keyword anchors)
Links are contextually placed (not in a footer dump section)
Auto-fixable: Partial (can verify resolution, cannot add missing links)

Check B7: Schema Validity

JSON-LD present and parseable
Schema type matches content type mapping (Section 4.6)
All required properties for the schema type are present and non-empty
author references a valid author entity
publisher references the Organization entity
datePublished is present and valid ISO 8601
dateModified is present and >= datePublished
speakable selector references exist in page markup
For HowTo: every step H2 maps to a HowToStep
For FAQPage: every FAQ Q&A pair maps to a Question/Answer
For CollectionPage: hasPart contains all child pages from graph
Auto-fixable: Yes (schema is generated programmatically — fix is regeneration)

Check B8: URL & Slug

URL-friendly (lowercase, hyphens, no special characters, no spaces)
Contains primary keyword or close variant
Under 75 characters (path portion only)
No duplicate slug in our_pages table
For refreshes: URL matches original (no slug changes without redirect)
Auto-fixable: Partial (can suggest slug, cannot auto-change)

Check B9: Date Integrity

datePublished present in schema and matches visible publish date
dateModified present in schema
For new content: dateModified equals datePublished
For refreshed content: dateModified is the refresh date, datePublished is the original date
Visible "last updated" date on page matches schema dateModified
Auto-fixable: Yes

Check B10: Content Type Structural Compliance

Content matches the required structural scaffold for its content type (Section 3)
Required sections are present (e.g., FAQ section on types that require it)
Required elements exist (e.g., comparison table on comparison pages, prerequisites on how-tos, customer quote on case studies)
TL;DR box present on types that require it
ToC present when required (word count threshold or type requirement)
Auto-fixable: No (structural issues require content rework)

WARNING Checks (Logged, Not Blocking)

Check W1: Image Density

Meets minimum image count for content type
Meets minimum density (1 per 800 words)
No 2 consecutive H2 sections without an image
Hero image present
All images have alt text (human-written)
All images have explicit width and height attributes

Check W2: External Linking

Meets minimum external link count for content type
No links to competitor domains (checked against competitors table)
External links have rel="noopener" on new-tab links
External links point to authoritative domains (heuristic: domain authority check if available)

Check W3: Readability Score

Flesch-Kincaid readability within configured range (target: grade 8-12 depending on content type)
No paragraph exceeds 300 words
Sentence length variety present (standard deviation of sentence lengths > 5 words)

Check W4: Content Depth Coverage

Draft covers all H2 sections specified in the approved brief
Each H2 section meets its target word count (within ±20%)
No brief-specified subtopic is missing entirely
This is a structural check, not a quality judgment

Check W5: FAQ Section Quality

FAQ section meets minimum Q&A count for content type
Questions are actual questions (end with "?")
Answers are 2-4 sentences each (citation-ready length)
Questions are unique (no near-duplicates within the same page)

Check W6: Mobile & Performance

All images have explicit width/height (prevents CLS)
Images use loading="lazy" except hero image (above-the-fold)
No inline styles that break mobile viewport
Tables have responsive handling (horizontal scroll wrapper)
No excessively large embedded content (>500KB individual assets)

INFO Checks (Analytics Only)

Check I1: Word Count Delta

Actual word count vs. brief target word count
Logged as percentage delta (e.g., "+12%", "-8%")

Check I2: Keyword Density Exact

Primary keyword density as exact percentage
Secondary keyword presence (count and density)

Check I3: Schema Richness Score

Count of schema properties populated beyond minimum required
Scored 0-100 based on optional property coverage
Tracks how "complete" the schema is vs. maximum possible

Check I4: Internal Link Density Ratio

Internal links per 1,000 words
Compared to site-wide average for the same content type

Check I5: Estimated Reading Time

Calculated from word count (avg 250 wpm)
Logged for analytics and potential on-page display

Check I6: Citation-Ready Block Count

Number of standalone paragraphs under 60 words that contain factual claims or definitions
These are the blocks most likely to be extracted by AI engines
Higher count = higher AI citation eligibility

6.4 Validation Output Schema

interface SeoValidationResult {
  pageId: string;
  contentType: ContentType;
  validatedAt: Date;
  validationVersion: string;  // schema version of the check suite

  // Gate decision
  passed: boolean;  // true if all BLOCKING checks pass
  
  // Summary scores
  blockingScore: string;    // "10/10", "8/10"
  warningScore: string;     // "5/6", "4/6"
  infoMetrics: Record<string, string | number>;

  // Individual checks
  checks: Array<{
    id: string;           // "B1", "W3", "I2"
    name: string;
    tier: "BLOCKING" | "WARNING" | "INFO";
    passed: boolean;
    value?: string | number;   // actual measured value
    target?: string | number;  // expected value or range
    details: string;
    failureReason?: string;
    autoFixable: boolean;
    autoFixApplied?: boolean;
  }>;
}

6.5 Historical Validation Tracking

Every validation run is stored for trend analysis and refresh signal generation.

CREATE TABLE validation_history (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    page_id UUID NOT NULL REFERENCES our_pages(id),
    validated_at TIMESTAMP DEFAULT now(),
    validation_trigger VARCHAR(20) NOT NULL,  -- 'pre_publish', 'refresh_eval', 'scheduled_audit', 'manual'
    passed BOOLEAN NOT NULL,
    blocking_score VARCHAR(10) NOT NULL,
    warning_score VARCHAR(10) NOT NULL,
    check_results JSONB NOT NULL,  -- full check array
    info_metrics JSONB NOT NULL,
    content_hash VARCHAR(64) NOT NULL,  -- detect if content changed between validations
    validation_version VARCHAR(20) NOT NULL
);

CREATE INDEX idx_val_page ON validation_history(page_id);
CREATE INDEX idx_val_date ON validation_history(validated_at);
CREATE INDEX idx_val_trigger ON validation_history(validation_trigger);

Usage: The refresh evaluation system (Section 5) can query validation_history to detect score decay. If a page's warning score drops between validation runs (e.g., a link target was unpublished, breaking an internal link), this contributes to refresh urgency.

Scheduled audit: A weekly Trigger.dev job runs the full validation suite against all published pages. This catches degradation from external changes (broken links, updated competitor content, expired schema data).

6.6 Auto-Fix Pipeline

When a BLOCKING check fails, the auto-fix pipeline attempts resolution before escalating to human review.

Pipeline:

Validation runs. If any BLOCKING check fails, collect all failures.
For each failure marked autoFixable: true, the Final Cleanup Agent applies the fix.
Validation re-runs on the fixed content.
Maximum 3 fix-revalidate cycles.
If all BLOCKING checks pass after auto-fix, proceed to publication.
If any BLOCKING check still fails after 3 cycles, escalate to human with a report listing all remaining failures, fix attempts made, and specific guidance on what needs manual correction.

Auto-fixable checks and their fix strategies:

Check	Fix Strategy
B1: Meta Title	Truncate to 60 chars at word boundary. Insert primary keyword if missing (prepend).
B2: Meta Description	Truncate to 160 chars at sentence boundary. Insert primary keyword if missing.
B3: Heading Hierarchy (partial)	Insert missing H2 parent for orphaned H3s. Cannot fix missing keyword in H1.
B7: Schema Validity	Regenerate schema from content metadata. This always works since schema is programmatic.
B9: Date Integrity	Set dates from content metadata in Supabase.

7. Content Depth Validation — Detailed Design (Check W4)

This check closes the loop between the Brief Agent's competitive gap analysis and the Writer Agent's actual output. It ensures the draft covers what the brief specified.

7.1 How It Works

The check compares the approved brief's outline against the draft's actual heading structure and section content.

Input:

Approved brief outline (from content_briefs.outline JSONB field)
Draft content (markdown with heading structure)

Validation logic:

For each H2 in brief.outline:
  1. Find matching H2 in draft (fuzzy string match, >70% similarity threshold)
  2. If no match found: FAIL — "Brief section '[heading]' missing from draft"
  3. If match found:
     a. Count words in draft section
     b. Compare to brief's suggestedWordCount for that section
     c. If actual < (suggested × 0.8): WARNING — "Section '[heading]' is 
        [X]% below target word count"
  4. Check that H3 subsections specified in brief exist under this H2

Report:
  - sections_covered: [count] / [total brief sections]
  - sections_missing: [list]
  - sections_underweight: [list with actual vs target]
  - coverage_percentage: sections_covered / total × 100

Threshold: Coverage percentage must be >= 85% to pass. Below 85% triggers a WARNING.

7.2 Why This Is a WARNING, Not BLOCKING

Content depth is a quality signal, not a binary pass/fail. A writer may deliberately merge two brief sections or cover a topic differently than outlined if they discover better framing during writing. Blocking publication for structural deviation would create false negatives. The WARNING surfaces the gap for human review without halting the pipeline.

8. Image Placement Rules

8.1 Writer Agent Image Markers

The Writer Agent outputs image placement markers in the following format:

[IMAGE: {description of what should go here} | alt: {suggested alt text basis}]

The description tells the human image placer what type of image fits. The alt field gives a starting point for alt text (human refines this).

8.2 Placement Rules

Rule	Specification
Hero image	Required on every content type. Placed immediately after the TL;DR/Results box, before the first body paragraph.
Density floor	Minimum 1 image per 800 words of body content.
Section gap	No more than 2 consecutive H2 sections without an image between them.
Minimum per type	Blog: 3, Listicle: 1 per item + hero, Guide: 5, How-to: 1 per step + hero, Comparison: 1 per product + hero, Case study: 3, Pillar: 4, Glossary: 2
Image type	AI-generated images relevant to the page content.
Format requirements	WebP preferred (with JPEG fallback). Max 500KB per image. Explicit width and height in HTML attributes. `loading="lazy"` on all images except hero.
Alt text	Written by human during image placement. Must be descriptive and include relevant keywords naturally. 10-125 characters. Must not start with "Image of" or "Picture of."

8.3 Schema for Images

Every image maps to an ImageObject in the page schema. The hero image is referenced by the content type schema's image property. Step images in how-tos are referenced by their corresponding HowToStep.image.

9. Open Questions for Review

#	Question	Impact	Recommended Default
1	Should the `speakable` CSS selectors be validated against actual deployed HTML, or only against the markdown template spec? Deployed HTML validation requires a post-render check.	Speakable schema accuracy	Validate against template spec at build time. Add deployed HTML validation as a Phase 2 enhancement.
2	The comparison type allows Consul as one of the compared products. Should there be a review flag for comparisons that mention Consul directly, to ensure objectivity?	Brand credibility	Yes. Any comparison mentioning Consul should have a `requires_objectivity_review: true` flag on the content plan item.
3	For the glossary batch build (20-40 terms), should terms be identified by the Strategy Agent from SERP extraction data, or manually curated?	Glossary relevance	Hybrid. Strategy Agent proposes terms from PAA and SERP data. Human curates final list.
4	Should validation history be retained indefinitely, or pruned after a retention period?	Storage	Retain indefinitely. Validation records are small (JSONB per check, ~2-5KB per run). Annual storage for 500 pages × 52 weekly audits = ~130MB. Negligible.
5	The auto-fix pipeline for meta title/description involves prepending keywords. Should there be a "preferred format" template per content type (e.g., "[Keyword]: [Benefit]	Consul")?	Meta tag consistency and brand

End of Addendum #2

Next addendum: Hierarchical Summary Generation — defining how LangExtract extraction outputs are aggregated into navigable Level 0-3 summaries for agent consumption.

ContentEngine — Technical Addendum #2

Content Type Templates, Schema Library, Refresh System & Validation Architecture

1. Purpose & Scope

1.1 What This Addendum Covers

1.2 What This Addendum Does Not Cover

1.3 Industry Context

2. Content Type Registry

2.1 Type Overview

2.2 Comparison Sub-Variants

3. Content Type Template Specifications

3.1 Blog Post (blog_post)

3.2 Listicle (listicle)

3.3 Comprehensive Guide (guide)

3.4 How-To / Tutorial (how_to)

3.5 Comparison (comparison)

3.5.1 Head-to-Head Variant

3.5.2 Roundup Variant

3.6 Case Study (case_study)

3.7 Pillar / Hub Page (pillar)

3.8 Glossary / Definition Page (glossary)

4. JSON-LD Schema Library

4.1 Schema Architecture

4.2 Organization Entity (Global — Every Page)

4.3 WebSite Entity (Global — Every Page)

4.4 Author Entities

4.4.1 Alton Wells

4.4.2 Stan [Last Name]

4.4.3 Auctor (AI Editorial Author)

4.5 Author Profile Page Specification

4.6 Content Type Schema Mapping

4.6.1 Blog Post Schema

4.6.2 Guide Schema

4.6.3 How-To Schema

4.6.4 Listicle Schema

4.6.5 Comparison Schema (Head-to-Head)

4.6.6 Comparison Schema (Roundup)

4.6.7 Case Study Schema

4.6.8 Pillar Page Schema

4.6.9 Glossary Page Schema

4.7 BreadcrumbList Schema (Global — Every Page)

4.8 SoftwareApplication Schema (Consul Product Entity)

4.9 Speakable Implementation

5. Refresh Queue System

5.1 Design Principles

5.2 Refresh Urgency Score

5.3 Refresh Thresholds and Evaluation Scheduling

5.4 Refresh Tiers

5.5 Calendar Integration

5.6 Refresh Tracking Schema

5.7 Refresh-Specific SEO Rules

6. SEO Validation Engine v2

6.1 Architecture Overview

6.2 Severity Tiers

6.3 Complete Check Registry

BLOCKING Checks (Must Pass)

WARNING Checks (Logged, Not Blocking)

INFO Checks (Analytics Only)

6.4 Validation Output Schema

6.5 Historical Validation Tracking

6.6 Auto-Fix Pipeline

7. Content Depth Validation — Detailed Design (Check W4)

7.1 How It Works

7.2 Why This Is a WARNING, Not BLOCKING

8. Image Placement Rules

8.1 Writer Agent Image Markers

8.2 Placement Rules

8.3 Schema for Images

9. Open Questions for Review

End of Addendum #2

3.1 Blog Post (`blog_post`)

3.2 Listicle (`listicle`)

3.3 Comprehensive Guide (`guide`)

3.4 How-To / Tutorial (`how_to`)

3.5 Comparison (`comparison`)

3.6 Case Study (`case_study`)

3.7 Pillar / Hub Page (`pillar`)

3.8 Glossary / Definition Page (`glossary`)