/seo-brand-foundation

name: seo-brand-foundation
description: >
  Establish or update a brand's semantic-SEO foundation — central entity, source
  context, audience, competitors, EAV attribute inventory, and the locked-facts
  ledger. Use this whenever the user starts SEO work for a new brand or domain, says
  "onboard this brand", "set up SEO for X", "build the entity profile", mentions
  source context or central entity, or asks for a topical map / content plan for a
  brand that has no entity-profile.json yet. Always run this before topical-map-builder
  if the brand's foundation is missing. Triggers even when the user only says "let's do
  SEO for a domain" without naming this step.

seo-brand-foundation

Produce a rigorous, provenance-tagged foundation that everything downstream depends on. Getting the central entity and core/outer boundary right here is worth more than any later cleverness — a perfect map of the wrong site is still wrong.

Read `../../framework/source-context.md` and `../../framework/eav-modeling.md` before starting. Read `../../framework/00-overview.md` if you haven't this session (it sets the provenance rules you must follow).

Inputs

• Brand domain + niche (from the user).
• `brands/<slug>/config.yaml` — read it first for grounding tier and sources.

Workflow

1. **Load config.** Determine tier. Everything below adapts to what's enabled.

2. **Understand the current site (if it exists).**

• T1 (`crawl: true`): run `../../scripts/crawl_sitemap.py` then

`../../scripts/extract_page_content.py` on home, about, product/pricing, and the top few content pages to infer what the site *currently claims to be*. Record as `measured` (crawl).

• T0: `web_search` the brand + fetch the homepage to infer the same, labeled

`asserted` where you're inferring.

3. **Resolve the central entity.**

• Distinguish it from the brand name — it's *what the brand is about* (see

source-context.md "brand-as-central-entity" failure mode).

• T1 (`wikidata: true`): `../../scripts/wikidata_entity.py` to get canonical typing
• a real attribute set (`measured`). T0: type it by judgement (`asserted`).

4. **Write source context + central intent.** What the brand is, who for, how it monetizes, and the one intent it exists to satisfy. Derive the **core/outer boundary** from monetization (source-context.md). If you can't cleanly classify a topic as core or outer later, the boundary here is under-specified — fix it now.

5. **Personas + competitor entities.** 2–4 personas (needs, sophistication). Competitors via `web_search` (T0) or domain-competitor data (T2), each tagged.

6. **Brand EAV attribute inventory.** Decompose the brand's own offering into attributes (defining/unique/rare/common) per eav-modeling.md. Factual values here must be grounded — see step 7.

7. **Seed locked-facts.json.** For every concrete brand fact (price, spec, capability, stat) you'd want articles to state: confirm it with the user or a cited source, then write it to `brands/<slug>/locked-facts.json` with `source` + `verified_date`. If a fact isn't confirmed, it does NOT go in — and articles won't be allowed to state it. **Ask the user to confirm brand facts; never invent them to fill the ledger.**

8. **Emit artifacts.**

• `brands/<slug>/entity-profile.json` — must validate against

`../../templates/entity-profile.schema.json`; every factual field provenance-tagged (use `../../scripts/provenance.py`).

• `brands/<slug>/locked-facts.json` — must validate against its schema.
• Append a one-page human-readable foundation summary to the workspace

(`brands/<slug>/foundation-summary.md`).

Interview, don't assume

When information is missing (monetization details, what they refuse to cover, unverified specs), ask the user rather than guessing. The will-not-cover list and the monetization model are the two answers that most shape the map — get them explicitly.

Definition of done

• entity-profile.json validates; central entity is the subject, not the brand name.
• Core/outer boundary is stated as a rule you could apply to a new topic.
• locked-facts.json exists (may be small) with sources on every fact.
• No bare numbers anywhere: run `provenance.audit()` mentally / via the validator.

Grounding ladder

• **T0:** LLM + web_search; most fields `asserted`; entity typed by judgement.
• **T1:** + Wikidata typing (`measured`) + site crawl of claimed identity (`measured`).
• **T2:** + DataForSEO domain-competitor data for the competitor list (`measured`).