openapi: 3.1.0
info:
  title: TenantAtlas Homepage Surface Contract
  version: 0.1.0
  summary: Structural contract for the `apps/website` homepage in Spec 216.
  description: >-
    This contract defines the public HTML routes that participate in the
    homepage journey for Spec 216. The homepage remains a static Astro surface
    and must route visitors into Product, Trust, Changelog, and Contact while
    satisfying the required homepage section model.
servers:
  - url: http://localhost:{port}
    description: Local Astro development or preview server
    variables:
      port:
        default: '4321'
tags:
  - name: Homepage Journey
    description: Public HTML routes used by the homepage structure contract
paths:
  /:
    get:
      tags: [Homepage Journey]
      operationId: getHomepage
      summary: Homepage
      description: >-
        Product-near homepage that positions the product, explains outcomes,
        groups the product model, shows bounded trust and dated progress
        signals, and ends in one clear next-step CTA.
      x-tenantatlas-homepage-structure:
        requiredBlocks:
          - header
          - hero
          - outcome
          - capability
          - trust
          - progress
          - cta
          - footer
        orderedNarrative:
          - hero
          - outcome
          - capability
          - trust
          - progress
          - cta
        primaryCtaTargets:
          - /contact
          - /demo
        secondaryCtaTargets:
          - /product
          - /trust
          - /changelog
        onwardRoutes:
          - /product
          - /trust
          - /changelog
          - /contact
        forbiddenPatterns:
          - template-first-saas
          - abstract-only-homepage
          - feature-wall
          - fake-trust
          - multi-primary-cta
      responses:
        '200':
          description: Homepage HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
  /product:
    get:
      tags: [Homepage Journey]
      operationId: getHomepageProductTarget
      summary: Product target route
      description: Deeper product-model route linked from homepage hero or capability sections.
      responses:
        '200':
          description: Product page HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
  /trust:
    get:
      tags: [Homepage Journey]
      operationId: getHomepageTrustTarget
      summary: Trust target route
      description: Bounded trust and credibility route linked from homepage trust cues and CTA paths.
      responses:
        '200':
          description: Trust page HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
  /changelog:
    get:
      tags: [Homepage Journey]
      operationId: getHomepageChangelogTarget
      summary: Changelog target route
      description: Dated progress route linked from the homepage progress section.
      responses:
        '200':
          description: Changelog page HTML
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/HtmlDocument'
  /contact:
    get:
      tags: [Homepage Journey]
      operationId: getHomepageContactTarget
      summary: Contact target route
      description: Primary conversion route used by the homepage 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