README-HANDOFF.txt REQUIREMENTS
==================================================

PROFILE REGRESSION GATES

The builder is not accepted only because one Golden package passes. Test all three reference builds:

- Simple / Clean: short navigation, focused section count and no more than the locked bounded-native budget.
- Standard / Brand-led: complete service-business journey and default production behavior.
- Extensive / Creative: deep page set, archive/detail recipes and expressive variants within responsive bounds.

For each fixture, verify deterministic plan fingerprinting, 100 percent approved selection coverage, component/variant root markers, Elementor Pro global parts, one-row mobile header, local media provenance, unique content, no horizontal overflow and desktop/tablet/mobile visual regression. A profile-specific failure blocks the builder standard.

Include a README-HANDOFF.txt inside the ZIP.

It must include:
- Project name


- Client info
- Pages included
- Templates included
- Sections included
- Menus included
- Expected plugin stack
- Global colors
- Global fonts
- Homepage/front page slug
- Header/footer connection notes
- Sticky header notes
- Elementor Pro Forms notes
- Yoast SEO notes
- Optional tracking recommendations, with confirmation that no tracking classes were injected
- Image/performance notes
- Unsplash/media notes
- Menu location notes for primary/footer
- Build instructions for Admatic Kit Factory
- Elementor CSS regeneration/cache notes
- Site identity notes
- Visual reference mapping summary

Per-project design blueprint:
- project.json contains design_blueprint with the project-specific reference controls and visual rules
- project.json contains design_traceability for all major homepage sections
- every traceability item is classified as OBSERVED, ADAPTED or INFERRED
- inferred sections use the established token/component family rather than unrelated generic templates
- README-HANDOFF.txt clearly identifies important areas not directly visible in the reference
- strict reference fidelity is not claimed for sections or breakpoints that were not supplied
- must_keep_rules and must_avoid_rules have been checked against the rendered frontend

- Optional fallback import instructions, if fallback ZIP/files are included
- Known limitations, if any

README must make it clear:
- Kit Factory Build is the main website creation flow
- The site should be ready after Build
- Native Elementor Website Kit export is not required by default
- Optional package/template export can be used later if the package must be moved to
another site
- The package targets Admatic Theme v1.14.2+ and Kit Factory v2.13.1+
- The site should not require opening Elementor and clicking Update for styles to appear
- Any required cache clearing or CSS regeneration must be documented clearly

==================================================
QA-CHECKLIST.txt REQUIREMENTS
==================================================

Include a QA-CHECKLIST.txt inside the ZIP.

Release status requires zero authoritative PHP package failures. When rendered reference comparison is available, it must also meet the selected fidelity threshold or request a bounded correction pass. Unavailable comparison infrastructure remains visible and cannot erase or duplicate the project.

It must include preflight checks:

Production standard:
- project_standard.id is admatic-elementor-pro-production
- project_standard.revision is 2026-07-16-modern-v5-1
- approved_component_library carries the same standard marker and includes global-header/global-footer
- strict_validation is true
- Elementor and Elementor Pro are declared as required dependencies
- Elementor Pro is active, compatible and not older than Elementor Core major/minor
- page_layout_default and every page template equal elementor_header_footer
- Elementor Canvas does not appear anywhere in the package
- global header/footer use structurally matched approved components or bounded native Elementor compositions
- each global template carries component/component_version metadata and the first root Elementor container mirrors it through admatic_component_id/admatic_component_version
- global header/footer are published Theme Builder types registered in elementor_library_type
- both templates have the exact include/general Entire Site condition
- admatic-global-header and admatic-global-footer render on every built page

ZIP/package:
- project.json is in ZIP root
- project.json includes schema_version
- project.json includes project_name
- project.json includes slug_prefix
- project.json includes inline site_settings


- All referenced files exist
- No missing images
- No empty templates
- No empty pages
- Header/footer templates are populated
- Pages have title, slug, type and populated content arrays
- Templates have title, slug, type and populated content arrays
- Homepage/front page is assigned with is_front: true
- JSON is valid
- ZIP structure is correct
- bounded intake contains no disallowed files such as checksums, source archives or executable helpers
- authoritative PHP package validation reports zero structural failures; optional package/content intelligence findings remain advisory
- every page contains at least 120 meaningful words
- every page has exactly one H1, sequential heading levels, a unique SEO title and a unique meta description
- supplied brief terms are covered and no package image is unused


Clean replacement build:
- project.json includes build_policy.clean_previous_build: true
- before each build, Kit Factory removes only content it previously generated
- old Kit Factory pages, Elementor templates, reusable sections and menus do not remain
- old Kit Factory media attachments and /uploads/admatic-kit-assets files do not remain
- old frontend Screenshot QA runs do not accumulate
- unrelated manually created WordPress pages/media/menus are never deleted

Global styles:
- Global colors are included
- Global fonts are included
- Widgets reference global styles where possible
- Buttons/cards/sections use design tokens
- Elementor defaults are not left unchanged

Color contrast/readability:
- Normal text has readable contrast against background
- Headings have readable contrast
- Buttons have readable contrast
- Footer text is readable
- Card text is readable
- Text over images uses overlay where needed
- Dark sections use light/off-white readable text
- Muted text is not too dark on dark backgrounds
- CTA buttons are readable in normal and hover states

Layout:
- Elementor containers are used
- No flexbox Wrap is used
- Grid is used where it makes sense
- Repeated info boxes use explicit grid
- Repeated service cards use explicit grid
- Repeated benefit cards use explicit grid
- Repeated review cards use explicit grid
- Repeated price cards use explicit grid
- 6-card/info sections use 3 columns x 2 rows on desktop
- Tablet/mobile fallbacks are included
- No unusual negative margin layout hacks
- No horizontal overflow

Menus:
- menus[] is included where relevant
- Primary Menu is defined
- Menu location is defined as primary
- Footer menu location is defined as footer where included


- Header and footer use Elementor Pro Nav Menu widgets
- Header includes an intentional navigation area
- No raw HTML navigation fallback is used
- Menu links match page slugs
- Package targets Admatic Theme menu locations: primary and footer
- Kit Factory should not show menu-location or missing Nav Menu widget warnings after
build

Plugin adapters:
- Sticky Header Effects adapter included
- Sticky Header Effects Enable is prepared to be ON
- Elementor Pro Forms adapter included
- Yoast SEO recommendations included
- Optional tracking recommendations are documented without injecting Elementor classes
- Performance image notes included
- Menu/header/footer adapter included
- Mobile CTA adapter included where relevant

Media:
- Unsplash placeholders used when client images are missing
- All image files are included locally under /assets/images/
- Reference screenshots are not used as cropped assets
- Images have clean filenames
- Images have alt text
- No oversized images where avoidable
- Duplicate image usage is avoided
- Media manifest is included in project.json/assets.images
- Every assets.images item has a local path, filename, alt text, usage and import_to_media_library: true
- Remote source URLs are only stored as credits/metadata, not live Elementor image sources
- client_asset entries use truthful client-provided:// provenance (or a real HTTPS source), client/business provider and ownership credit; no public URL is invented
- external photography entries use real HTTPS source/credit URLs
- Image references are connected in Elementor content arrays through importable local asset keys or paths
- Placeholder images are real photographic images, not generated graphics
- No AI-style abstract placeholder images are included
- No uploaded reference screenshot has been cropped, recreated, traced or reused as an
asset
- Images follow reference radius/cropping/treatment
- Images inside rounded cards retain rounded corners
- The package fails if images are only remote URLs, missing from /assets/images/, missing from the media manifest, or not importable into WordPress Media Library


Strict/golden fixture QA:
- golden_test_contract defines exact fixture counts
- required blueprint fields and section contracts are present
- required component IDs/versions exist in both canonical template metadata and generated Elementor root settings
- golden images are genuine locally bundled photographs, not generated illustrations
- every golden image includes provider, credit, source URL, generation_method and local path
- golden validation fails if fixture images are missing, too small, generated or remote-only

Visual/design QA:
- The frontend does not look plain, unfinished or wireframe-like.
- The design clearly follows the uploaded reference layout, spacing, card style, typography
direction, section rhythm and visual hierarchy.
- All styling is implemented in Elementor widget/container/responsive settings and global Site Settings.
- project.json assets.css is empty and no design stylesheet or Elementor custom CSS is present.
- Every page and section CSS Classes field is empty.
- the rendered site does not fall back to a generic white/default Elementor presentation.
- The site remains professionally styled without helper CSS.
- Hero section resembles the reference visual hierarchy.
- Header resembles the reference direction.
- Footer is styled and complete.
- CTA sections are visually distinct.
- Cards are designed, aligned and not plain.
- Mobile layout still feels designed.


Theme Builder condition QA:
- Header template conditions use Elementor-safe string format.
- Footer template conditions use Elementor-safe string format.
- Conditions use ["include/general"] or another confirmed Elementor-compatible string
format.
- No header/footer condition is stored as an object or nested array.

Elementor CSS / cache QA:
- Elementor CSS regenerated after build
- CSS exists for imported pages
- CSS exists for imported templates
- Elementor Site Kit/global CSS regenerated where possible
- WP Rocket/cache cleared if active
- Frontend styling appears before manually editing any Elementor page/template
- Header styling appears before manually editing header
- Footer styling appears before manually editing footer
- Frontpage styling appears before manually editing frontpage

Site identity QA:
- WordPress site title is set to client/business name
- Tagline is relevant
- Site title does not remain "My new WordPress installation"
- Yoast/site schema does not use default placeholder name where possible
- Homepage is assigned correctly

Post-build checks:
- Homepage is assigned correctly
- Header appears globally
- Footer appears globally
- Header and footer markers are present in rendered HTML for every built page
- Menu appears correctly
- Primary menu is assigned to primary
- Footer menu is assigned to footer if included
- Mobile menu works
- Mobile header keeps brand/logo and burger toggle aligned on one row without wrapping
- Desktop header CTA is hidden on mobile and does not create a second row
- Global colors appear in Elementor Site Settings
- Global fonts appear in Elementor Site Settings
- Sticky Header Effects panel shows Enable = On where supported
- Global header Advanced > Position remains Default, never Fixed or Absolute
- Desktop brand/navigation/action zones are nested, vertically centered and sized auto/1fr/auto inside the measured content width
- Sticky header works after plugin activation
- All pages open in Elementor
- All forms render correctly or fallback block appears
- Buttons work
- Phone links work
- Email links work
- No page or section classes were injected into Elementor content
- Mobile layout works
- Tablet layout works
- Images load correctly
- No horizontal scroll


- No broken icons
- No empty sections
- Site is ready after Kit Factory Build
- Admatic Theme ecosystem dashboard should show correct readiness data where possible

==================================================
AUTOMATED FRONTEND SCREENSHOT QA - OPTIONAL ADVISORY
==================================================

After Kit Factory Build, desktop, tablet and mobile renders are evaluated by region. When external capture/comparison is unavailable, the Modern Golden Standard V5.1 structural benchmark remains active and actionable.

Kit Factory v2.13.1+ supports optional frontend screenshot QA after build. The project package must
include canonical screenshot viewport metadata, reference geometry and region-weighted correction controls. Failed critical regions are patched and rerendered on the same project up to three times.

Add this object to project.json unless a stronger custom configuration is needed:

"frontend_screenshot_qa": {
  "max_pages": 5,
  "viewports": [
    { "name": "desktop", "width": 1440, "height": 1200 },
    { "name": "tablet", "width": 834, "height": 1200 },
    { "name": "mobile", "width": 390, "height": 1100 }
  ]
}

Screenshot QA must check real frontend URLs for:
- Homepage
- Important subpages such as Ydelser and Kontakt
- Desktop viewport
- Tablet viewport
- Mobile viewport
- Header before scroll
- Header after scroll where possible
- Footer
- Hero section
- Repeated card/info sections
- Contact form section
- CTA sections

The screenshot QA output should be reviewed for:
- Missing Elementor CSS
- Header/footer appearing unstyled
- Plain/unfinished wireframe-looking sections
- Dark text on dark backgrounds or low-contrast muted text
- White/gold text on bright images without overlay
- Missing or broken images
- Desktop card grids stacking 1x1
- Horizontal overflow
- Oversized mobile headings
- Buttons that are hard to tap on mobile
- Sticky header color/readability problems
- Mobile header brand and burger toggle stacking vertically, wrapping or drifting onto separate rows
- Desktop header CTA still visible in the compact mobile header

When screenshots are available, these findings create actionable repair recommendations: missing styling, unreadable text, unstyled header/footer, missing CSS, 1-column desktop card grids, broken images, horizontal overflow, visual-reference drift, or an invalid compact mobile header. Apply no more than three corrections to the same project.

README-HANDOFF.txt must mention:
- Frontend Screenshot QA runs automatically after build
- Screenshots are stored under wp-content/uploads/admatic-kit-factory/frontend-qa/
- Automated capture requires local headless Chrome/Chromium or an internal
  ADMATIC_SCREENSHOT_QA_ENDPOINT
- If no screenshot engine is available, the build report should show a non-blocking advisory warning

QA-CHECKLIST.txt must include:
- Its report and any reference-comparison findings are attached to workflow status
- If captured, desktop screenshot checked
- If captured, tablet screenshot checked
- If captured, mobile screenshot checked
- Header/footer styling visible before opening Elementor
- Repeated card/info sections are not 1-column stacks on desktop
- Text contrast/readability confirmed from screenshots
- Broken images checked from screenshots
- No horizontal overflow confirmed from screenshots

Do not rely only on:
- JSON validation
- ZIP structure validation
- Elementor editor preview
- Package schema checks

The built frontend URL and screenshots should be reviewed when available without blocking ZIP release.


==================================================
AUTOMATED CENTRAL SCREENSHOT QA - OPTIONAL ADVISORY
==================================================

The Admatic stack may use a central Screenshot QA endpoint when configured.
The project package should include frontend_screenshot_qa configuration, but it must not require the user to manually add endpoint or secret values for each new project.

Expected behavior after Kit Factory Build:
- Kit Factory uses the configured Admatic central Screenshot QA endpoint automatically.
- Desktop, tablet and mobile screenshots are captured for the frontend URLs.
- Screenshots are saved to the WordPress uploads folder and displayed in the build/QA report.
- If the target site is not publicly reachable, Screenshot QA may warn, but it must not corrupt the build.
- The generated package must still include README/QA checklist notes that screenshots should be reviewed by a human for visual reference match.

Do not include endpoint secrets inside project.json.
The endpoint/secret belongs to the internal Admatic plugin configuration, not client project packages.


PROMPT PLAN / ASSET INTAKE GATES
- The provisional planner reports approved candidate coverage, not zero locked coverage. With planned slots present, approvedSelections must be greater than zero and approvedPercent must represent candidate coverage.
- planningDigest or provisionalFingerprint is present before Core resolution; canonical fingerprint remains Core-owned and may be blank until configure-pages.
- templateStructureContract is present, names a supported family and meets its region targets unless measured reference evidence documents a deviation.
- The rendered page is not flattened into a generic four-section structure when the selected family requires deeper architecture.
- Every Project Wizard upload appears as a WordPress Media Library attachment and survives navigation/reload.
- The active logo has attachmentId, URL, brand-logo role and a real header binding.
- Reference screenshots remain evidence only; none are used as production page media.
- Deleting a wizard asset removes only an Admatic-owned attachment and updates all prompt URL fields without a full page reload.

==================================================
PREFLIGHT BEFORE DELIVERY
==================================================

Before giving the final answer:
- Build the project package ZIP
- Build optional Elementor JSON fallback ZIP only if relevant
- Inspect the ZIP contents
- Verify project.json is in the ZIP root
- Validate JSON syntax
- Check schema_version is included


- Check project_name, slug_prefix and site_identity are included
- Check that pages/templates/sections have populated content arrays
- Check that every page/template/section has title, slug and type
- Check that homepage has is_front: true
- Check that header/footer exist and are populated
- Check that header/footer have location and conditions
- Check that site_settings is inline in project.json
- Check that global colors/fonts are defined
- Check that WCAG-safe text/background color pairs are used
- Check that menus[] is included where relevant
- Confirm the package targets Admatic Theme v1.14.2+, central Admatic Core v2.14.1+ and Kit Factory v2.13.1+ menu locations: primary and footer
- Check that the main menu uses location: "primary"
- Check that footer menu uses location: "footer"
- Check that both global header and global footer use Elementor Pro Nav Menu widgets
- Check that the header root uses row/nowrap/space-between/center controls, the brand is a real Image/Site Logo or native Heading wordmark, Nav Menu Full Width is Yes, the brand and menu widgets have auto mobile width, and every header CTA Button has hide_mobile: "yes". Header role markers on wrapper containers fail this check.
- Check that every page, section, template, container and widget leaves Elementor Advanced > Position at Default with no direct position or offset settings
- Check that every page has an explicit native Elementor background and CTA banners use internal padding without external margins
- Check that reused page slugs replace stale Yoast title, description, focus keyword, canonical, social and schema values, and that every page contains project-specific AEO question, concise answer and query targets
- Reject packages that depend on Kit Factory auto-insertion or raw HTML navigation instead of shipping complete global templates
- Confirm Kit Factory should not show menu-location or missing Nav Menu widget warnings
after build
- Check that plugin-adapter files exist
- Confirm Sticky Header Effects settings are prepared to be enabled, not only class-ready
- Check that image references are valid
- Confirm all image files are included locally under /assets/images/
- Confirm every image is listed in project.json assets.images with import_to_media_library: true
- Confirm Elementor image widgets/backgrounds use local asset keys/paths, not remote-only URLs
- Confirm remote Unsplash/source URLs appear only as source/credit metadata
- Confirm Kit Factory media import summary should show imported/reused local images and 0 remaining remote image URLs
- Check that Unsplash/client images are connected inside Elementor content arrays
- Check that no reference screenshot crops are used as placeholder assets
- Check that README-HANDOFF.txt exists
- Check that QA-CHECKLIST.txt exists
- Confirm there are no empty templates or obvious broken references
- Confirm no flexbox Wrap is used
- Confirm grid is used where it makes sense for repeated card/info sections
- Confirm repeated info boxes/cards are not built as desktop 1-column stacks unless
intentionally required
- Confirm no generated/AI-style placeholder images are included
- Confirm every placeholder image is a real photographic image from Unsplash or another
approved real-photo source
- Confirm image source URLs are documented in the media manifest
- Confirm no uploaded visual reference image was reused, cropped, traced, recreated or
generated into a placeholder asset
- Confirm the complete visual design is implemented in Elementor widget/container/responsive settings and global Site Settings
- Confirm assets.css is empty and no project stylesheet or Elementor custom CSS is present
- Confirm the finished frontend should not look plain, unfinished or wireframe-like after Build
- Confirm header/footer Theme Builder conditions use Elementor-safe strings such as
["include/general"]
- Confirm no Theme Builder condition is stored as an object, nested array or malformed
condition value
- Confirm Elementor CSS regeneration/cache-clearing requirements are included
- Confirm the site should not require opening Elementor and clicking Update for styles to
appear
- Confirm site_identity is present and site identity is prepared without default WordPress placeholder values


- Confirm frontend screenshot QA requirements are included

Do not say the package is complete unless the files have actually been created and verified.

==================================================
FINAL RESPONSE FORMAT
==================================================

Final response should include only:
- Download link to the Admatic Kit Factory project package ZIP
- Optional download link to Elementor JSON fallback ZIP, only if created
- Very short build note

CANONICAL BASELINE AND ADAPTER GATES
Reject a new package when canonical_baseline is absent, referenceGeometry does not identify admatic-licensed-inspiration-corpus-v2 revision 2026-07-16-modern-v5-1, the adapter manifest is not V3, any of the 17 named adapter files is absent, baseline/optional counts are not 14/3, or aggregate manifest/data files are counted as functional adapters.

ADMATIC REFERENCE-FIRST RELEASE GATE V4 — MANDATORY
- A reference-led project cannot pass from schema validation, capture success, baseline creation or structural heuristics alone.
- comparison.available=false, comparisons=0, baselineCreated-only, structural-advisory or missing viewport mapping must set releaseReady=false.
- Structural analysis is advisory and may identify corrective controls, but it may never contribute synthetic perfect region scores or satisfy rendered reference comparison.
- Header, hero, sections, typography, imagery and footer each have independent minimum thresholds. A failed critical region triggers same-project correction even when the weighted average passes.
- Approved components require measured structuralMatch.score >= 0.96 plus evidence. Otherwise use admatic.native-composition.v2. Never silently substitute utility-message, global-header/classic or global-footer/columns in a reference-led plan.
- The header brand Image control may bind only to an assetRole=brand-logo manifest entry. With no valid brand logo, render a native text wordmark. Any content-photo in the brand control is a blocking validation failure.
- Prefer explicit Elementor Grid containers for repeated structures. Flexbox wrap is forbidden for card, feature, service, testimonial, price and gallery collections.
- Supported global-part families include overlay navigation, centered-logo split, utility-bar + primary, editorial asymmetric, contact-heavy footer, editorial wide footer, compact legal footer and CTA-led footer. Select by measured geometry, not industry defaults.



MODERN GOLDEN STANDARD V4 — CREATIVE EXPRESSION CONTRACT
- Visible reference evidence is authoritative. Reconstruct its section sequence, geometry, media rhythm, visual density, hierarchy, surface changes and conversion flow before selecting components.
- Do not default to repeated bare heading/text card grids. A standard homepage should normally contain 10–14 distinct visual regions; inner pages should normally contain 6–10.
- Approved components are optional candidates, not mandatory output. Use them only at measured structural match >= 0.96. Otherwise use expressive admatic.native-composition.v2 structures.
- Creative freedom is open inside native Elementor controls. Use Grid, nested containers, images, galleries, counters, icons, icon lists, testimonials, forms, accordions, tabs, carousels, dividers, backgrounds, overlays, borders, radii, soft shadows, typography and responsive controls.
- Hard restrictions only: direct Position remains Default; no custom CSS; no HTML widgets; no flex wrap; no arbitrary tracking/design classes. Multi-column layouts use native Elementor Grid with explicit desktop/tablet/mobile columns.
- Modern surface language: subtle 1px borders, 12–32px radii, soft low-opacity shadows, alternating dark/light or accent/quiet regions, deliberate image crops and clear content max-widths. Avoid every section looking like the same flat dark rectangle.
- Mobile must satisfy document.scrollWidth <= document.documentElement.clientWidth + 1 at 390px. Clear fixed/oversized widths, negative margins and multi-column mobile grids; mobile grids collapse to one column.
- Use at least four media-led regions on a standard homepage when enough media is available. Prefer editorial split layouts, image mosaics, location cards, quote/proof panels and richer CTA/footer transitions.

MODERN V5 REJECTION RULES
- Reject when a page section uses a curated component without the configured structural-match evidence.
- Reject when the package declares a universal fixed padding table instead of reference-relative rendered rhythm.
- Reject when the final render has unexplained blank vertical runs, mobile horizontal overflow, direct positioning, flex wrapping, custom CSS, custom JavaScript or HTML widgets.
- Do not treat capture-only structural heuristics as satisfying required rendered-reference comparison.
