{
  "schemaVersion": "starter-update-questionnaire-v1.1",
  "title": "IGNITE Starter Sitemap Builder Update Questionnaire",
  "purpose": "Reusable questionnaire for resolving assumptions in the builder-facing component knowledge contract after an IGNITE Starter/component catalogue refresh.",
  "usage": "Most Starter updates should not need this. Use it when new/changed components, variants, slots, props, recipes, or assumptions need human clarification.",
  "responseSaveEndpoint": "./api/save-questionnaire",
  "responseDirectory": "local-tools/sitemap-builder/questionnaire-responses/",
  "sections": [
    {
      "id": "update-context",
      "title": "1. Starter update context",
      "description": "Use this only when a Starter/component catalogue update introduces uncertainty, or when a new Starter baseline is being established.",
      "questions": [
        {
          "id": "starterVersionName",
          "label": "What should this Starter/component baseline be called?",
          "type": "text",
          "placeholder": "e.g. IGNITE Starter June 2026"
        },
        {
          "id": "sourceCatalogueDate",
          "label": "Which raw catalogue/source contract is this based on?",
          "type": "text",
          "placeholder": "artifacts/starter-json/YYYY-MM-DD/..."
        },
        {
          "id": "reviewOwner",
          "label": "Who is reviewing/approving these answers?",
          "type": "text",
          "placeholder": "Sylvain / Andrew / Anthony / other"
        },
        {
          "id": "targetUse",
          "label": "What is this Starter primarily for?",
          "type": "textarea",
          "placeholder": "School sites, general marketing sites, client-specific verticals, etc."
        },
        {
          "id": "mustNotAssume",
          "label": "What should I NOT assume from component names alone?",
          "type": "textarea",
          "placeholder": "Any naming conventions, misleading component names, deprecated patterns..."
        }
      ]
    },
    {
      "id": "component-selection",
      "title": "2. Component purpose and selection rules",
      "description": "Clarifies which components are preferred, optional, deprecated, or only for special cases.",
      "questions": [
        {
          "id": "recommendedComponents",
          "label": "Which components should the Sitemap Builder/agent prefer for normal page generation?",
          "type": "textarea",
          "placeholder": "List component names and any priority notes."
        },
        {
          "id": "discouragedComponents",
          "label": "Which components should generally be avoided unless explicitly requested?",
          "type": "textarea",
          "placeholder": "Deprecated, experimental, CMS-only, internal, fragile, etc."
        },
        {
          "id": "componentPurposeCorrections",
          "label": "For any component, what purpose/use-case did I infer incorrectly?",
          "type": "textarea",
          "placeholder": "Component / name → correct purpose / when to use."
        },
        {
          "id": "componentAvoidWhen",
          "label": "Are there components with specific “avoid when” rules?",
          "type": "textarea",
          "placeholder": "Section / X → avoid when..."
        },
        {
          "id": "preferredSectionOrder",
          "label": "Are there preferred section-order patterns?",
          "type": "textarea",
          "placeholder": "Hero → intro → cards → CTA, etc."
        }
      ]
    },
    {
      "id": "variant-guidance",
      "title": "3. Variant usage guide",
      "description": "This is the main missing human layer: when each exported variant should be used.",
      "questions": [
        {
          "id": "globalVariantRules",
          "label": "Are there global rules for variant names such as Primary, Secondary, Image Left/Right, No Image, Dark/Light?",
          "type": "textarea",
          "placeholder": "Confirm/correct the inferred rules."
        },
        {
          "id": "heroVariants",
          "label": "How should Section / Hero variants be used?",
          "type": "textarea",
          "placeholder": "Primary vs Secondary, homepage vs interior, image requirements, etc."
        },
        {
          "id": "ctaVariants",
          "label": "How should Section / CTA variants be used?",
          "type": "textarea",
          "placeholder": "Image Right / Image Left / No Image, final CTA vs mid-page CTA."
        },
        {
          "id": "twoColumnVariants",
          "label": "How should two-column/text-image variants be used?",
          "type": "textarea",
          "placeholder": "Image right/left/bottom and page rhythm rules."
        },
        {
          "id": "otherVariantCorrections",
          "label": "For any other component variants, what should the guide say?",
          "type": "textarea",
          "placeholder": "Component → Variant → useWhen / avoidWhen / notes."
        },
        {
          "id": "variantsNeedingHumanReview",
          "label": "Which variant decisions should remain “needs human review” rather than inferred?",
          "type": "textarea",
          "placeholder": "List components/variants."
        }
      ]
    },
    {
      "id": "slots-nesting",
      "title": "4. Slots, nesting, and allowed children",
      "description": "Clarifies what can be inserted where, especially component slots such as Cards/FAQs/Tabs.",
      "questions": [
        {
          "id": "pageSlotRules",
          "label": "How should abovePageSlot, pageSlot, and belowPageSlot be used?",
          "type": "textarea",
          "placeholder": "Hero in above, main sections in page, closing CTA below, etc."
        },
        {
          "id": "slotChildRules",
          "label": "High-level slot child rules. If unclear, use section 8 for detailed section-by-section rules.",
          "type": "textarea",
          "placeholder": "Section / Cards → Element / Card Item, min/max counts, etc."
        },
        {
          "id": "nestedSlotLimits",
          "label": "Are there min/max/recommended counts for nested children?",
          "type": "textarea",
          "placeholder": "Cards 3–4, FAQs 4–8, Tabs 3–5..."
        },
        {
          "id": "slotWarnings",
          "label": "Any slot/nesting combinations that are technically possible but should be avoided?",
          "type": "textarea",
          "placeholder": "List fragile/visually poor combinations."
        }
      ]
    },
    {
      "id": "props-values",
      "title": "5. Props and value-shape assumptions",
      "description": "Captures rules that raw Webflow exports may not fully explain.",
      "questions": [
        {
          "id": "requiredProps",
          "label": "Which props are required or should always be set for key components?",
          "type": "textarea",
          "placeholder": "Component → required props / defaults."
        },
        {
          "id": "optionalPropsToOmitWhenBlank",
          "label": "Which exported props should be omitted/unset when empty, and which should be set to an empty string to intentionally hide default text?",
          "type": "textarea",
          "placeholder": "Example: invalid HTML id props should be omitted; eyebrow may need blank string to hide default text."
        },
        {
          "id": "linkRules",
          "label": "For generated internal/external links, how should the builder choose targets and shape link values?",
          "type": "textarea",
          "placeholder": "Internal sitemap links, external URLs, email/phone links, button pairs, when to omit."
        },
        {
          "id": "richTextRules",
          "label": "Any rules for richText vs plain text props?",
          "type": "textarea",
          "placeholder": "Use innerText, allowed HTML, line breaks, lists..."
        },
        {
          "id": "imageAssetRules",
          "label": "How should image/image-alt props be handled?",
          "type": "textarea",
          "placeholder": "When required, when placeholder allowed, alt text conventions."
        },
        {
          "id": "propNameCorrections",
          "label": "Any prop labels that are misleading or need mapping notes?",
          "type": "textarea",
          "placeholder": "Button Text vs Text, Link vs Button Link, etc."
        }
      ]
    },
    {
      "id": "recipes",
      "title": "6. Page recipes and content patterns",
      "description": "Reusable recipes help the agent choose components from a brief.",
      "questions": [
        {
          "id": "homepageRecipe",
          "label": "What should a default school homepage recipe look like?",
          "type": "textarea",
          "placeholder": "Sections, variants, counts, CTA placement."
        },
        {
          "id": "admissionsRecipe",
          "label": "What should an admissions/enrolment page recipe look like?",
          "type": "textarea",
          "placeholder": "Journey steps, FAQ, CTA, form, cards, etc."
        },
        {
          "id": "learningRecipe",
          "label": "What should a learning/curriculum page recipe look like?",
          "type": "textarea",
          "placeholder": "Intro, cards, tabs, text-image, CTA."
        },
        {
          "id": "contactRecipe",
          "label": "What should a contact page recipe look like?",
          "type": "textarea",
          "placeholder": "Hero, contact details, form, map/embed, FAQ."
        },
        {
          "id": "otherRecipes",
          "label": "Any other reusable page recipes to add?",
          "type": "textarea",
          "placeholder": "Boarding, scholarships, wellbeing, international students, staff, news..."
        }
      ]
    },
    {
      "id": "refresh-governance",
      "title": "7. Refresh, merge, and governance",
      "description": "Defines how future Starter catalogue refreshes should preserve human guidance.",
      "questions": [
        {
          "id": "mergePolicy",
          "label": "When a new export arrives, what should be overwritten vs preserved?",
          "type": "textarea",
          "placeholder": "Technical metadata overwritten; guidance preserved by component/variant id/name, etc."
        },
        {
          "id": "newComponentPolicy",
          "label": "What should happen when a new component appears?",
          "type": "textarea",
          "placeholder": "Mark needsGuidance, hide from default builder until reviewed, etc."
        },
        {
          "id": "removedComponentPolicy",
          "label": "What should happen when a component/variant/prop disappears?",
          "type": "textarea",
          "placeholder": "Deprecate, warn, remove from picker, migrate recipes..."
        },
        {
          "id": "approvalThreshold",
          "label": "What changes need a changelog/review note before the builder uses refreshed data?",
          "type": "textarea",
          "placeholder": "Even if no approval gate, list what should be called out."
        },
        {
          "id": "notesForIggy",
          "label": "Anything else I should remember when maintaining this contract?",
          "type": "textarea",
          "placeholder": "Stable conventions, gotchas, examples."
        }
      ]
    },
    {
      "id": "section-by-section-slots",
      "title": "8. Section-by-section slot rules follow-up",
      "description": "Opened by Sylvain baseline: slot rules need to be confirmed section by section, preferably using slot-accepts attributes where catalogued.",
      "questions": [
        {
          "id": "slotAcceptsCatalogueSource",
          "label": "Where can the catalogue/export read slot-accepts attributes from, and what exact field names should we expect?",
          "type": "textarea",
          "placeholder": "e.g. Webflow slot custom attribute name, exported property path, examples."
        },
        {
          "id": "cardsSlotDetailedRule",
          "label": "For Section / Cards, confirm accepted child components, min/max/recommended counts, and any card variants/content patterns.",
          "type": "textarea",
          "placeholder": "Accepted children, count rules, when to leave empty, when to populate."
        },
        {
          "id": "faqsSlotDetailedRule",
          "label": "For Section / FAQs, confirm accepted child components, min/max/recommended counts, and any FAQ content rules.",
          "type": "textarea",
          "placeholder": "Accordion item rules, max visible items, question length, etc."
        },
        {
          "id": "tabsSlotDetailedRule",
          "label": "For tab/switching-tab sections, confirm accepted child components, min/max/recommended counts, and when tabs should be used.",
          "type": "textarea",
          "placeholder": "Tabs min/max, content suitability, avoid cases."
        },
        {
          "id": "multiCtaSlotDetailedRule",
          "label": "For Section / Multi CTA and similar multi-card components, confirm accepted children and when they should be populated.",
          "type": "textarea",
          "placeholder": "Multi CTA cards, counts, CTA/link rules."
        },
        {
          "id": "otherSlotComponentsDetailedRules",
          "label": "For every other slot-based section, list accepted child components and whether the slot should default empty or populated.",
          "type": "textarea",
          "placeholder": "Component → Slot → accepts → default population → min/max → notes."
        },
        {
          "id": "slotCombinationsToAvoid",
          "label": "Which technically possible slot/child combinations should the builder actively prevent or warn about?",
          "type": "textarea",
          "placeholder": "Parent component → child/component combo → why avoid."
        }
      ]
    },
    {
      "id": "props-link-followup",
      "title": "9. Prop/link/image follow-up clarification",
      "description": "Clarifies questions that were unclear in v1 and turns them into concrete builder rules.",
      "questions": [
        {
          "id": "blankTextOverrideRules",
          "label": "Which text props should be deliberately set to blank to hide default/example text, versus omitted entirely?",
          "type": "textarea",
          "placeholder": "Component / prop label → blank string or omit? Include eyebrow, subheading, paragraph, button text."
        },
        {
          "id": "headingRequiredExceptions",
          "label": "Are there heading props that can be blank/omitted, or should all visible sections have headings?",
          "type": "textarea",
          "placeholder": "Component exceptions and notes."
        },
        {
          "id": "buttonLinkPairRules",
          "label": "For button/link props, which text+link prop pairs must be set together?",
          "type": "textarea",
          "placeholder": "Component → Button Text prop + Link prop pairing; omit/hide behavior."
        },
        {
          "id": "internalLinkSelectionRules",
          "label": "How should the builder choose internal links when generating from sitemap/page content?",
          "type": "textarea",
          "placeholder": "Nearest relevant child pages, admissions/contact CTAs, next pages, same-section cards, etc."
        },
        {
          "id": "externalLinkRules",
          "label": "When should external/email/phone links be used, and what value shape should the builder produce?",
          "type": "textarea",
          "placeholder": "External URL, mailto, tel, document links, asset links."
        },
        {
          "id": "imageSupportRoadmap",
          "label": "When image props become supported, what initial rules should apply?",
          "type": "textarea",
          "placeholder": "Placeholder images, required alt text, when to leave blank, image-position variants."
        }
      ]
    },
    {
      "id": "refresh-changelog-followup",
      "title": "10. Refresh changelog and review workflow follow-up",
      "description": "Opened by Sylvain baseline: no hard approval gate, but keep a changelog and ask targeted questions when needed.",
      "questions": [
        {
          "id": "changelogFormat",
          "label": "What changelog format would be useful after a Starter catalogue refresh?",
          "type": "textarea",
          "placeholder": "Added/removed/renamed components, prop changes, variant changes, guidance needing review."
        },
        {
          "id": "questionnaireTriggerRules",
          "label": "What exact changes should trigger a new targeted questionnaire?",
          "type": "textarea",
          "placeholder": "New variants, ambiguous slot accepts, removed props, naming mismatch, unsupported prop types, etc."
        },
        {
          "id": "reviewLinkSharingPreference",
          "label": "How should I share a future questionnaire link/file for review?",
          "type": "textarea",
          "placeholder": "Slack file, local Tailscale link, Google Doc, JSON export, etc."
        },
        {
          "id": "learningMemoryPolicy",
          "label": "Which learned conventions should be stored in contract vs skill vs memory?",
          "type": "textarea",
          "placeholder": "Contract = Starter component guidance; skill = workflow; memory = stable team preference."
        }
      ]
    }
  ],
  "lastUpdated": "2026-06-03",
  "updates": [
    "Added follow-up questions from Sylvain baseline response: section-by-section slot rules, prop/link clarification, changelog/update review."
  ]
}