# Deck Schema
# Schema for interactive decks: an ordered list of scenes the Deck Viewer
# Capability composes into A2UI surfaces, one per scene. A deck lives as a
# Possibility entity in the Hive (owner ruling 2026-09-16); the repository
# holds seed fixtures under content/decks/ and the publish step embeds every
# pinned excerpt and recorded artifact into the entity so rendering never
# needs a checkout. Drafted by M81.P2 E4872 S0 (#4887); finalized by S2
# (#4889) against the first deck, content/decks/agent-protocols.kno.

$schema: kno@0.0.9
id: 01M2K977G394XQB28J4YS4EBC7
slug: deck-schema
type: spec
version: 0.1.0
title: "Deck Schema"
purpose: |
  Schema for interactive decks rendered from .kno documents.

  A deck is an ordered list of scenes. Each scene carries stage copy, a body of
  catalog components, presenter notes, its sources (pinned excerpts and file
  references) and live request specs. The Deck Viewer Capability's composer
  turns each scene into one A2UI surface drawn by any host in that host's
  tokens.

  **Key Features:**
  - Scenes as the unit: kicker, title, body components, notes, sources, live
  - Body items reference pinned excerpts and recorded artifacts by key; the
    publish step embeds them (excerpts, artifacts) so the entity is
    self-contained
  - X-Ray configuration borrowing page-schema's field shape, extended with the
    deck's own layers (the A2A task, the A2UI wire, the deck source, the sources)
  - Provenance: the storyboard the deck was translated from and its pinned commit

  **Relation to page-schema:** a sibling, not an extension. A page renders a
  route and aggregates entities; a deck is composed into surfaces. The two share
  the xray idea by field shape only.

  **Where a deck lives:** as an entity of type `deck` in a Possibility's Hive,
  written and read through the per-Possibility entities API. The repository's
  content/decks/*.kno files are seed fixtures; content/decks/generated/ holds
  the published documents the publish step produced from them.
  Seed identity uses a bare 26-character Crockford ULID. The entities API may
  assign the canonical persisted identity ent_<ULID>; the deck parser accepts
  both forms and retains the supplied identity.

  **Platform paths:** live request paths, frame paths and list link hrefs start
  with a single slash. Protocol-relative URLs, backslashes and control
  characters are refused. Ordinary path, query and fragment syntax is retained;
  the rendering host owns any narrower route or origin allowlist.

provenance:
  origin:
    id: 01M2K977G394XQB28J4YS4EBC7
    timestamp: "2026-09-15T19:38:07Z"
    tool: manual-authoring

taxonomy:
  topics:
    - decks
    - demos
    - a2ui
    - rendering
  keywords:
    - deck
    - scene
    - presentation
    - a2ui
    - viewer
    - xray
    - entity

relationships:
  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification"
  related_to:
    - xri: "kno://specs/page-schema"
      reason: "Sibling schema; the xray block shares its field shape"
    - xri: "kno://specs/platform-capability-schema"
      reason: "The Deck Viewer and Deck Builder Capabilities that render and edit decks"
    - xri: "kno://specs/style-guide-schema"
      reason: "Hosts draw deck surfaces in the tokens a style guide generates"

quality:
  last_reviewed: "2026-09-16"
  review_status: review

_history:
  version: 2
  created: "2026-09-15T19:38:07Z"
  created_by: "claude"
  modified: "2026-09-16T01:20:00Z"
  modified_by: "claude"
  changelog:
    - version: "0.1.0"
      date: "2026-09-16"
      author: "claude"
      summary: "Finalized by S2 (#4889) against the first deck; the deck is a Possibility entity (owner ruling 2026-09-16)"
      changes:
        - "Added the spec block the validator enforces (scenes required; xray and provenance_note recommended; excerpts and artifacts optional)"
        - "sources[] items are objects: a pinned excerpt by key, or a file reference by path and label"
        - "live[] carries the full live-request contract (title, reads, body, extract, after, autorun, maxLines); body items reference a live spec by id"
        - "Body item kinds enumerated; code items reference an excerpt or an artifact by key; surface items draw a recorded A2UI artifact"
        - "excerpts and artifacts maps embedded at publish time so the entity needs no checkout"
        - "Instances live as entities in a Possibility's Hive; content/decks/*.kno are seed fixtures"
    - version: "0.0.1"
      date: "2026-09-15"
      author: "claude"
      summary: "Draft from the S0 design record (docs/planning/interactive-demos/deck-primitive-design.md § 6)"
      changes:
        - "Declared the deck entity: metadata, scenes[], xray, provenance"
        - "Named page-schema as a sibling and borrowed its xray field shape"

# The block scripts/validate-kno.ts --schema reads for an instance: section
# presence. The field tree under `schema:` below is the full contract; the
# composer's validator (services/pspace-api/src/a2a/deck-document.ts) enforces
# it and a drift test holds the two together (#4944 tracks the validator gap).
spec:
  status: Review
  description: |
    A deck document has identity (id, slug, type: deck, version), metadata
    (title, slug, description, audience, status) and an ordered list of
    scenes. Everything a scene shows is either stage copy, a catalog
    component, a reference to a pinned excerpt, a reference to a recorded
    artifact, or a live request spec. Published entities embed the excerpts
    and artifacts they reference, including excerpts named only by sources[].key.
    The presence of published_from selects the published form: no referenced
    excerpt may be missing and no artifact may remain a from/select fixture
    reference. Each published excerpt carries its own repository's 40-character
    lowercase git commit SHA. Each embedded artifact has an own content field:
    a JSON value for kind json, or a string for kind html or text.
  required_sections:
    - name: "identity"
      description: "BASIC tier fields (id, slug, type, version)"
    - name: "metadata"
      description: "Title, slug, description, audience, listing status"
    - name: "scenes"
      description: "The ordered scenes; each becomes one A2UI surface"
  recommended_sections:
    - name: "xray"
      description: "X-Ray configuration and the layers the deck exposes"
    - name: "provenance_note"
      description: "The storyboard the deck was translated from and the commit its excerpts are pinned to"
  optional_sections:
    - name: "excerpts"
      description: "Pinned excerpts embedded at publish time, keyed as the scenes reference them"
    - name: "artifacts"
      description: "Recorded artifacts (JSON, HTML, text) embedded at publish time, keyed as the scenes reference them"

schema:
  name: deck
  version: 0.1.0
  description: |
    Schema for interactive decks that render from .kno content. An ordered list
    of scenes composed into A2UI surfaces by the Deck Viewer Capability.
  required_fields:
    - name: metadata
      description: "Deck metadata for the hub, the shell and the copy gate"
      type: object
      required_children:
        - name: title
          description: "Deck title (the cover and the hub card)"
          type: string
        - name: slug
          description: "URL slug under the decks hub (e.g. agent-protocols)"
          type: string
          pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
      optional_children:
        - name: description
          description: "One or two sentences for the hub card and the cover"
          type: string
        - name: audience
          description: "Who the deck is for; the DevRel copy rules apply to every deck"
          type: string
          enum:
            - external
            - partner
            - internal
        - name: status
          description: "Whether the deck is listed on the hub"
          type: string
          enum:
            - draft
            - listed
            - retired
    - name: scenes
      description: "The ordered scenes; each becomes one A2UI surface"
      type: array
      items:
        type: object
        required_children:
          - name: id
            description: "Stable scene id, unique in the deck; the URL hash and the probe key"
            type: string
            pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
          - name: title
            description: "Scene title shown on stage"
            type: string
        optional_children:
          - name: kicker
            description: "Short line above the title"
            type: string
          - name: layout
            description: "The scene's stage layout"
            type: string
            enum:
              - default
              - cover
          - name: body
            description: "Catalog components drawn in the scene body, in order"
            type: array
            items:
              type: object
              required_children:
                - name: kind
                  description: "The catalog kind. code takes excerpt or artifact; liveRequest takes live; surface takes artifact; conversation takes agent"
                  type: string
                  enum:
                    - text
                    - code
                    - tabs
                    - table
                    - row
                    - column
                    - card
                    - list
                    - image
                    - frame
                    - liveRequest
                    - conversation
                    - surface
          - name: notes
            description: "Presenter notes; presenter-side by default, under the copy rules"
            type: string
          - name: sources
            description: "What the scene rests on: pinned excerpts by key, or file references by path and label"
            type: array
            items:
              type: object
              children:
                - name: key
                  description: "A pinned excerpt key in scripts/demos/sources.manifest.json; published decks must embed it under excerpts even when the scene body does not use it"
                  type: string
                - name: path
                  description: "A repository path the scene refers to"
                  type: string
                - name: label
                  description: "How the reference is labelled on stage"
                  type: string
                - name: lines
                  description: "A line range in the referenced file"
                  type: string
          - name: live
            description: "Live request specs the liveRequest component renders (platform API only)"
            type: array
            items:
              type: object
              required_children:
                - name: id
                  type: string
                - name: title
                  type: string
                - name: path
                  description: "Platform API path starting with a single slash; protocol-relative URLs, backslashes and control characters are refused; queries and fragments are allowed"
                  type: string
              optional_children:
                - name: reads
                  description: "What the room is told the request shows"
                  type: string
                - name: method
                  type: string
                  enum:
                    - GET
                    - POST
                - name: auth
                  type: string
                  enum:
                    - none
                    - session
                - name: body
                  description: "JSON body for a POST"
                  type: object
                - name: extract
                  description: "A path into the response to show (e.g. json:skills)"
                  type: string
                - name: after
                  description: "The id of the live spec whose result this one reads"
                  type: string
                - name: autorun
                  type: boolean
                - name: maxLines
                  type: number
  optional_fields:
    - name: xray
      description: "X-Ray configuration; the field shape of page-schema's xray block, plus the deck's layers"
      type: object
      children:
        - name: enabled
          type: boolean
          default: true
        - name: description
          description: "Explanation shown in X-Ray mode"
          type: string
        - name: layers
          description: "Which layers the X-ray shows for the current scene"
          type: array
          items:
            type: string
            enum:
              - a2a-task
              - a2ui-wire
              - deck-source
              - sources
        - 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: provenance_note
      description: "Where the deck came from: the storyboard it was translated from and the commit its excerpts are pinned to"
      type: object
      children:
        - name: storyboard
          description: "The page this deck was translated from, until that page retires"
          type: string
        - name: pinned_commit
          description: "The commit the excerpt snapshot was taken at (filled by the publish step)"
          type: string
    - name: excerpts
      description: "Pinned excerpts embedded at publish time, keyed by body excerpt and source key references. Each carries repo, path, sha256 and code; commit is optional in a seed and required in a published entity as that excerpt repository's 40-character lowercase git SHA"
      type: object
    - name: artifacts
      description: "Recorded artifacts embedded at publish time. A seed entry declares from (a repository JSON file) and optional select; every published entry carries kind, sha256 and an own content field. Content is a JSON value for kind json and a string for kind html or text; absent or undefined content is invalid"
      type: object