{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://quailpages.com/schema/site-building/qp.site-building-intake.json", "title": "Quail Pages Site Building Intake Contract", "description": "Describes an adaptive intake method for improving a Quail Pages Site Contract. Begin by understanding what already exists, then discover enough organizational, audience, content, operational, page-set, and imagery/media knowledge for a downstream builder to build the complete site implied by the job. Explicitly named pages are requirements, not necessarily a complete sitemap. Ask only when the answer can materially change what should be built; infer ordinary completeness needs from evidence without inventing unsupported facts. Brand discovery belongs to Style Guide Intake.", "$comment": "Authoritative guidance: Facts first. Expression second. Professional completeness is part of intake. Orient to supplied context before asking the user to restate established knowledge. Determine whether the work is greenfield, reskin, redesign, rebrand, migration/port, restructuring, replacement, or a combination. Discover not only what pages were explicitly requested but what page set the organization reasonably needs. Reason from purpose, audiences, journeys, trust, contactability, content, operational requirements, and known data practices rather than from a prescribed standard-page inventory. For privacy/legal content, gather known operational facts and preserve unknowns; never invent legal claims or business practices. Intake should leave enough knowledge and source material for the builder to actually author each planned page. Do not add pages merely to increase page count. Imagery/media discovery is part of site discovery, not a presumed later finishing pass. Determine where build imagery may come from; inventory useful supplied or existing-site media; associate relevant media or media needs with planned pages; preserve learned asset context for downstream use; and make sourcing, permission, quality, or acquisition gaps explicit. For migrations/ports, inspect relevant source-site media during discovery so the builder does not need to recrawl merely to learn what imagery exists. Supplied images should remain available through handoff with useful identity/context such as normalized filenames and grounded alt-text context when appropriate. The absence of supplied media does not imply that a site should be text-only. When imagery materially supports the site, Discovery must establish an authorized sourcing strategy—supplied assets, existing-site assets, stock, generated media, screenshots, or another approved source—and carry that strategy into the Site Contract. Discovery inventories material, reusable, or source-defining media rather than exhaustively cataloging every decorative image.", "type": "object", "additionalProperties": false, "properties": { "version": { "const": "0.5", "description": "Identifies the V0.5 site-building intake vocabulary when a producer chooses to record a version." }, "knowledgeContract": { "const": "https://quailpages.com/schema/site-building/qp.site.json", "description": "Identifies the separate Site Contract this intake is intended to improve." }, "purpose": { "type": "string", "minLength": 1, "description": "A concise explanation of why this interview is being conducted." }, "principles": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true, "description": "Human-readable operating guidance. This is not a condition or scoring language." }, "stages": { "type": "array", "items": { "$ref": "#/$defs/stage" }, "description": "Optional interview stages. Their order guides inquiry but does not require every stage or field to be completed." }, "questions": { "type": "array", "items": { "$ref": "#/$defs/question" }, "description": "Candidate questions selected adaptively according to what is already known and what could materially change subsequent work." }, "selectionPolicy": { "$ref": "#/$defs/selectionPolicy", "description": "Choose the next question according to unresolved site-building knowledge that could materially change the eventual site. Prefer existing evidence over asking the human to restate sufficiently established facts." }, "synthesis": { "$ref": "#/$defs/synthesis", "description": "Synthesis should retain consequential site facts, requirements, sources, assumptions, conflicts, open questions, the relationship to the applicable Style Guide, and a reasoned page plan with enough known content/material context for the downstream builder to author the planned pages." }, "stoppingPolicy": { "$ref": "#/$defs/stoppingPolicy", "description": "Stop when unresolved site knowledge is unlikely to materially change the downstream build and the downstream builder has enough grounded context to choose and author the complete page set. Do not stop merely because the user named a few pages; do not continue merely to fill every field." }, "siteCompletenessPolicy": { "$ref": "#/$defs/siteCompletenessPolicy", "description": "Guidance for discovering a buildable, professionally complete page set without manufacturing unnecessary scope." }, "imageryMediaPolicy": { "$ref": "#/$defs/imageryMediaPolicy", "description": "Guidance for discovering, preserving, and handing off imagery/media knowledge and sourcing authority. The absence of supplied media is not evidence that the site should be text-only." } }, "$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._:-]*$" }, "knowledgePath": { "type": "string", "pattern": "^(|/.*)$", "description": "JSON Pointer into the separate Quail Pages Site Contract." }, "stageName": { "enum": [ "context-ingestion", "organization-and-mandate", "people-and-visit-situations", "actions-beliefs-and-objections", "differentiation-truth-and-proof", "site-completeness-and-page-plan", "materials", "imagery-and-media", "operational-requirements", "style-guide-and-creative-constraints", "character-and-references", "synthesis" ], "description": "Discovery stages establish reasoning dependencies rather than a mandatory questionnaire. context-ingestion first orients to existing state and supplied sources. site-completeness-and-page-plan determines the complete page set implied by the organization, audiences, journeys, trust/contact needs, content, and operational/privacy requirements rather than assuming explicitly named pages are exhaustive. imagery-and-media establishes sourcing authority, useful media inventory, intended uses, and gaps." }, "stage": { "type": "object", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/stageName" }, "goal": { "$ref": "#/$defs/nonEmptyString" }, "guidance": { "$ref": "#/$defs/stringList" } } }, "question": { "type": "object", "description": "One candidate site-building inquiry. Conditions are plain-language guidance for an AI consumer, not an executable generalized condition language. Build on available context rather than asking the user to repeat information already sufficiently established by an appropriate source. When existing-state orientation is unresolved and consequential, clarify what already exists, the intended relationship of the new work to it, what should be preserved or changed, and how much freedom exists to reinterpret organizational story or content. Identify whether an applicable Style Guide exists; route unresolved brand identity or visual-language work to Style Guide Intake rather than solving it here. Establish imagery/media sourcing authority when consequential and not already known. Do not force the downstream builder to rediscover media that intake can inventory from supplied assets or an existing site.", "additionalProperties": false, "properties": { "id": { "$ref": "#/$defs/id" }, "stage": { "$ref": "#/$defs/stageName" }, "goal": { "$ref": "#/$defs/nonEmptyString" }, "prompt": { "$ref": "#/$defs/nonEmptyString" }, "targets": { "type": "array", "items": { "$ref": "#/$defs/knowledgePath" }, "uniqueItems": true }, "importance": { "enum": [ "high", "medium", "low" ] }, "askWhen": { "$ref": "#/$defs/nonEmptyString", "description": "Plain-language evidence that this question could materially change what comes next." }, "skipWhen": { "$ref": "#/$defs/nonEmptyString", "description": "Plain-language evidence that the answer is already sufficient or would not affect subsequent work." }, "weakAnswerSignals": { "$ref": "#/$defs/stringList", "description": "Signals such as generic claims, audience 'everyone', unexplained references, unclear relationship to an existing site or brand, generic mission/vision/value language that does not reveal actual organizational behavior or belief, or assertions without observable behavior or evidence." }, "followUps": { "$ref": "#/$defs/stringList", "description": "Possible follow-up prompts. They remain optional and are used only when they can materially improve consequential knowledge." }, "completion": { "$ref": "#/$defs/nonEmptyString", "description": "Plain-language indication that this line of inquiry is sufficient for the present work." } } }, "selectionPolicy": { "type": "object", "description": "Priorities for choosing the next useful question without turning intake into a score or completeness gate. Existing-state uncertainty is consequential when misunderstanding whether the work is greenfield, reskin, redesign, rebrand, migration/port, restructuring, or replacement could cause later work to preserve, discard, rewrite, or invent the wrong things. Organizational uncertainty is consequential when insufficient understanding of purpose, story, positioning, audiences, content, or requirements would materially weaken the site. Brand uncertainty should be identified and routed to Style Guide Intake rather than explored as visual design here.", "additionalProperties": false, "properties": { "priorityOrder": { "type": "array", "items": { "enum": [ "high-impact-conflict", "blocking-unknown", "unsupported-important-claim", "operational-constraint", "identity-boundary", "character-uncertainty" ] }, "uniqueItems": true }, "guidance": { "$ref": "#/$defs/stringList" } } }, "synthesis": { "type": "object", "description": "Guidance for reflecting current site knowledge back to the user while preserving sources, assumptions, conflicts, and unknowns. Preserve distinctions between current-state facts and desired future state; between organizational truth and marketing invention; between material that must be preserved, material that may be reinterpreted, and greenfield areas open to later creative work; and between site knowledge here and brand truth owned by the Style Guide. Preserve consequential imagery/media knowledge: allowed sources, discovered references/assets, intended page/content uses, permissions and uncertainties, and unresolved needs.", "additionalProperties": false, "properties": { "include": { "$ref": "#/$defs/stringList" }, "guidance": { "$ref": "#/$defs/stringList" } } }, "stoppingPolicy": { "type": "object", "description": "A sufficiency-oriented stopping policy. It must not require every site field and must not be interpreted as permission to proceed. Missing formal mission, vision, values, or an existing website is not itself a reason to continue questioning. Continue only when unresolved site-building knowledge could materially change subsequent work. The absence of a usable Style Guide should be surfaced for the separate Style Guide Intake rather than extending this intake into brand design. Do not treat imagery as an implicit later pass: establish a usable media sourcing strategy and preserve enough inventory/need context for planned pages, or explicitly record unresolved media dependencies. Before completing Discovery, ask whether Site/Create can fulfill the planned site's materially important imagery without independently repeating Discovery. For migrations/ports, representative or source-defining imagery should be identified where existing imagery materially contributes to meaning, credibility, product understanding, or brand expression.", "additionalProperties": false, "properties": { "signals": { "$ref": "#/$defs/stringList" }, "guidance": { "$ref": "#/$defs/stringList" } } }, "siteCompletenessPolicy": { "type": "object", "additionalProperties": false, "properties": { "principle": { "$ref": "#/$defs/nonEmptyString" }, "guidance": { "$ref": "#/$defs/stringList" }, "completenessConsiderations": { "$ref": "#/$defs/stringList", "description": "General site needs worth considering when determining whether the planned page set is complete, such as orientation, trust, contactability, operational requirements, and known privacy/data-practice needs. These are considerations, not a prescribed page inventory." } }, "description": "Guidance for reasoning about whether the discovered page set is professionally complete for the particular organization and job. Derive page needs from the evidence and Site Contract rather than maintaining a canonical list of standard pages. Media needs are part of professional completeness when imagery materially supports the organization, page purpose, source site, or Style Guide." }, "imageryMediaPolicy": { "type": "object", "additionalProperties": false, "properties": { "principle": { "$ref": "#/$defs/nonEmptyString" }, "guidance": { "$ref": "#/$defs/stringList" }, "sourceConsiderations": { "$ref": "#/$defs/stringList" }, "handoffExpectations": { "$ref": "#/$defs/stringList" } }, "description": "Imagery/media discovery establishes where media may come from, what useful media already exists, how it relates to planned pages/content, and what remains unresolved. Discovery should identify material/reusable/source-defining media, not exhaustively catalog every decorative image. Exact placement and final composition remain Site/Create responsibilities." } } }