The Blueprint

The blueprint is the structured description of a business that Yoshi turns into a site. It's the input — a directory of JSON (+ markdown for docs) — and it's the single source of truth: the skeleton is content-free, so everything a site says or shows is declared here.

The shape

  blueprint/
    config.json        # identity: brand, niche, contact, colours, displayFont, siteType
    products.json      # the services (→ a page each, × every area)
    cities.json        # the service areas / neighbourhoods
    reviews.json       # real reviews (optional)
    blog-posts.json    # posts (optional; one starter is seeded if empty)
    images.json        # sourced/matched photos (optional)
    fr/                # the FR locale (optional): config/products/cities/faqs
    content/*.md       # docs-type only: one md per page (frontmatter → nav)

config.json is the only required file for a docs site; pSEO additionally needs products.json + cities.json (the page taxonomy is their cross-product).

Three layers (why it's declarative)

Yoshi separates presentation from content so the same skeleton individuates per business:

  1. L1 — the skeleton — pure presentation + variants. No hardwired copy, icons, links, or language.
  2. L2 — the blueprint — declares all content + structure: copy, icons, links, menus, the page taxonomy, variant picks, data. This page.
  3. L3 — intake — the conversation (or a scrape) that produces the blueprint.

The acid test: any literal English/French string in the skeleton is a bug — it belongs in the blueprint.

Validation

yoshi validate <blueprint> runs a MUST/SHOULD report (brand, niche, tagline, contact, address, colours must be non-empty for pSEO). Generation refuses to run on MUST failures unless you pass --skip-validate. Docs sites skip the pSEO validation + image gate automatically.

Where it comes from

You rarely hand-write a blueprint. The intake agent grows it from a seed (a name, or a URL) — scraping what the world already knows (services, reviews, photos, hours) and synthesising the rest. The blueprint is the contract between intake and generation: get it right, and the same deterministic build always produces the same site.