docs: require fidelity-first Astro migration

AGENTS.md

@@ -1,5 +1,16 @@
 # AGENTS.md
 
+## Instruction precedence
+
+This file is the authoritative project policy for all editors and AI agents.
+`MIGRATION_BRIEF.md` supplies detailed implementation guidance and must be read
+with this file. If the two files appear to conflict, follow `AGENTS.md` and
+update the conflicting documentation before continuing.
+
+The `migration-foundation` branch is a reference and recovery point only. It is
+not the visual or architectural source of truth. Reuse its nonvisual tooling or
+content only after verifying it against the live public site.
+
 ## Project
 
 This repository contains a mirrored copy of the Arizona Institute for Autism website.
@@ -26,9 +37,29 @@ Do not modify, move, rename, or delete `./www.azinstitute4autism.com`.
 
 Treat the mirror as read-only raw source material.
 
+The live public website is the single source of truth:
+
+```txt
+https://www.azinstitute4autism.com
+```
+
+Use the mirror as a convenient local extraction and inspection aid only. The
+mirror may contain stale, missing, rewritten, or incorrectly downloaded
+content and assets. Verify content, design, URLs, metadata, assets, and
+responsive behavior against the live public site before treating them as
+authoritative. When the live site and mirror disagree, follow the live site and
+document material discrepancies.
+
 ## Primary goal
 
-Create a clean, maintainable Astro + TypeScript site in `./www` that reproduces the current public site as faithfully as practical while replacing HubSpot-generated structure with a future-friendly static site architecture.
+Create a clean, maintainable Astro + TypeScript site in `./www` that faithfully
+reproduces the current public site's content, visual design, page structure, and
+responsive behavior while replacing HubSpot-generated implementation details
+with a future-friendly static site architecture.
+
+This is a fidelity-first migration, not a redesign. The live public site is the
+source of truth for both content and presentation. Maintainability must improve
+the implementation without materially changing what visitors see.
 
 The new site should be suitable for:
 
@@ -149,13 +180,31 @@ Do not invent large Arabic or Spanish translations unless source content is avai
 
 ## Design rules
 
-The new design should be mostly faithful to the current site while becoming more maintainable.
+The new site must remain visually faithful to the live public site. Do not
+reinterpret, modernize, simplify, or genericize the design unless a specific
+change is required for accessibility or reliable responsive behavior.
+
+Preserve each source page's:
+
+- section order and visible content
+- typography, font weights, and text hierarchy
+- colors, backgrounds, and decorative treatments
+- container widths, spacing, alignment, and proportions
+- imagery, crops, icons, borders, radii, and shadows
+- header, navigation, footer, calls to action, and forms
+- desktop and mobile responsive behavior
+
+Reuse exact source assets and locally available fonts wherever practical.
+Do not replace distinctive source sections with generic cards, generic heroes,
+or a new site-wide layout merely to make component reuse easier.
 
 Use plain CSS with design tokens.
 
 Create reusable Astro components for repeated layout sections.
 
-Do not create a messy page-by-page clone of HubSpot output.
+Component boundaries must follow genuinely repeated source patterns. Distinctive
+pages and sections may retain page-specific markup and CSS when abstraction
+would reduce fidelity. Do not copy HubSpot's generated DOM or CSS wholesale.
 
 Favor:
 
@@ -163,10 +212,31 @@ Favor:
 - reusable components
 - organized CSS
 - clear data files
-- consistent spacing
+- source-faithful spacing
 - accessible markup
 - predictable file structure
 
+### Visual validation
+
+Before implementing a page family or shared component:
+
+1. Inspect the live page and its HTML, CSS, assets, and responsive behavior.
+2. Use the mirror to accelerate local extraction and inspection.
+3. Resolve any discrepancy in favor of the live public site.
+4. Record the source structure and important visual details.
+5. Identify which patterns are truly shared and which are page-specific.
+
+After implementation, compare the Astro output with the live public site at
+representative desktop and mobile viewport widths. Check the full page, not
+only the header or first viewport. Fix material differences before treating the
+page as complete.
+
+Document intentional visual deviations and their reasons in:
+
+```txt
+reports/migration-summary.md
+```
+
 ## URL and SEO rules
 
 Preserve existing public URL paths whenever possible.
@@ -294,9 +364,11 @@ reports/migration-summary.md
 
 Before large filesystem changes:
 
-1. Inspect the mirror.
+1. Inspect the live public site.
-2. Summarize the implementation plan.
+2. Inspect the mirror and identify relevant discrepancies.
-3. Proceed methodically.
+3. Inspect the relevant source HTML, CSS, and assets in detail.
+4. Summarize the implementation and visual-validation plan.
+5. Proceed methodically.
 
 At the end of a task, summarize:
 
@@ -307,4 +379,7 @@ At the end of a task, summarize:
 - audit results
 - unresolved issues
 
-Prioritize a clean, maintainable foundation over a pixel-perfect but messy clone.
+Prioritize visual fidelity and content correctness while implementing them with
+clean, maintainable Astro code. Do not trade away visible source design for a
+generic foundation, and do not copy HubSpot-generated implementation merely to
+obtain fidelity.

CLAUDE.md

@@ -36,19 +36,24 @@ For the migration task:
 
 1. Read `AGENTS.md`.
 2. Read `MIGRATION_BRIEF.md`.
-3. Inspect the local mirror.
+3. Inspect the live public site as the single source of truth.
-4. Provide a concise implementation plan.
+4. Inspect the local mirror as a convenient extraction aid and identify
-5. Scaffold or update the Astro project in `./www`.
+   relevant discrepancies.
-6. Build extraction, crawl, audit, sitemap, and redirect tools.
+5. Inspect the relevant live HTML, CSS, assets, and responsive behavior.
-7. Extract content, media, metadata, navigation, and forms.
+6. Provide a concise implementation and visual-validation plan.
-8. Refactor into reusable Astro components.
+7. Scaffold or update the Astro project in `./www`.
-9. Configure Astro content collections and Front Matter CMS.
+8. Build extraction, crawl, audit, sitemap, and redirect tools.
-10. Add English, Arabic, and Spanish structure.
+9. Extract content, media, metadata, navigation, and forms.
-11. Add RTL CSS for Arabic.
+10. Refactor genuinely repeated patterns into reusable Astro components.
-12. Add SEO, sitemap, robots, redirects, and reports.
+11. Compare rendered pages with the live site at desktop and mobile widths.
-13. Run build and audits.
+12. Configure Astro content collections and Front Matter CMS.
-14. Fix practical errors.
+13. Add English, Arabic, and Spanish structure.
-15. Document incomplete items in `reports/migration-summary.md`.
+14. Add RTL CSS for Arabic.
+15. Add SEO, sitemap, robots, redirects, and reports.
+16. Run build and audits.
+17. Fix practical errors.
+18. Document incomplete items and intentional visual deviations in
+    `reports/migration-summary.md`.
 
 ## Important Claude-specific behavior
 
@@ -60,6 +65,15 @@ When asked to begin migration, first read the relevant project files, then work
 
 Treat `./www.azinstitute4autism.com` as read-only source material.
 
+Treat the live public site as the single content and visual source of truth.
+Use the mirror only as a convenient local extraction and inspection aid. When
+the live site and mirror disagree, follow the live site and document material
+discrepancies. This migration is not a redesign. Do not substitute a generic
+visual system for the live design.
+
+Treat the `migration-foundation` branch as reference-only. Do not use it as the
+visual baseline.
+
 Do not delete or overwrite raw source assets.
 
 Do not remove files unless you are certain they are generated output in `./www`.

MIGRATION_BRIEF.md

@@ -1,5 +1,18 @@
 # MIGRATION_BRIEF.md
 
+## Authority and interpretation
+
+Read and follow `AGENTS.md` first. It is the authoritative project policy; this
+brief provides detailed implementation guidance. If any wording here appears
+to conflict with `AGENTS.md`, follow `AGENTS.md` and correct this brief before
+continuing.
+
+This is a fidelity-first migration, not a redesign. The raw mirror is a
+convenient local extraction and inspection aid, but the live public site is the
+single content and visual source of truth. The `migration-foundation` branch
+may be consulted for nonvisual tooling and recovered content, but it must not
+be used as the visual baseline.
+
 ## Task
 
 Migrate the public Arizona Institute for Autism website from a mirrored HubSpot-generated static copy into a clean, maintainable Astro + TypeScript site.
@@ -24,15 +37,21 @@ wget --mirror --page-requisites --adjust-extension --convert-links --no-parent h
 
 There is no HubSpot export, no HubSpot CLI access, and no HubSpot API access.
 
-Use the local mirror as the primary source.
+Use the live public website as the single source of truth:
-
-If internet access is available, also crawl the live public website to catch missing URLs or assets:
 
 ```txt
 https://www.azinstitute4autism.com
 ```
 
-The live crawl is only for comparison and gap-filling. The local mirror remains the source of truth.
+Use the local mirror as a convenient extraction and inspection aid. It may
+contain stale, missing, rewritten, or incorrectly downloaded content and
+assets. Verify content, design, URLs, metadata, assets, and responsive behavior
+against the live site. When the live site and mirror disagree, follow the live
+site and document material discrepancies.
+
+If the live site is temporarily unavailable, work that depends on its authority
+must remain explicitly unverified rather than silently treating the mirror as
+authoritative.
 
 ## High-level goal
 
@@ -49,7 +68,7 @@ Create a new Astro site in `./www` that is:
 - SEO-conscious
 - accessible
 - maintainable
-- mostly faithful to the current design
+- faithful to the current design, layout, and responsive behavior
 - free of unnecessary HubSpot-generated structure
 - prepared for future development and publishing
 
@@ -238,11 +257,20 @@ Do not invent extensive translations.
 
 ### Design direction
 
-The new site should be more maintainable while remaining mostly faithful to the current design.
+The new site must faithfully reproduce the live public site's visible design,
+layout, content hierarchy, and responsive behavior. Do not redesign,
+reinterpret, modernize, simplify, or genericize source pages.
 
-Do not create a messy clone of HubSpot output.
+Preserve typography, colors, backgrounds, spacing, proportions, imagery,
+section order, decorative treatments, navigation, calls to action, forms, and
+page-specific distinctions. Reuse exact source assets and fonts wherever
+practical.
 
-Refactor repeated sections into reusable components.
+Do not copy HubSpot-generated DOM or CSS wholesale.
+
+Refactor genuinely repeated sections into reusable components. Do not force
+distinctive source sections into generic components when doing so changes their
+appearance or structure.
 
 Use semantic markup.
 
@@ -250,6 +278,22 @@ Use plain CSS with design tokens.
 
 Do not use Tailwind.
 
+### Fidelity workflow
+
+For each page family or shared component:
+
+1. Inspect the live page, HTML, CSS, assets, and responsive behavior.
+2. Use the mirror to accelerate local extraction and inspection.
+3. Resolve discrepancies in favor of the live public site.
+4. Record important visual details and identify genuine shared patterns.
+5. Implement the page or component in maintainable Astro code.
+6. Compare the complete rendered page with the live public site at representative
+   desktop and mobile viewport widths.
+7. Fix material visual differences before marking it complete.
+
+Document intentional visual deviations and their reasons in
+`reports/migration-summary.md`.
+
 ## Required target structure
 
 Create this project structure in `./www`:
@@ -643,7 +687,10 @@ src/styles/rtl.css
 src/styles/global.css
 ```
 
-Infer the current site’s visual language from the mirrored CSS and HTML.
+Extract the current site's visual language from the live public site, using the
+mirrored CSS and HTML as a convenient local aid after checking for discrepancies.
+Tokens must encode source values; they must not introduce a replacement visual
+system.
 
 Use design tokens such as:
 
@@ -1168,6 +1215,8 @@ The migration is successful when:
 - `./www` contains a working Astro project
 - `npm run build` succeeds or unresolved build issues are clearly documented
 - main public pages render locally
+- main public pages have been compared with the live site at desktop and mobile
+  widths and have no undocumented material visual differences
 - blog posts are migrated into file-based Markdown where feasible
 - Markdown files work with Front Matter CMS
 - MDX is available but not overused
@@ -1191,18 +1240,22 @@ Proceed methodically:
 1. Read `AGENTS.md`.
 2. Read `CLAUDE.md`, if using Claude Code.
 3. Read this `MIGRATION_BRIEF.md`.
-4. Inspect `./www.azinstitute4autism.com`.
+4. Inspect the live public site.
-5. Summarize a concise implementation plan.
+5. Inspect `./www.azinstitute4autism.com` and identify relevant discrepancies.
-6. Scaffold Astro in `./www`.
+6. Summarize a concise implementation plan.
-7. Build extraction/reporting scripts.
+7. Scaffold Astro in `./www`.
-8. Extract pages, blog posts, assets, metadata, navigation, and forms.
+8. Build extraction/reporting scripts.
-9. Refactor repeated sections into Astro components.
+9. Extract pages, blog posts, assets, metadata, navigation, and forms.
-10. Configure content collections and Front Matter CMS.
+10. Refactor repeated sections into Astro components.
-11. Add multilingual structure.
+11. Configure content collections and Front Matter CMS.
-12. Add SEO, sitemap, robots, and redirects.
+12. Add multilingual structure.
-13. Add reports.
+13. Add SEO, sitemap, robots, and redirects.
-14. Run build and audits.
+14. Add reports.
-15. Fix errors.
+15. Run build and audits.
-16. Summarize what changed and what still needs manual review.
+16. Fix errors.
+17. Summarize what changed and what still needs manual review.
 
-Prioritize a clean, maintainable foundation over a messy pixel-perfect clone.
+Prioritize visual fidelity and content correctness while implementing them with
+clean, maintainable Astro code. Do not trade away visible source design for a
+generic foundation, and do not copy HubSpot-generated implementation merely to
+obtain fidelity.