# Page Schema — Layer 3 Site Schema
# KNO Schema Version: 0.0.6
#
# Layer 3 schema for website pages. Provides web-specific structure:
# hero sections, navigation metadata, SEO, templates, and X-Ray support.
#
# DOMAIN: Site content rendered to HTML
# PURPOSE: Define structure for web pages that render from .kno
#
# KEY CONCEPT: Pages are .kno entities with web-specific metadata
# and content structure (hero, sections, footer, entity references).

# =============================================================================
# SCHEMA DECLARATION
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KGK3V73J9Z90V1A88F47JMVG
slug: page-schema
type: spec
version: 0.0.3

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Page Schema"
purpose: |
  Schema for website pages rendered from .kno files.

  **Key Features:**
  - Web-specific metadata (SEO, Open Graph, path, template)
  - Content structure with sections (hero, features, footer)
  - Entity references for aggregating other .kno entities (APIs, docs)
  - X-Ray support for revealing .kno source behind rendered pages
  - Template binding for Astro page generation

# =============================================================================
# RICH TIER
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73J9Z90V1A88F47JMVG
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - web
    - pages
    - site-content
    - rendering
  keywords:
    - page
    - website
    - seo
    - hero
    - template
    - xray

relationships:
  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification"
  produces:
    # Schema-level declaration: every page conforming to page-schema can be
    # served as a markdown twin (`.md` URL alongside the rendered HTML) via
    # thin transformation. Markdown twins are an agent-friendly projection;
    # see #1807 and specs/markdown-format.kno. The producer edge lives on
    # the schema (per kno-foundational-principles § Forward vs Reverse
    # Edge Storage v1.20.0).
    - xri: "kno://specs/markdown-format"
      reason: "Pages are projected to markdown twins for AI-agent consumption"
  enables:
    - xri: "kno://content/homepage"
      reason: "Homepage page entity"
    - xri: "kno://content/about-page"
      reason: "About page entity"
    - xri: "kno://content/landing-page"
      reason: "Landing page entities"
  related_to:
    - xri: "kno://specs/style-guide-schema"
      reason: "Pages use style guides for theming"
    - xri: "kno://specs/nav-schema"
      reason: "Pages include navigation"
    - xri: "kno://specs/agent-policy-schema"
      reason: "Pages surface 'For agents' affordances driven by site agent policy"

quality:
  last_reviewed: "2026-01-12"
  review_status: draft

_history:
  version: 3
  created: "2026-01-10T12:00:00Z"
  created_by: "claude"
  modified: "2026-04-23T00:00:00Z"
  modified_by: "claude"
  changelog:
    - version: "0.0.3"
      date: "2026-04-23"
      author: "claude"
      summary: "Added produces: [markdown-format] edge for agent-friendly markdown
        twins (#1807 Phase 1)"
      changes:
        - "Declared produces: [markdown-format] so pages can be served as .md
          URL twins alongside rendered HTML"
        - "Added related_to: agent-policy-schema for the 'For agents' affordance
          pattern surfaced on each page"

# =============================================================================
# SCHEMA DEFINITION
# =============================================================================
schema:
  name: page
  version: 0.0.2
  description: |
    Schema for website pages that render from .kno content.
    Provides web-specific metadata, content structure, and entity references.

  # ---------------------------------------------------------------------------
  # Required Fields (web-specific)
  # ---------------------------------------------------------------------------
  required_fields:
    # Core metadata
    - name: metadata
      description: "Page metadata for rendering and SEO"
      type: object
      required_children:
        - name: title
          description: "Page title (appears in browser tab)"
          type: string

        - name: path
          description: "URL path for the page (e.g., /, /about, /docs)"
          type: string
          pattern: "^/.*$"

      optional_children:
        - name: description
          description: "Meta description for SEO"
          type: string

        - name: template
          description: "Astro template to use for rendering"
          type: string
          enum:
            - homepage
            - default
            - docs
            - dashboard

        - name: og
          description: "Open Graph metadata for social sharing"
          type: object
          children:
            - name: title
              type: string
            - name: description
              type: string
            - name: image
              type: string
            - name: type
              type: string
              enum:
                - website
                - article
                - profile

  # ---------------------------------------------------------------------------
  # Optional Fields (content structure)
  # ---------------------------------------------------------------------------
  optional_fields:
    # Context (same as parent but with page-specific fields)
    - name: context
      description: "Page context and dependencies"
      type: object
      children:
        - name: source_repo
          type: string
        - name: related_files
          type: array
          items:
            type: string
        - name: dependencies
          type: array
          items:
            type: string

    # Main content structure
    - name: content
      description: "Page content sections"
      type: object
      children:
        - name: hero
          description: "Hero section (prominent top section)"
          type: object
          children:
            - name: title
              type: string
              required: true
            - name: tagline
              type: string
            - name: subtitle
              type: string
            - name: terminal
              description: "Terminal animation display"
              type: object
              children:
                - name: command
                  type: string
                - name: output
                  type: string
                - name: spinner
                  type: boolean
            - name: cta
              description: "Call-to-action buttons"
              type: array
              items:
                type: object
                children:
                  - name: label
                    type: string
                    required: true
                  - name: href
                    type: string
                    required: true
                  - name: style
                    type: string
                    enum:
                      - primary
                      - secondary
                      - ghost

        - name: features
          description: "Features/highlights section"
          type: object
          children:
            - name: enabled
              type: boolean
              default: true
            - name: title
              type: string
            - name: items
              type: array
              items:
                type: object
                children:
                  - name: id
                    type: string
                  - name: icon
                    type: string
                  - name: title
                    type: string
                  - name: description
                    type: string

        - name: sections
          description: "Additional content sections"
          type: array
          items:
            type: object
            required_children:
              - name: id
                type: string
            children:
              - name: type
                type: string
              - name: enabled
                type: boolean
                default: true
              - name: items
                type: array

        - name: footer
          description: "Footer content"
          type: object
          children:
            - name: enabled
              type: boolean
              default: true
            - name: text
              type: string
            - name: links
              type: array
              items:
                type: object
                children:
                  - name: label
                    type: string
                  - name: href
                    type: string

    # X-Ray support
    - name: xray
      description: "X-Ray mode configuration for revealing .kno source"
      type: object
      children:
        - name: enabled
          type: boolean
          default: true
        - name: description
          description: "Explanation shown in X-Ray mode"
          type: string
        - name: source_map
          description: "Map page elements to their .kno sources"
          type: object
        - name: show_files
          description: "Files to display in X-Ray view"
          type: array
          items:
            type: object
            children:
              - name: path
                type: string
              - name: label
                type: string
              - name: highlight
                type: string

    # Entity references (for aggregation pages like API docs, doc indexes)
    - name: references
      description: "XRI references to entities this page aggregates or links to"
      type: array
      items:
        type: object
        children:
          - name: xri
            description: "XRI to the referenced entity (e.g., kno://api/schema-api)"
            type: string
            required: true
          - name: label
            description: "Display label for the reference"
            type: string
          - name: description
            description: "Brief description of the referenced entity"
            type: string
          - name: order
            description: "Display order (lower numbers first)"
            type: integer
          - name: group
            description: "Grouping category (e.g., 'public', 'admin')"
            type: string

  # ---------------------------------------------------------------------------
  # Validation Rules
  # ---------------------------------------------------------------------------
  validation:
    rules:
      - name: path_starts_with_slash
        description: "Page path must start with /"
        check: "metadata.path starts with '/'"
        severity: error

      - name: hero_title_required
        description: "If hero section exists, title is required"
        check: "if content.hero exists, content.hero.title must exist"
        severity: error

      - name: cta_has_href
        description: "CTA buttons must have both label and href"
        check: "each cta item must have label and href"
        severity: error

# =============================================================================
# EXAMPLES
# =============================================================================
examples:
  - name: "Minimal page"
    description: "A page with just required fields"
    content: |
      $schema: page-schema@0.0.2
      id: about
      type: page
      version: 0.1.0
      title: "About Us"
      purpose: "About page for the website"
      metadata:
        title: "About — Possibility"
        path: /about

  - name: "Full homepage"
    description: "Homepage with all sections"
    content: |
      $schema: page-schema@0.0.2
      id: homepage
      type: page
      version: 0.2.0
      title: "Possibility Homepage"
      purpose: "Main landing page"
      metadata:
        title: "Possibility"
        path: /
        template: homepage
        og:
          title: "Possibility"
          type: website
      content:
        hero:
          title: "Welcome"
          tagline: "Build possibilities"
          cta:
            - label: "Get Started"
              href: /docs
              style: primary
        features:
          enabled: true
          items:
            - id: fast
              title: "Fast"
              description: "Built for speed"

  - name: "API docs page"
    description: "Page that aggregates API entity references"
    content: |
      $schema: page-schema@0.0.2
      id: api-docs-page
      type: page
      version: 0.1.0
      title: "API Reference"
      purpose: "Index page for API documentation"
      metadata:
        title: "API Reference — Possibility"
        path: /docs/api
        template: docs
      references:
        - xri: kno://api/schema-api
          label: "Schema Registry API"
          description: "JSON and XML schema access"
          group: public
          order: 1
        - xri: kno://api/kno-api
          label: "KNO Validation API"
          description: ".kno file validation"
          group: public
          order: 2

# =============================================================================
# CONTAINER TIER — Navigation Index
# =============================================================================
_index:
  - path: "identity"
    line: 18
    keywords: [ id, type, version, page-schema ]
  - path: "spec/fields"
    line: 80
    keywords: [ title, slug, layout, sections, navigation ]
  - path: "spec/layouts"
    line: 150
    keywords: [ default, dashboard, docs, landing ]
  - path: "spec/navigation"
    line: 220
    keywords: [ nav_items, xri, label, group, order ]
  - path: "examples"
    line: 300
    keywords: [ minimal, dashboard, docs-page ]

contains:
  - xri: "#identity"
    role: section
    title: "Schema Metadata"
    keywords: [ id, type, version ]
  - xri: "#spec"
    role: section
    title: "Page Schema"
    keywords: [ layouts, navigation, sections ]
  - xri: "#examples"
    role: section
    title: "Usage Examples"
    keywords: [ minimal, dashboard, docs ]