diff --git a/AGENTS.md b/AGENTS.md index e066d7f..1e513af 100644 --- a/AGENTS.md +++ b/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. -2. Summarize the implementation plan. -3. Proceed methodically. +1. Inspect the live public site. +2. Inspect the mirror and identify relevant discrepancies. +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. \ No newline at end of file +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. diff --git a/CLAUDE.md b/CLAUDE.md index 5519597..02ee563 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,19 +36,24 @@ For the migration task: 1. Read `AGENTS.md`. 2. Read `MIGRATION_BRIEF.md`. -3. Inspect the local mirror. -4. Provide a concise implementation plan. -5. Scaffold or update the Astro project in `./www`. -6. Build extraction, crawl, audit, sitemap, and redirect tools. -7. Extract content, media, metadata, navigation, and forms. -8. Refactor into reusable Astro components. -9. Configure Astro content collections and Front Matter CMS. -10. Add English, Arabic, and Spanish structure. -11. Add RTL CSS for Arabic. -12. Add SEO, sitemap, robots, redirects, and reports. -13. Run build and audits. -14. Fix practical errors. -15. Document incomplete items in `reports/migration-summary.md`. +3. Inspect the live public site as the single source of truth. +4. Inspect the local mirror as a convenient extraction aid and identify + relevant discrepancies. +5. Inspect the relevant live HTML, CSS, assets, and responsive behavior. +6. Provide a concise implementation and visual-validation plan. +7. Scaffold or update the Astro project in `./www`. +8. Build extraction, crawl, audit, sitemap, and redirect tools. +9. Extract content, media, metadata, navigation, and forms. +10. Refactor genuinely repeated patterns into reusable Astro components. +11. Compare rendered pages with the live site at desktop and mobile widths. +12. Configure Astro content collections and Front Matter CMS. +13. Add English, Arabic, and Spanish structure. +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`. @@ -105,4 +119,4 @@ When finished, report: - redirect status - build status - audit status -- manual review items \ No newline at end of file +- manual review items diff --git a/MIGRATION_BRIEF.md b/MIGRATION_BRIEF.md index 502490e..84e41ff 100644 --- a/MIGRATION_BRIEF.md +++ b/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. - -If internet access is available, also crawl the live public website to catch missing URLs or assets: +Use the live public website as the single source of truth: ```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`. -5. Summarize a concise implementation plan. -6. Scaffold Astro in `./www`. -7. Build extraction/reporting scripts. -8. Extract pages, blog posts, assets, metadata, navigation, and forms. -9. Refactor repeated sections into Astro components. -10. Configure content collections and Front Matter CMS. -11. Add multilingual structure. -12. Add SEO, sitemap, robots, and redirects. -13. Add reports. -14. Run build and audits. -15. Fix errors. -16. Summarize what changed and what still needs manual review. +4. Inspect the live public site. +5. Inspect `./www.azinstitute4autism.com` and identify relevant discrepancies. +6. Summarize a concise implementation plan. +7. Scaffold Astro in `./www`. +8. Build extraction/reporting scripts. +9. Extract pages, blog posts, assets, metadata, navigation, and forms. +10. Refactor repeated sections into Astro components. +11. Configure content collections and Front Matter CMS. +12. Add multilingual structure. +13. Add SEO, sitemap, robots, and redirects. +14. Add reports. +15. Run build and audits. +16. Fix errors. +17. Summarize what changed and what still needs manual review. -Prioritize a clean, maintainable foundation over a messy pixel-perfect clone. \ No newline at end of file +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.