{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://quailpages.com/schema/qp.site-discovery.json",
  "title": "Quail Pages Site Discovery Knowledge Contract",
  "description": "Describes the best current factual understanding available before creative direction begins. Discovery seeks sufficiency, not completeness: every field is optional, missing knowledge remains visible, and this contract never grants or withholds permission to proceed.",
  "$comment": "Authoritative guidance: Discovery seeks sufficiency, not completeness. Unknown, inferred, assumed, and conflicting knowledge should remain explicit. Creative direction, page proposals, theme choices, layouts, and generated QP documents belong downstream and are outside this contract.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "version": {
      "const": "0.1",
      "description": "Identifies the V0.1 discovery knowledge vocabulary when a producer chooses to record a version."
    },
    "organization": { "$ref": "#/$defs/organization" },
    "mandate": { "$ref": "#/$defs/mandate" },
    "audiences": {
      "type": "array",
      "description": "People the site may need to serve, kept separate from what the site is intended to accomplish.",
      "items": { "$ref": "#/$defs/audience" }
    },
    "persuasion": { "$ref": "#/$defs/persuasion" },
    "structure": { "$ref": "#/$defs/structure" },
    "materials": { "$ref": "#/$defs/materials" },
    "requirements": { "$ref": "#/$defs/requirements" },
    "identity": { "$ref": "#/$defs/identity" },
    "preferences": { "$ref": "#/$defs/preferences" },
    "governance": { "$ref": "#/$defs/governance" },
    "epistemics": { "$ref": "#/$defs/epistemics" }
  },
  "$defs": {
    "nonEmptyString": { "type": "string", "minLength": 1 },
    "stringList": {
      "type": "array",
      "items": { "$ref": "#/$defs/nonEmptyString" },
      "uniqueItems": true
    },
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
    },
    "organization": {
      "type": "object",
      "description": "Known facts about the organization or person the site represents, including boundaries that prevent attractive but false positioning.",
      "additionalProperties": false,
      "properties": {
        "name": { "$ref": "#/$defs/nonEmptyString" },
        "legalName": { "$ref": "#/$defs/nonEmptyString" },
        "description": { "$ref": "#/$defs/nonEmptyString" },
        "history": { "$ref": "#/$defs/nonEmptyString" },
        "operatingModel": { "$ref": "#/$defs/nonEmptyString" },
        "locations": { "$ref": "#/$defs/stringList" },
        "relationships": { "$ref": "#/$defs/stringList" },
        "doesNotDo": {
          "$ref": "#/$defs/stringList",
          "description": "Explicit negative truth: services, roles, promises, or identities that must not be attributed to the organization."
        }
      }
    },
    "mandate": {
      "type": "object",
      "description": "Why the site exists or needs to change and what evidence would indicate useful progress.",
      "additionalProperties": false,
      "properties": {
        "currentSituation": { "$ref": "#/$defs/nonEmptyString" },
        "problem": { "$ref": "#/$defs/nonEmptyString" },
        "desiredChange": { "$ref": "#/$defs/nonEmptyString" },
        "successSignals": { "$ref": "#/$defs/stringList" },
        "constraints": { "$ref": "#/$defs/stringList" },
        "nonGoals": { "$ref": "#/$defs/stringList" }
      }
    },
    "audience": {
      "type": "object",
      "description": "One audience and the real situation in which that audience encounters the site.",
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/id" },
        "name": { "$ref": "#/$defs/nonEmptyString" },
        "priority": { "enum": ["primary", "secondary", "supporting"] },
        "description": { "$ref": "#/$defs/nonEmptyString" },
        "visitSituations": { "$ref": "#/$defs/stringList" },
        "needs": { "$ref": "#/$defs/stringList" },
        "barriers": { "$ref": "#/$defs/stringList" },
        "desiredActions": { "$ref": "#/$defs/stringList" },
        "currentBeliefs": { "$ref": "#/$defs/stringList" },
        "desiredBeliefs": { "$ref": "#/$defs/stringList" }
      }
    },
    "persuasion": {
      "type": "object",
      "description": "Actions, beliefs, objections, claims, and evidence that explain what the site must communicate without collapsing truth into presentation.",
      "additionalProperties": false,
      "properties": {
        "desiredActions": { "$ref": "#/$defs/stringList" },
        "currentBeliefs": { "$ref": "#/$defs/stringList" },
        "desiredBeliefs": { "$ref": "#/$defs/stringList" },
        "objections": { "$ref": "#/$defs/stringList" },
        "alternatives": { "$ref": "#/$defs/stringList" },
        "claims": {
          "type": "array",
          "items": { "$ref": "#/$defs/claim" }
        },
        "evidence": {
          "type": "array",
          "items": { "$ref": "#/$defs/evidence" }
        }
      }
    },
    "claim": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/id" },
        "statement": { "$ref": "#/$defs/nonEmptyString" },
        "importance": { "enum": ["high", "medium", "low"] },
        "support": { "enum": ["supported", "partially-supported", "unsupported", "disputed"] },
        "evidenceIds": {
          "type": "array",
          "items": { "$ref": "#/$defs/id" },
          "uniqueItems": true
        }
      }
    },
    "evidence": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/id" },
        "description": { "$ref": "#/$defs/nonEmptyString" },
        "sourceIds": {
          "type": "array",
          "items": { "$ref": "#/$defs/id" },
          "uniqueItems": true
        }
      }
    },
    "structure": {
      "type": "object",
      "description": "Known information architecture and content relationships. It records current or required truth, not proposed creative direction.",
      "additionalProperties": false,
      "properties": {
        "existingPages": { "$ref": "#/$defs/stringList" },
        "knownContent": { "$ref": "#/$defs/stringList" },
        "requiredContent": { "$ref": "#/$defs/stringList" },
        "navigationConstraints": { "$ref": "#/$defs/stringList" },
        "relationships": { "$ref": "#/$defs/stringList" }
      }
    },
    "materials": {
      "type": "object",
      "description": "Available content and media inputs, their condition, permissions, and gaps. Possessing an asset does not by itself make it evidence for a claim.",
      "additionalProperties": false,
      "properties": {
        "content": { "type": "array", "items": { "$ref": "#/$defs/material" } },
        "media": { "type": "array", "items": { "$ref": "#/$defs/material" } },
        "gaps": { "$ref": "#/$defs/stringList" }
      }
    },
    "material": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/id" },
        "description": { "$ref": "#/$defs/nonEmptyString" },
        "location": { "$ref": "#/$defs/nonEmptyString" },
        "condition": { "$ref": "#/$defs/nonEmptyString" },
        "permission": { "enum": ["cleared", "restricted", "unknown"] },
        "notes": { "$ref": "#/$defs/nonEmptyString" }
      }
    },
    "requirements": {
      "type": "object",
      "description": "Operational, legal, accessibility, privacy, integration, and delivery constraints the eventual work must honor.",
      "additionalProperties": false,
      "properties": {
        "functional": { "$ref": "#/$defs/stringList" },
        "accessibility": { "$ref": "#/$defs/stringList" },
        "legal": { "$ref": "#/$defs/stringList" },
        "privacy": { "$ref": "#/$defs/stringList" },
        "integrations": { "$ref": "#/$defs/stringList" },
        "delivery": { "$ref": "#/$defs/stringList" }
      }
    },
    "identity": {
      "type": "object",
      "description": "Existing identity truth and non-negotiable boundaries. Desired character and references live separately under preferences.",
      "additionalProperties": false,
      "properties": {
        "names": { "$ref": "#/$defs/stringList" },
        "logos": { "$ref": "#/$defs/stringList" },
        "colors": { "$ref": "#/$defs/stringList" },
        "typography": { "$ref": "#/$defs/stringList" },
        "voice": { "$ref": "#/$defs/stringList" },
        "nonNegotiables": { "$ref": "#/$defs/stringList" }
      }
    },
    "preferences": {
      "type": "object",
      "description": "Expressed tastes and desired character. These are discovery inputs rather than final creative decisions.",
      "additionalProperties": false,
      "properties": {
        "desiredCharacter": { "$ref": "#/$defs/stringList" },
        "references": { "type": "array", "items": { "$ref": "#/$defs/reference" } },
        "avoid": { "$ref": "#/$defs/stringList" },
        "openness": { "$ref": "#/$defs/nonEmptyString" }
      }
    },
    "reference": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "location": { "$ref": "#/$defs/nonEmptyString" },
        "relevantQualities": { "$ref": "#/$defs/stringList" },
        "qualitiesToAvoid": { "$ref": "#/$defs/stringList" }
      }
    },
    "governance": {
      "type": "object",
      "description": "Who may decide, approve, maintain, and exercise creative judgment, including limits on that authority.",
      "additionalProperties": false,
      "properties": {
        "decisionMakers": { "$ref": "#/$defs/stringList" },
        "approvers": { "$ref": "#/$defs/stringList" },
        "maintainers": { "$ref": "#/$defs/stringList" },
        "creativeAuthority": { "$ref": "#/$defs/nonEmptyString" },
        "reviewConstraints": { "$ref": "#/$defs/stringList" }
      }
    },
    "epistemics": {
      "type": "object",
      "description": "Provenance and uncertainty for the knowledge above. Annotations use JSON Pointers so domain values remain readable while their status and sources remain explicit.",
      "additionalProperties": false,
      "properties": {
        "sources": { "type": "array", "items": { "$ref": "#/$defs/source" } },
        "annotations": { "type": "array", "items": { "$ref": "#/$defs/annotation" } },
        "assumptions": { "type": "array", "items": { "$ref": "#/$defs/knowledgeIssue" } },
        "conflicts": { "type": "array", "items": { "$ref": "#/$defs/knowledgeIssue" } },
        "openQuestions": { "type": "array", "items": { "$ref": "#/$defs/knowledgeIssue" } }
      }
    },
    "source": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": { "$ref": "#/$defs/id" },
        "label": { "$ref": "#/$defs/nonEmptyString" },
        "location": { "$ref": "#/$defs/nonEmptyString" },
        "kind": { "enum": ["user", "document", "website", "dataset", "observation", "other"] },
        "authority": { "$ref": "#/$defs/nonEmptyString" },
        "notes": { "$ref": "#/$defs/nonEmptyString" }
      }
    },
    "annotation": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "path": {
          "type": "string",
          "pattern": "^(|/.*)$",
          "description": "JSON Pointer to the knowledge value being qualified."
        },
        "status": { "enum": ["known", "inferred", "assumed", "conflicting"] },
        "sourceIds": {
          "type": "array",
          "items": { "$ref": "#/$defs/id" },
          "uniqueItems": true
        },
        "note": { "$ref": "#/$defs/nonEmptyString" }
      }
    },
    "knowledgeIssue": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "path": { "type": "string", "pattern": "^(|/.*)$" },
        "statement": { "$ref": "#/$defs/nonEmptyString" },
        "impact": { "enum": ["high", "medium", "low"] },
        "sourceIds": {
          "type": "array",
          "items": { "$ref": "#/$defs/id" },
          "uniqueItems": true
        }
      }
    }
  }
}