Build Spec: Home Service Site Architecture

v4 froze the architecture. This annex is the layer beneath it: the conventions, validation rules, and gates an engineer needs in order to start without asking what anything meant. Two items in the handed-down spec would not have survived contact with a validator. Both are corrected here and marked. ← Back to Wireframe v4

ACMS data model

Inverse queries drive every generated block. A ServicePillar renders its city list by querying IntersectionPages that reference it; a LocationHub renders its service index the same way. Editors write copy. They do not build navigation, and they cannot override a generated link's target or anchor.

BURL and slug conventions

City disambiguation, decided now rather than at expansion

• Default slug is the bare city name: /ac-repair/phoenix/.
• When two cities in the registry share a name, both take a state suffix: /ac-repair/portland-or/ and /ac-repair/portland-me/. Never suffix only the newcomer, because that silently changes the meaning of the original URL and leaves the older page ranking for an ambiguous term.
• The city registry includes planned expansion markets, not just live ones. A collision is detected against the plan, so the suffix is decided before either page exists.
• The slug generator enforces this on save. It is not a naming guideline.

CJSON-LD entity graph

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#org",
      "name": "Example HVAC Inc.",
      "url": "https://example.com",
      "logo": "https://example.com/logo.png",
      "sameAs": ["<GBP profile URL>", "<BBB URL>", "<social URLs>"]
    },
    {
      "@type": "LocalBusiness",
      "@id": "https://example.com/service-areas/phoenix/#localbusiness",
      "name": "Example HVAC Inc. – Phoenix",
      "parentOrganization": { "@id": "https://example.com/#org" },
      "areaServed": { "@type": "City", "name": "Phoenix", "addressRegion": "AZ" },
      "telephone": "+1-555-123-4567",
      "address": { "@type": "PostalAddress", "addressLocality": "Phoenix", "addressRegion": "AZ" },
      "geo": { "@type": "GeoCoordinates", "latitude": 33.4484, "longitude": -112.0740 },
      "openingHoursSpecification": [ /* per day */ ],
      "sameAs": "<GBP URL carrying this location's CID>"
    },
    {
      "@type": "Service",
      "@id": "https://example.com/ac-repair/#service",
      "name": "AC Repair",
      "serviceType": "HVAC Repair",
      "provider": { "@id": "https://example.com/service-areas/phoenix/#localbusiness" }
    },
    {
      "@type": "Person",
      "@id": "https://example.com/team/mike-rodriguez/#person",
      "name": "Mike Rodriguez",
      "worksFor": { "@id": "https://example.com/#org" },
      "hasCredential": {
        "@type": "EducationalOccupationalCredential",
        "credentialCategory": "NATE Certification"
      }
    },
    {
      /* CORRECTED: Article, not HowTo. author/about/contentLocation resolve. */
      "@type": "Article",
      "@id": "https://example.com/projects/capacitor-replacement-ahwatukee/#project",
      "headline": "AC Capacitor Replacement in Ahwatukee",
      "about": { "@id": "https://example.com/ac-repair/#service" },
      "author": { "@id": "https://example.com/team/mike-rodriguez/#person" },
      "publisher": { "@id": "https://example.com/#org" },
      "contentLocation": { "@id": "https://example.com/service-areas/phoenix/#localbusiness" },
      "datePublished": "2026-09-25",
      "image": ["<before>", "<after>"]
    }
  ]
}

Emission rule: every page emits its own slice of this graph, and every @id it references must resolve to a node emitted somewhere on the site. Validate against the Rich Results test before launch, and again in CI on every template change.

DAnchor text conventions

Templates generate all of these. Manual override is disabled in the editor. One generated link per target per page, so a page never carries the same anchor to the same URL three times.

ETemplate defaults

FCI and QA gates

Tiered content floors

The 350-word absolute minimum from section 1 does not move: nothing publishes below it, ever. These tiers sit above that floor and set the target for a market's priority.

• Assignment: contentTier on the LocationHub, default tier3. The SEO Lead owns the initial mapping across all locations as a one-time strategic pass; marketing ops then executes against the assigned tiers.
• Tier-1 eligibility: a location needs 6 or more published Projects with photos, geotagged to its service area, before tier-1 can be assigned. Tier-1 asks for 1,500 words per intersection page, and without the job history behind it that target gets met with padding, which is the exact failure the content floor exists to prevent.
• Override: tier-1 without the project threshold, for an aggressive new-market launch, with named approval and the justification in the commit message.
• Scope of the count: narrative copy only. Promo badges, financing terms and other module strings do not count, or the floor becomes satisfiable with furniture.
• Enforcement: CI warns below the floor; the deploy proceeds only when the commit message carries --ack-short-copy={pageSlug} for each flagged page. Shipping thin copy becomes deliberate and attributable rather than silent.
• At 90 days below floor: recommended for soft-unlink from global navigation, with the same named approval as the M.5 escalation. The page stays published and indexable.

Gates run on pull requests against the six template archetypes, not against every published page. Page-level problems are the nightly crawl's job; template-level problems must never reach production.

GOperational rules

• Project reuse: a project may appear on its location hub (one of many) and on its service pillar (in a recent-work block). It may appear on exactly one intersection page. No reuse across intersections, because the same job in two cities is the first lie a reviewer would catch.
• GBP SOP stands as written in v3: weekly posts, Q&A answered inside 24 hours, photo cadence matched to the project pipeline.
• Content supply governs page count. The grid will land below its theoretical maximum. That is the expected outcome, not a shortfall to explain away.
• Minimum project count before a city opens: 3 documented projects in that service area. One project is a page; three is a pattern a reviewer believes. A city with fewer stays unpublished until the trucks have been there.
• Before any city expansion: the capture workflow is running with field operations, and ongoing project documentation has a named owner. Expansion that outruns capture produces exactly the thin grid this architecture exists to avoid.

HAccessibility

IBrand governance

These values live in one config singleton (CMS singleton or environment, one of the two, chosen once). Templates read from it. Editors cannot fork them, because a second phone number in the wild is a tracked-call attribution failure and a NAP inconsistency at the same time.

JZero-click event schema CLOSES THE FLAGGED GAP

The handed-down spec left remarketing instrumentation "for sprint tickets." Leaving it undefined is how it ships as three inconsistent event names. Defined here instead.

Every event carries service and city where the page type has them, so remarketing audiences can be built per intersection rather than per site. Pixel placement is a template concern, not a page concern: it ships once in the base layout.

KAI retrieval optimization

Everything above optimizes for search engines reading the site, including their AI features. This section covers the other half: being quotable when someone asks ChatGPT, Perplexity, or Claude for an electrician in their city. That traffic never appears as a ranking, and the page that earns it is built differently.

K.1 — Authority claims, added to the section I singleton

Verifiable business facts every template can pull from. Editors cannot fork them. A LocationHub cannot publish while any required field is empty.

K.2 — Machine-readable About block

Every LocationHub renders a 150 to 200 word structured summary in third person, directly below the H1, generated from the singleton plus that location's fields. It is factual, quotable prose written to be extracted, not marketing copy.

Third person throughout. "We have served" cannot be quoted by a model answering someone else's question; "[Business Name] has served" can.

K.3 — FAQPage schema on comparison pages only

• Comparison and decision pages (repair vs replace, heat pump vs furnace, AC size guide) carry FAQPage wrapping 3 to 5 genuine Q&A pairs.
• Each question is a real question someone asks, not a heading rewritten with a question mark. Each answer is self-contained and readable with no page context around it.
• Problem and symptom pages do not get FAQ schema. They are single-intent diagnostic content; adding Q&A markup creates circular structure and dilutes the topical focus that makes them rank.

K.4 — Person schema, extended

The sameAs requirement is the one with teeth. It is what turns a name on a page into an entity a model can corroborate somewhere else, and it is the field most likely to stall the build, because it needs a real profile per technician. Budget for that before promising the field is required.

K.5 — Article dating, enforced (freshness hygiene, not an AI signal)

Stated honestly: this is a freshness signal for traditional crawlers and a forcing function against content decay. Its effect on LLM retrieval is assumed, not demonstrated. It stays required because content rot is real; it should stop being sold as an AI optimization.

• Every article-type page (problem pages, comparison and decision pages) emits datePublished and dateModified in its JSON-LD.
• CI gate: the build fails when dateModified is missing, or older than 365 days, on any article-type page.
• dateModified changes only when the content actually changed. A build that touches the date without touching the substance is lying to the crawler, and the date-freshness gate becomes a ritual instead of a signal.

K.6 — Crawl accessibility gate

• Every intersection page renders 400 bytes or more of body text with JavaScript disabled.
• JSON-LD is present in the raw HTML response, never injected client-side.
• Test method: a plain curl fetch, or a headless browser in no-JS mode, during build validation. The build fails on any page that does not clear it.

Most assistant fetchers do not execute JavaScript. A page that needs JS to show its content is, to them, an empty page.

K.7 — Citation durability

The H1 and the first sentence of body copy on every intersection page carry the business name and the city:

• H1: AC Repair in Phoenix | [Business Name]
• First sentence: "[Business Name] provides 24/7 AC repair service throughout the Phoenix metropolitan area…"

Models quote sentences and drop links. If the identifying information is inside the sentence, the attribution survives the citation being stripped.

K.8 — LLM accessibility files

/llms.txt indexing the key pages in plain English, and /llms-full.txt carrying the full text for a single fetch. Regenerate whenever the architecture changes or a new service area launches.

Status: both files are already live on this document site, which is also the working proof of the pattern. Honest caveat, carried over from the source spec: their utility for third-party crawlers is plausible and unproven at scale. Cheap to ship, so ship them; do not count on them.

K.9 — Crawler licensing stance

Decide explicitly whether AI systems may cache and redistribute the content, rather than letting silence pick for you. For a local service business the answer is nearly always permissive: the entire goal is to be quoted to someone shopping for a contractor, and a restriction that keeps you out of an answer costs a lead to buy nothing.

• Permissive: a License: line in the /llms.txt header.
• Restrictive: documented in robots.txt or the emerging ai-permissions.txt convention.

This is a client decision, made per client and recorded in the build, not a default anyone should inherit silently.

K.10 — Content supply, stated plainly

K.11 — Speakable markup (required, enforced as a warning)

• Scope: LocationHub and IntersectionPage. Target: the page's WebPage node — corrected from the directive, which targets LocalBusiness and Service. Google has only ever documented speakable for Article and WebPage in news-publisher contexts, never for LocalBusiness or Service, so emitting it there is markup for a combination that has never been supported anywhere. If it is worth emitting at all, emit it where it is at least defined.
• Value: a CSS selector pointing at the introductory paragraph, the first two or three sentences, resolving to something non-empty and staying at or under 300 characters.
• Enforcement: CI warns when the selector is missing, resolves empty, or exceeds the limit. It does not fail the build, because a selector that stops matching after a template edit is a content problem, not a broken deploy.
• Deprecation clause: drop the requirement if Google formally deprecates speakable for LocalBusiness. Worth knowing now: speakable support has only ever been documented for news content, so treat this as cheap positioning rather than a mechanism with evidence behind it.

Acceptance criteria — AI retrieval complete

Build order

Slotted into the existing phases from v4, by dependency rather than sprint number:

• With the content model (v4 phase 2): authority fields on the singleton, extended Person type, About block component.
• With the templates (v4 phase 3): the no-JS and date-freshness CI gates, citation-durability H1 and opening sentence, FAQ schema on comparison templates.
• After launch: the LLM accessibility files, regenerated on every architecture change.

LOff-site authority and measurement

L.0 — The runbook is a build dependency

The build fails when /ai-visibility.md or its runbook.yaml is missing, or when runbook.yaml has a null owner or reviewCadence. Off-site work is the half that quietly does not happen; tying it to the build makes its absence loud.

L.1 — GBP identity required, GBP quality measured GATE REJECTED

Required fields on LocationHub: gbpCid and gbpPlaceId. A location hub cannot publish without them, because they are the join between this site and the surface the assistants actually read.

L.2 — NAP verification freshness

• Required field on LocationHub: napLastVerifiedAt.
• Creating a new LocationHub is blocked when the timestamp is null or older than 90 days.
• Updating an existing one warns but never blocks. Otherwise a stale audit stops you fixing a typo, and the fix people reach for is faking the timestamp.
• The nightly job flags anything past 60 days so the audit is scheduled, not discovered.

Why 90 and not 30: the review asked for 30 days while its own runbook sets the NAP audit at quarterly. Ninety matches the cadence that is actually staffed. A gate tuned tighter than the process behind it does not raise the standard, it teaches people to bypass the gate.

L.3 — AI referrer tagging

Analytics tags traffic arriving from assistant platforms as channel=ai_generated, with the domain list in the section I singleton as aiReferrerDomains[]:

chatgpt.com perplexity.ai claude.ai gemini.google.com copilot.microsoft.com you.com

Deployment test: request the homepage with a spoofed Referer from each listed domain and assert the beacon fires with channel=ai_generated. The deployment fails if it does not.

L.4 — Assistant crawler logging

Middleware matches incoming User-Agent headers against llmCrawlerRegex[] in the singleton and logs hits: GPTBot, anthropic-ai, ClaudeBot, Claude-User, Google-Extended, PerplexityBot, CCBot, OAI-SearchBot.

• CI compiles every pattern; a syntax error fails the build.
• An unmatched user agent exceeding 1,000 requests a day emits a warning naming it, so the list grows from observation rather than memory.
• Quarterly review of the list sits in the runbook.

This is the cheapest honest signal in section L: it tells you whether assistants fetch the site at all, which is a precondition for every other claim here.

L.5 — Citation panel data

The measurement table exists before launch, and CI asserts its schema. Storage is vendor-agnostic: BigQuery, Postgres, or Supabase all qualify. The schema does not.

run_id        STRING
timestamp     TIMESTAMP
assistant     STRING     // chatgpt, perplexity, gemini, claude, copilot
query         STRING
appeared      BOOLEAN
link_present  BOOLEAN
sentiment     STRING     // nullable: positive, neutral, negative, hallucination
snapshot_url  STRING     // nullable: path to stored response or its hash

How the table is filled is the runbook's problem. That it exists, and that nothing ships before it does, is this spec's problem.

L.6 — Falsifiability, without letting the spec rewrite itself AUTOMATION REJECTED

A requirement demoted this way moves to optional in kRequirementStatus in the singleton, and the change lands in this document in the same pull request. Config and prose never disagree.

Mv4.1 surfaces: estimator, equipment pages, specials, review counter

Three new page types and one global element. Each inherits the same envelope as everything else here: server-rendered, gated on real supply, measured. None of it changes the section L conclusion that off-site authority dominates AI citation. These are conversion and traditional-SEO surfaces that must not become the thin-content vector the rest of this spec exists to prevent.

M.1 — Installation-intent estimator

/ac-installation/estimate/ /furnace-installation/estimate/ /heat-pump-installation/estimate/

• Content first: 300+ words server-rendered and visible with JavaScript disabled — why an estimate matters, the factors weighed, a sample table of 2 to 3 scenarios with tier recommendations, the CTA, the disclaimer.
• Calculator second: progressive enhancement after first paint, with a <noscript> block repeating the sample table.
• Disclaimer, fixed wording (replacing "prices are illustrative", which presumes prices this spec forbids): This tool sizes equipment and narrows your options. It is not a quote. Your quote comes after a technician sees the home.
• Config: estimatorParamsAllowlist: [homeSize, systemAge, efficiency]. Every other querystring parameter 301s to canonical, so the tool cannot spawn an index of near-duplicate pages.
• Schema: SoftwareApplication for the calculator. FAQPage only over a genuine Q&A block — a sample table is a table, and marking it up as an FAQ is the exact misuse K.3 bans.
• Events: EstimatorRangeViewed server-side on render, EstimatorCalculated client-side on submit.

M.2 — Equipment and model pages

/brands/[brand-slug]/[model-number]/, trailing slash, brand drawn from the installedBrands[] registry.

Gate 4 is the one that matters. Same rule as intersection pages: a page about equipment you have never installed is a page about nothing.

• Content floor: 600 words, 3+ features, a 5+ row spec table, at least one installing technician linked.
• Template: a "Recent Local Installations" block by inverse query from Projects. No manual curation.
• Sitemap: model pages live in /sitemap-model.xml with changefreq: yearly, referenced from the index and excluded from the primary sitemap.
• Orphan check: a model page with no inbound link from its parent brand page, or no Project reference, raises an alert.

M.3 — Specials page

• /specials/, a singleton. Offers are anchored sections. No per-coupon URLs, because a coupon URL is a page that expires into a 404 or a thin orphan.
• Each offer carries Offer schema with validThrough.
• Expired offers are removed from the rendered HTML, not hidden with CSS. Hidden text is still content, and an expired offer still in the markup is a promise the business is no longer keeping.
• With no active offer, a fallback block renders — "Check back soon for seasonal specials" — with CTAs to the diagnostic tool and the estimator. The page auto-noindexes only if the fallback is missing too.
• Data: offerTitle, offerDescription, validFrom, validUntil, conditions, optional linkedService. Reject save when validUntil is already past. The nightly job archives expired offers.
• Dollar amounts: off by default per M.0. Offers state what the customer gets, not what it costs. allowOfferAmounts: false in the singleton; enabling it for a client who insists is a recorded decision by Jason, not a developer's call.

M.4 — Sitewide review counter

• Display: global header beside the phone CTA, ★ 4.9 — {floor_to_100}+ Google Reviews, so 437 renders as "400+".
• Source: nightly aggregation across the GBP place IDs of every published LocationHub, stored on the AuthorityClaims singleton.
• Schema integrity: aggregateRating.reviewCount carries the exact live number, never the floored one. CI fails when the schema value is below the displayed floor. Header "400+" with schema 347 fails; with schema 437 it passes.
• Negative delta: a drop over 20% between nightly runs raises a RED alert to PagerDuty and #seo-alerts, owned by the SEO Lead with DevOps as backup, 8 business-hour SLA. What it freezes is the number, not the pipeline: the counter holds at the last known good value and the new figure cannot ship until a human picks one of three resolutions — accept and document, legitimate drop so rebaseline, or data error so keep last known good. Deployments continue.

M.5 — GBP quality monitor

Replaces the rejected publish gate. Nothing here blocks a deployment; consequences escalate over time instead, and a new location gets 90 days before any of it applies.

gbpQualityMonitor:
  coldStartGracePeriodDays: 90
  onApiError: fail_open_with_warn
  thresholds:
    large_metro:  { minReviews: 50, minRating: 4.5 }
    mid_market:   { minReviews: 20, minRating: 4.5 }
    small_market: { minReviews: 10, minRating: 4.3 }
  cityTierAssignments:
    phoenix: large_metro
    scottsdale: large_metro
    flagstaff: small_market
    # unassigned cities default to mid_market
  escalations:
    tier1: { consecutiveDaysBelow: 7,  action: slack_warn, channel: '#seo-alerts', coolDownDays: 7 }
    tier2: { consecutiveDaysBelow: 30, action: page_marketing_ops }
    tier3: { consecutiveDaysBelow: 90, action: recommend_soft_unlink, requires: marketingDirectorApproval }
  # timers reset when both metrics meet threshold

Soft-unlink, when approved, removes the location from primary and footer navigation while the URL stays live and indexable for review generation. Its @id node stays in the graph. Approval records acknowledgedBy, reason (20 characters minimum), and remediationTargetDate.

M.6 — Measurement for the new surfaces

All three enter the L.6 loop at launch, tagged channel=estimator, channel=model_page, channel=specials.

M.7 — The quarterly variance report

The automation that was wanted, pointed at the right target: it produces a shortlist for a human instead of editing the spec. Two tracks, because a surface with one quarter of data cannot be judged the same way as one with a history.

-- surfaces with 2+ quarters of data
FLAG WHERE citations_current_q = 0
  AND entrances_current_q < 0.7 * entrances_prev_q;

-- surfaces with less than 2 quarters
FLAG WHERE citations_current_q = 0
  AND assisted_conversions = 0
  AND entrances_current_q < 50;

Output is a board the SEO Lead reads. Flagged items get interpreted, demotions get proposed with the evidence attached, and the change lands as a pull request updating this document and kRequirementStatus together. Looker is one way to render it; any dashboard will do, and a spreadsheet will do for one client.

M.8 — Project bulk-create endpoint

ProjectContentType:
  supportsBulkApiCreate: true
  endpoint: POST /cms/api/v1/projects?draft=true
  auth: service-account token "field-capture-bridge"
  rateLimit: 100 req/min, burst 25

Drafts created this way still pass through the section 5 moderation queue: GPS and work order required, technician approval before publish. The endpoint removes the typing, not the gate. Typical wiring is job-close webhook to a small function to a CMS draft, then the content coordinator's daily queue.

NConversion and trust signals DRAFT

N.1 — ReviewAggregate, required

• Source: gbpPlaceId from section A, via the nightly GBP sync job. Hard fail when it is missing: our field, our configuration error.
• Cache shape: the sync writes {reviewCount, rating, lastUpdated}, and for a new branch with no reviews it explicitly writes reviewCount: 0 — otherwise an empty state and a cache miss look identical at render time, and they call for opposite handling.

Alerting: #seo-alerts fires on stale only. lowVolume and empty are legitimate states for a new branch, and paging someone about a young location every night is how an alert channel becomes wallpaper.

N.2 — BookingIntegration, required

• Provider enum (ServiceTitan, HousecallPro, and the rest); embed as inline_widget or modal_link.
• Required fallback: <noscript><a href="tel:{branchPhone}">Call to book</a></noscript>.
• Monitoring: GA4 booking_iframe_load_error; alert when the failure rate passes 1% for a location.
• Hard fail when neither widget nor phone fallback is present. Accepted unchanged: a booking module that fails silently with no way to call is the worst outcome on the page.

N.3 — LocalManagerEndorsement

Governed by a managerEndorsementRequired boolean in page front-matter, defaulted by the CMS:

• Gate: when the flag is true and the quote, photo or manager name is missing, the build fails. Marketing ops may flip it by hand, but the commit that flips it on carries the content too — a flag set true with nothing behind it just breaks the next build for whoever pushes after you.
• Fields: manager name, photo (lazy-loaded), quote (≤240 chars), optional branch title. personRef points at the same Person type as technician profiles.
• Added to the per-city pre-launch checklist beside the 3-project minimum.

N.4 — OfferBadgeSet (template required, content optional)

• OfferBadge[], may be empty. Fields: text (≤50 chars), expires, cityScoped. Badges auto-suppress once expired.
• Pages with active badges emit Cache-Control: max-age=3600, so an expired promo leaves the edge cache within the hour.
• An empty array past 30 days escalates to marketing ops. Dollar amounts in badge text stay governed by M.0 and allowOfferAmounts.

N.5 — TrustBadgeSet (template required, content optional)

TrustBadge[], may be empty: icon, label, linkUrl. CI warns when a label contains "guarantee" or "warranty" and linkUrl is empty. An unsubstantiated warranty claim with nothing behind it is the kind of sentence that gets read back to you later.

N.6 — FinancingBlock, reshaped by the cost rule and by lending law

N.7 — InternalLinkBudget, soft only

Counted within the primary content container only. Links inside <nav>, the global header and <footer> are excluded, via a configurable contentRegionSelector per template, defaulting to main.

That scoping is the whole point: a mega-nav carries 300+ links by design, and counting them in every page's budget produces a site-wide warning that masks the body-content bloat the check exists to find.

Warn at 150 links in the content region; the nightly report flags 200 or more. No build failure — a page can legitimately be link-dense, and this is a smell, not a defect.

N.8 — Performance instrumentation, advisory

• Hero rasters carry explicit width and height. Soft fail.
• Third-party widgets (ServiceTitan booking iframe, GBP widgets) load with loading="lazy" and fetchpriority="low". The page shell emits Cache-Control: max-age=3600 and widget behaviour is decoupled from page cacheability, so a slow widget never makes the page uncacheable.
• Warn above 3s LCP on mobile, 2.5s desktop, or CLS above 0.1. Tracked in the lab harness.

N.9 — Accessibility for conversion components

Every CTA anchor these templates render carries role="button" where it behaves as one, and a meaningful aria-label. CI fails when either is missing on a conversion CTA. Our markup, our gate.

OThe editorial tier

Three separate reviews found the same hole: this spec had nowhere to put an article that is neither a symptom page nor a comparison. Seasonal content, rebate and incentive news, community coverage, equipment guidance that does not fit a head-to-head — all of it was homeless. Homeless content is how a blog ends up with 320 posts, 93 of them linking to no service page at all, and two separate articles about AC blowing warm air.

The choice was to ban the category or to govern it. Banning it loses the seasonal and local content that earns links, so it is governed.

O.1 — Shape

• URL: /resources/[slug]/. If a client already runs /blog/, keep theirs and freeze it — what matters is that exactly one convention exists, not which word it uses.
• Required parent: parentService, exactly one, the same rule that governs problem pages. This single field stops the orphan drift, because the template generates the link up to the pillar and the pillar lists its posts back by inverse query.
• Required topicKey, unique across published posts. The second article on the same topic cannot be saved; it has to become an edit to the first.
• Content floor: 600 words, with the M.0 cost rule in full.
• Dates: datePublished and dateModified, both required, under the K.5 freshness gate.

O.3 — Consolidation, not accumulation

When the near-duplicate report flags a pair, the resolution is a merge, never quiet coexistence: the stronger page absorbs what the weaker one had, the weaker 301s to it, and the topicKey moves across. A blog that only ever accumulates is how a site ends up competing with itself for its own terms.

PService-area businesses: one location, many towns

Sections A through O assume a multi-location business: Phoenix, Scottsdale and Mesa each with a real address, real hours and its own Google listing, each getting its own LocalBusiness node.

P.0 — Which model applies

The test: would Google verify a listing at that address? Staffed premises, its own hours, its own phone, signage. If yes it is a location. If the answer is "we send a van there", it is a service area, and no amount of wanting it to rank makes it a location.

A business can be both: two real branches, each serving twenty surrounding towns. Then each branch is a LocalBusiness and each town it merely serves is a service area of the nearest one.

P.1 — Entity model

• One LocalBusiness node per real address, at the real address.
• areaServed[] on that node lists every town served.
• City pages reference that single @id. They emit no LocalBusiness of their own, no NAP, no openingHours, no geo.
• Service.provider points at the one LocalBusiness. Every @id still resolves, so the section F graph gate passes unchanged.

P.2 — URL and page model

• Intersections are unchanged: /[service]/[city]/, self-canonical, project-gated.
• The location hub becomes a service-area page at /service-areas/[city]/, carrying the city's project feed, the services offered there, response expectations, and links to that city's intersections. An index and a proof page, not a fake branch page.
• /service-areas/ indexes every town.

P.3 — What a city page may and may not claim

P.4 — Google Business Profile

• One profile, configured as a service-area business with its service area set. Not a listing per town, ever.
• gbpCid and gbpPlaceId live on the single LocalBusiness record, not on each city page.
• N.1 ReviewAggregate reads that one profile for every page on the site. The review count is the company's, because there is one company.
• The M.5 tier thresholds apply to the single profile rather than per city.

P.5 — Migrating an existing flat structure

A service-area business almost always arrives with flat URLs: /arlington/ for towns and /ev-charging-stations/ for services, both at the root, both predating any convention.

1. Freeze the registry and the convention first (section B). Migrating into a convention you have not frozen means doing it twice.
2. Map, do not guess. Existing service slug 301s to its registry slug; existing /[city]/ 301s to /service-areas/[city]/.
3. Gate G.5 applies: every redirect source must exist in the previous crawl, one source to one target, caps per PR, human review above the cap.
4. Do not migrate a page to a page you have not earned. A thin city page with no projects behind it retires to the /service-areas/ index, not to an intersection page that cannot publish yet. Redirecting a weak page into a nonexistent one loses traffic you did not have to lose.
5. Retire rather than rewrite where the old page has no place in the new structure. A 301 into the nearest true parent beats leaving an orphan live because deleting felt risky.

QUser-centred gates: UX, copy and budgets

Every gate up to here protects the crawler, the entity graph or the business. None of them protect the person on the page. A site can pass all of section F and still bury the phone number below a hero carousel, or read like it was written for a keyword rather than a homeowner. This section closes that gap, and all of it is team-controlled, so N.0 permits gating on it.

Q.1 — UX acceptance tests

The six-field rule is the one that will be argued about. Every extra field costs completions, and the fields that get added are almost always for the business rather than the customer. Name, phone, address, and what is wrong is four. A seventh needs someone to say out loud which field earns more than it costs.

Q.2 — Content linting

contentLint:
  maxGradeLevel: 8.0        # Flesch-Kincaid
  maxKeywordDensity: 3.0    # percent, per 100 words
  bannedPhrases:
    - "leading provider of"
    - "best in class"
    - "100% satisfaction guaranteed"
    - "your trusted partner"
  enforcement: warn         # override with <!--lint-disable:reason-->

Warn rather than fail, because grade level and density are heuristics and a copywriter with a reason should win. The override requires a reason in the comment, which makes the exception visible in review instead of invisible in a config file.

Q.3 — Performance and accessibility budgets

Monitored, not hard-failed, until a baseline exists. A budget set before measurement is a guess that generates noise.

performanceBudget:
  lcpDesktop: 1.2s
  lcpMobile4G: 1.8s
  totalKBGzipped: 150
  thirdPartyScripts: 2      # maximum

accessibility:
  standard: WCAG 2.1 AA
  hardFail:
    - body text contrast below 4.5:1
    - focus ring missing on an interactive element
  warn:
    - skip-nav link absent

Two third-party scripts is a real constraint, and it is usually spent before anyone checks: a booking widget, a chat bubble, a review carousel, an analytics tag and a heatmap is five. Decide which two earn it.

Rv5.1 implementation addendum, and image governance

Two things live here. First, the rules that were implemented in the build before they were written down, which is a divergence this section closes. Second, image governance, which is new.

R.0 — What was built before it was specified

Honest accounting. Each of these runs in the All Spark build today and had no home in the specification until now.

R.1 — Anchor budget scope

The budget counts links inside main only. Navigation, header and footer are excluded. A mega-nav carries a hundred links by design, and counting them turns a body-content check into a site-wide alarm that everyone learns to ignore.

R.2 — Navigation must not point at empty rooms

On production builds, a primary nav link to a page that would render only an empty state is hidden. Applies to Recent Work, which needs at least one published project, and Specials, which needs at least one active offer.

An honest empty state is correct once a visitor is on the page. Sending them there from the main navigation is not honesty, it is a dead end with a signpost. On staging the links stay visible so the structure can be reviewed.

R.3 — Disclaimer on symptom pages

Adapt the trade and the licence noun per vertical. The reason is not legal theatre: these pages describe what a homeowner can safely check, and the boundary between that and what needs a professional is the most important sentence on the page.

R.4 — Focus visibility and safe areas

• No interactive element uses outline: 0 without a visible :focus-visible replacement. A removed focus ring is a page that cannot be operated from a keyboard.
• Sticky footer elements include padding-bottom: env(safe-area-inset-bottom) so an iOS home indicator does not sit on top of the call button.

R.6 — Schema binding and formats

• Every Service node carries provider pointing at the site's LocalBusiness.
• LocalBusiness.image is a raster, 1200x630 or larger, WebP or JPEG. An SVG logo is not an image for this purpose and rich results will ignore it.
• AggregateRating carries ratingValue, reviewCount, bestRating and worstRating, and the count matches what the profile shows. The header may display a floored number; the schema carries the exact one.
• All tel: hrefs use E.164 with the country code.

Sign-off checklist

Deployment and maintenance procedures that sit outside this spec live in the operational runbook.