openapi: 3.1.0
info:
  title: TenantAtlas Homepage Hero Contract
  version: 0.1.0
  summary: Semantic contract for the `apps/website` homepage hero in Spec 218.
  description: >-
    This contract defines the public HTML routes that participate in the
    homepage hero journey for Spec 218. The homepage remains a static Astro
    surface and must present a clear category context, one headline, one
    supporting-copy block, one CTA pair, a product-near visual, and optional
    bounded trust cues while routing visitors into Product, Trust, Changelog,
    and Contact.
servers:
  - url: http://localhost:{port}
    description: Local Astro development or preview server
    variables:
      port:
        default: '4321'
tags:
  - name: Homepage Hero Journey
    description: Public HTML routes used by the homepage hero contract
paths:
  /:
    get:
      tags: [Homepage Hero Journey]
      operationId: getHomepageHero
      summary: Homepage hero
      description: >-
        Product-near homepage hero that positions the product, explains the
        problem space, offers one clear CTA pair, and establishes bounded
        first-read credibility without replacing the deeper Product or Trust
        surfaces.
      x-tenantatlas-homepage-hero:
        requiredElements:
          - category-context
          - headline
          - supporting-copy
          - primary-cta
          - secondary-cta
          - product-near-visual
        optionalElements:
          - trust-subclaims
        contentPriority:
          - product-and-problem-understanding
          - clear-next-step
          - product-reality
          - early-trust
          - stylistic-finish
        primaryCtaTargets:
          - /contact
          - /demo
        secondaryCtaTargets:
          - /product
          - /trust
          - /changelog
        onwardRoutes:
          - /product
          - /trust
          - /changelog
          - /contact
        mobileMeaningOrder:
          - headline
          - supporting-copy
          - cta-pair
          - product-near-visual
          - trust-subclaims
        productVisualRules:
          - derived-from-real-product-structure
          - no-generic-dashboard-wallpaper
          - no-fake-metrics
          - alt-text-must-be-product-specific
        trustSubclaimRules:
          - factually-supportable
          - concise
          - supportable-by-trust-surface
          - no-legal-or-compliance-guarantees
          - no-badge-wall
        forbiddenPatterns:
          - generic-startup-hero
          - abstract-only-hero
          - dashboard-wallpaper-hero
          - badge-overload-hero
          - sales-pressure-hero
          - compliance-theater-hero
      responses:
        '200':
          description: Homepage HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
  /product:
    get:
      tags: [Homepage Hero Journey]
      operationId: getHomepageHeroProductTarget
      summary: Product target route
      description: Deeper product-model route linked from the homepage hero.
      responses:
        '200':
          description: Product page HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
  /trust:
    get:
      tags: [Homepage Hero Journey]
      operationId: getHomepageHeroTrustTarget
      summary: Trust target route
      description: Bounded trust route that supports any public trust-adjacent hero language.
      responses:
        '200':
          description: Trust page HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
  /changelog:
    get:
      tags: [Homepage Hero Journey]
      operationId: getHomepageHeroChangelogTarget
      summary: Changelog target route
      description: Dated progress route that may be used as a secondary deepening destination from the homepage journey.
      responses:
        '200':
          description: Changelog page HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
  /contact:
    get:
      tags: [Homepage Hero Journey]
      operationId: getHomepageHeroContactTarget
      summary: Contact target route
      description: Primary next-step route used by the homepage hero until a distinct public `/demo` route exists.
      responses:
        '200':
          description: Contact page HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
components:
  schemas:
    HtmlDocument:
      type: string
      description: Server-rendered static HTML document