From d19b3f3248cf638cf3b298f3f6face47c2e68113 Mon Sep 17 00:00:00 2001 From: Jeffrey Hales Date: Sat, 6 Jun 2026 20:02:17 -0700 Subject: [PATCH] init: git all the things! --- AGENTS.md | 310 +++++++++++ AUTONOMOUS-CODEX.md | 52 ++ CLAUDE.md | 108 ++++ MIGRATION_BRIEF.md | 1208 +++++++++++++++++++++++++++++++++++++++++++ codex-auto | 15 + 5 files changed, 1693 insertions(+) create mode 100644 AGENTS.md create mode 100644 AUTONOMOUS-CODEX.md create mode 100644 CLAUDE.md create mode 100644 MIGRATION_BRIEF.md create mode 100755 codex-auto diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e066d7f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,310 @@ +# AGENTS.md + +## Project + +This repository contains a mirrored copy of the Arizona Institute for Autism website. + +Raw mirror source: + +```txt +./www.azinstitute4autism.com +``` + +New Astro site target: + +```txt +./www +``` + +The mirror was created with: + +```sh +wget --mirror --page-requisites --adjust-extension --convert-links --no-parent https://www.azinstitute4autism.com +``` + +Do not modify, move, rename, or delete `./www.azinstitute4autism.com`. + +Treat the mirror as read-only raw source material. + +## 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. + +The new site should be suitable for: + +- static hosting +- file-based editing +- Front Matter CMS in VS Code +- future blog posting +- future Spanish and Arabic publishing +- future Netlify, nginx, Cloudflare Pages, or Vercel deployment + +## Stack + +Use: + +- Astro +- TypeScript +- npm +- Markdown-first content +- MDX only when embedded Astro/React-style components are genuinely needed +- Astro content collections +- Zod frontmatter validation +- plain CSS with design tokens +- Astro image optimization where appropriate + +Do not use: + +- Tailwind +- a database +- a headless CMS +- HubSpot APIs +- HubSpot CLI +- HubSpot-hosted production assets unless unavoidable +- a form backend +- deployment-specific config unless explicitly requested + +## Content strategy + +Use file-based Markdown as the default content format. + +Use `.md` for: + +- normal blog posts +- normal service pages +- informational pages +- author profiles + +Use `.mdx` only for pages or posts that need embedded components. + +The content should be structured to work well with Front Matter CMS in VS Code. + +Use these content folders: + +```txt +src/content/pages/en +src/content/pages/ar +src/content/pages/es +src/content/blog/en +src/content/blog/ar +src/content/blog/es +src/content/authors/en +src/content/authors/ar +src/content/authors/es +``` + +## Multilingual requirements + +Support: + +- English +- Arabic +- Spanish + +English is the default language. + +URL patterns: + +```txt +English: +/ +/aba +/autismevaluations +/library/post-slug + +Arabic: +/ar +/ar/aba +/ar/autismevaluations +/ar/library/post-slug + +Spanish: +/es +/es/aba +/es/autismevaluations +/es/library/post-slug +``` + +Arabic pages must use: + +```html + +``` + +English pages must use: + +```html + +``` + +Spanish pages must use: + +```html + +``` + +Add RTL CSS support for Arabic. + +Do not invent large Arabic or Spanish translations unless source content is available. Use clearly marked placeholders when needed. + +## Design rules + +The new design should be mostly faithful to the current site while becoming more maintainable. + +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. + +Favor: + +- semantic HTML +- reusable components +- organized CSS +- clear data files +- consistent spacing +- accessible markup +- predictable file structure + +## URL and SEO rules + +Preserve existing public URL paths whenever possible. + +Preserve or document: + +- page title +- meta description +- canonical URL +- Open Graph tags +- Twitter card tags +- JSON-LD/schema +- H1 +- image alt text +- internal links + +Generate nginx rewrite rules only for paths that must change. + +Do not create unnecessary redirects for paths that are preserved. + +## Assets + +Self-host assets wherever practical. + +Extract and organize: + +- images +- SVGs +- icons +- fonts +- PDFs +- media files +- downloads + +Use: + +```txt +public/assets/images +public/assets/fonts +public/assets/media +public/assets/downloads +src/assets/images +``` + +Use `public/assets` for content/frontmatter references. + +Use `src/assets` for images imported into Astro components and optimized by Astro. + +Document any remaining external asset dependencies. + +## Forms + +Recreate visible forms as styled static HTML. + +Do not implement backend submission. + +Every form must include TODO comments, for example: + +```html + + +``` + +## Likes and views + +Preserve the AIA like/view counter conceptually. + +Use this API base URL as the default: + +```txt +https://api.azinstitute4autism.com +``` + +Do not hardcode it throughout the app. + +Use: + +```txt +PUBLIC_AIA_API_BASE=https://api.azinstitute4autism.com +``` + +Add it to `.env.example`. + +The component must degrade gracefully when the API is unavailable. + +## Validation + +After meaningful changes, run: + +```sh +npm run build +``` + +When available, also run: + +```sh +npm run audit:links +``` + +If a command fails, diagnose and fix it when practical. + +If it cannot be fixed, document the issue in: + +```txt +reports/migration-summary.md +``` + +## Required reports + +Create: + +```txt +reports/url-inventory.csv +reports/asset-inventory.csv +reports/seo-audit.md +reports/accessibility-audit.md +reports/broken-links.md +reports/cleanup-log.md +reports/redirect-map.csv +reports/nginx-rewrites.conf +reports/migration-summary.md +``` + +## Working style + +Before large filesystem changes: + +1. Inspect the mirror. +2. Summarize the implementation plan. +3. Proceed methodically. + +At the end of a task, summarize: + +- what changed +- what works +- what needs manual review +- build results +- audit results +- unresolved issues + +Prioritize a clean, maintainable foundation over a pixel-perfect but messy clone. \ No newline at end of file diff --git a/AUTONOMOUS-CODEX.md b/AUTONOMOUS-CODEX.md new file mode 100644 index 0000000..1be57ec --- /dev/null +++ b/AUTONOMOUS-CODEX.md @@ -0,0 +1,52 @@ +# Autonomous Codex + +Use the project launcher to run Codex with the `azi4a2-autonomous` permission +profile: + +```sh +./codex-auto +``` + +For a non-interactive task: + +```sh +./codex-auto exec "Continue the Astro migration, verify the build and audits, and document unresolved issues." +``` + +The launcher automatically permits non-interactive runs in this mounted +workspace even when Codex cannot discover its Git metadata. + +The profile: + +- never pauses for approval +- limits filesystem access to minimal runtime files plus this project +- allows writes in this project +- keeps `.codex` and `www.azinstitute4autism.com` read-only +- permits normal Git operations, including staging and committing +- enables live web search and outbound network retrievals + +Outbound network access is domain-unrestricted because package installation and +retrieval sources vary. The sandbox cannot distinguish a retrieval from another +outbound request, so do not place secrets in project files or task prompts. + +The profile is stored outside the workspace at: + +```txt +~/.codex/azi4a2-autonomous.config.toml +``` + +Do not add `--sandbox`; legacy sandbox flags override the custom permission +profile. Do not use `--dangerously-bypass-approvals-and-sandbox`. + +## Verification + +The nested setup smoke test confirmed that the project is readable and +`~/.codex/auth.json` is not readable. In the current host session, sandboxed +shell retrievals resolved domains but were reset by the beta network proxy. +After launching `./codex-auto` directly, verify shell retrievals with: + +```sh +curl -fsS https://registry.npmjs.org/astro >/dev/null +``` + +Live web search is separate from shell network access and remains enabled. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5519597 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,108 @@ +@AGENTS.md + +# CLAUDE.md + +## Claude Code instructions + +This project is intended to be worked on with Claude Code. + +Before starting the HubSpot-to-Astro migration, read: + +```txt +MIGRATION_BRIEF.md +``` + +Then inspect: + +```txt +./www.azinstitute4autism.com +``` + +and create the new Astro site in: + +```txt +./www +``` + +Do not modify or delete: + +```txt +./www.azinstitute4autism.com +``` + +## Expected workflow + +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`. + +## Important Claude-specific behavior + +Do not rely on a single massive prompt if the same information already exists in `MIGRATION_BRIEF.md`. + +When asked to begin migration, first read the relevant project files, then work from the files. + +## Safety and preservation + +Treat `./www.azinstitute4autism.com` as read-only source material. + +Do not delete or overwrite raw source assets. + +Do not remove files unless you are certain they are generated output in `./www`. + +Do not make assumptions about form backend behavior. Forms must remain static with TODO comments. + +Do not invent large Spanish or Arabic translations. Create placeholders only when source content does not exist. + +## Commands + +Use npm. + +Expected commands after setup: + +```sh +npm install +npm run dev +npm run build +npm run preview +npm run audit:links +``` + +If any command fails, investigate and fix when practical. + +If unresolved, document the issue in: + +```txt +www/reports/migration-summary.md +``` + +## Completion summary + +When finished, report: + +- files and folders created +- content migrated +- pages and posts extracted +- assets copied or converted +- forms recreated +- multilingual structure status +- like/view counter status +- SEO status +- redirect status +- build status +- audit status +- manual review items \ No newline at end of file diff --git a/MIGRATION_BRIEF.md b/MIGRATION_BRIEF.md new file mode 100644 index 0000000..502490e --- /dev/null +++ b/MIGRATION_BRIEF.md @@ -0,0 +1,1208 @@ +# MIGRATION_BRIEF.md + +## Task + +Migrate the public Arizona Institute for Autism website from a mirrored HubSpot-generated static copy into a clean, maintainable Astro + TypeScript site. + +Raw mirrored source: + +```txt +./www.azinstitute4autism.com +``` + +New Astro project target: + +```txt +./www +``` + +The raw mirror was created with: + +```sh +wget --mirror --page-requisites --adjust-extension --convert-links --no-parent https://www.azinstitute4autism.com +``` + +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: + +```txt +https://www.azinstitute4autism.com +``` + +The live crawl is only for comparison and gap-filling. The local mirror remains the source of truth. + +## High-level goal + +Create a new Astro site in `./www` that is: + +- Astro-based +- TypeScript-based +- static-hosting friendly +- Markdown-first +- MDX-enabled only when needed +- Front Matter CMS friendly +- multilingual for English, Arabic, and Spanish +- self-hosted for media and assets wherever practical +- SEO-conscious +- accessible +- maintainable +- mostly faithful to the current design +- free of unnecessary HubSpot-generated structure +- prepared for future development and publishing + +## Important constraints + +Do not modify or delete: + +```txt +./www.azinstitute4autism.com +``` + +Do not depend on: + +- HubSpot CLI +- HubSpot API +- HubSpot export files +- a database +- a form backend +- a headless CMS +- Tailwind + +Do not hardcode environment-specific deployment assumptions. + +Hosting is undecided. + +Possible future hosts include: + +- Netlify +- nginx +- Cloudflare Pages +- Vercel +- another static host + +Use `npm`, not pnpm or yarn. + +Use plain CSS with design tokens. + +Use Astro image optimization where useful. + +Generate nginx rewrite rules for changed URLs. + +## Current known requirements + +### URL preservation + +Preserve existing URL structure exactly whenever possible. + +Important paths include: + +```txt +/ +/aba +/autismevaluations +/learnersocialclub +/client-consultation +/library +/library/post-slug +``` + +If a URL must change, document it and generate an nginx rewrite. + +Do not generate redirects for URLs that remain unchanged. + +### Content format + +Use file-based Markdown as the default content format. + +Use `.md` for most pages and blog posts. + +Use `.mdx` only when embedded Astro/React-style components are genuinely needed. + +### Front Matter CMS + +The content structure should work well with the Front Matter CMS VS Code extension. + +Create a `frontmatter.json` file at the Astro project root. + +### Forms + +Recreate visible forms as styled static HTML. + +Do not implement backend submission. + +Each form must include TODO comments. + +Example: + +```html +
+ + +
+``` + +If original HubSpot form fields cannot be fully recovered, create a reasonable static approximation and document the uncertainty. + +### Likes and views + +Preserve the like/view counter conceptually. + +Known production API base: + +```txt +https://api.azinstitute4autism.com +``` + +Use environment configuration: + +```txt +PUBLIC_AIA_API_BASE=https://api.azinstitute4autism.com +``` + +Add this to `.env.example`. + +Do not make the build fail if the API is unavailable. + +The like/view feature should degrade gracefully. + +### Multilingual + +Support: + +- English +- Arabic +- Spanish + +English is the default. + +Use these URL patterns: + +```txt +English: +/ +/aba +/autismevaluations +/library/post-slug + +Arabic: +/ar +/ar/aba +/ar/autismevaluations +/ar/library/post-slug + +Spanish: +/es +/es/aba +/es/autismevaluations +/es/library/post-slug +``` + +Arabic pages must use RTL layout. + +Arabic HTML: + +```html + +``` + +English HTML: + +```html + +``` + +Spanish HTML: + +```html + +``` + +Add: + +```txt +src/styles/rtl.css +``` + +If Arabic or Spanish source content is missing, create minimal placeholder content only where needed to demonstrate the structure. + +Mark placeholders clearly: + +```md + +``` + +Do not invent extensive translations. + +### Design direction + +The new site should be more maintainable while remaining mostly faithful to the current design. + +Do not create a messy clone of HubSpot output. + +Refactor repeated sections into reusable components. + +Use semantic markup. + +Use plain CSS with design tokens. + +Do not use Tailwind. + +## Required target structure + +Create this project structure in `./www`: + +```txt +www/ + README.md + package.json + astro.config.mjs + tsconfig.json + .env.example + frontmatter.json + + public/ + assets/ + images/ + fonts/ + media/ + downloads/ + robots.txt + sitemap.xml + + src/ + assets/ + images/ + + components/ + Header.astro + Footer.astro + MainNav.astro + MobileNav.astro + LanguageSwitcher.astro + Hero.astro + ServiceCard.astro + BlogCard.astro + ConsultationCTA.astro + InsuranceStrip.astro + LocationCard.astro + FAQAccordion.astro + LikeViewCounter.astro + Seo.astro + FormShell.astro + + content/ + config.ts + + pages/ + en/ + ar/ + es/ + + blog/ + en/ + ar/ + es/ + + authors/ + en/ + ar/ + es/ + + data/ + navigation.en.json + navigation.ar.json + navigation.es.json + site.json + redirects.json + services.json + + layouts/ + BaseLayout.astro + PageLayout.astro + BlogPostLayout.astro + BlogIndexLayout.astro + + pages/ + index.astro + aba.astro + autismevaluations.astro + learnersocialclub.astro + client-consultation.astro + + ar/ + index.astro + [...slug].astro + + es/ + index.astro + [...slug].astro + + library/ + index.astro + [slug].astro + page/ + [page].astro + + scripts/ + forms.ts + navigation.ts + likes-views.ts + + styles/ + global.css + variables.css + typography.css + layout.css + components.css + forms.css + blog.css + rtl.css + + tools/ + extract-site.mjs + crawl-live-site.mjs + audit-links.mjs + generate-redirects.mjs + generate-sitemap.mjs + + original/ + README.md + + reports/ + url-inventory.csv + asset-inventory.csv + seo-audit.md + accessibility-audit.md + broken-links.md + cleanup-log.md + redirect-map.csv + nginx-rewrites.conf + migration-summary.md +``` + +The `original/README.md` file should explain that the raw source mirror lives outside the Astro project at: + +```txt +../www.azinstitute4autism.com +``` + +Do not duplicate the entire raw mirror inside `./www` unless there is a specific reason. + +## Initial inspection + +Before creating or modifying files, inspect the mirror. + +Look for: + +- all HTML files +- URL paths +- CSS files +- JS files +- image assets +- SVGs +- fonts +- PDFs +- media files +- blog posts +- blog listing pages +- blog pagination +- author pages +- Arabic pages +- Spanish pages +- sitemap files +- robots.txt +- canonical tags +- Open Graph metadata +- schema/JSON-LD +- forms +- navigation +- footer links +- HubSpot-specific scripts +- analytics/pixel scripts +- like/view counter code +- broken or rewritten local links +- asset references still pointing to remote hosts + +Create an initial implementation plan after inspection. + +## Astro setup + +Create or scaffold the Astro project in: + +```txt +./www +``` + +Use: + +```sh +npm create astro@latest www +``` + +Adjust as needed. + +Install and configure only useful dependencies. + +Likely useful dependencies: + +```txt +astro +@astrojs/mdx +@astrojs/sitemap +typescript +zod +cheerio +fast-glob +gray-matter +turndown +``` + +Use judgment. + +Avoid unnecessary framework bloat. + +The final project should support: + +- Astro +- TypeScript +- Markdown content collections +- MDX integration +- sitemap generation +- image optimization +- plain CSS imports +- Front Matter CMS editing + +## Content collections + +Create: + +```txt +src/content/config.ts +``` + +Define collections for: + +- pages +- blog +- authors + +Use Zod schemas. + +### Blog schema + +Recommended fields: + +```ts +title: string +description: string +slug: string +date: Date +updatedDate?: Date +author: string +category?: string +tags?: string[] +featuredImage?: string +alt?: string +canonical?: string +draft?: boolean +lang: 'en' | 'ar' | 'es' +translationKey?: string +``` + +### Page schema + +Recommended fields: + +```ts +title: string +description: string +slug: string +canonical?: string +featuredImage?: string +alt?: string +lang: 'en' | 'ar' | 'es' +translationKey?: string +draft?: boolean +``` + +### Author schema + +Recommended fields: + +```ts +name: string +slug: string +description?: string +avatar?: string +lang: 'en' | 'ar' | 'es' +translationKey?: string +``` + +### Example blog post + +```md +--- +title: "ABA Prompting: A Parent-Friendly Guide" +description: "Learn how ABA prompting helps children build independence through clear support and gradual fading." +slug: "aba-prompting" +date: "2026-05-29" +author: "aia" +category: "ABA Therapy" +tags: + - ABA therapy + - autism parenting +featuredImage: "/assets/images/blog/aba-prompting.webp" +alt: "Parent helping a child practice brushing teeth with gentle hand support" +canonical: "https://www.azinstitute4autism.com/library/aba-prompting" +draft: false +lang: "en" +translationKey: "aba-prompting" +--- + +Article content goes here. +``` + +## Front Matter CMS configuration + +Create: + +```txt +frontmatter.json +``` + +Configure it for the VS Code Front Matter CMS extension. + +Register these content folders: + +```txt +src/content/pages/en +src/content/pages/ar +src/content/pages/es +src/content/blog/en +src/content/blog/ar +src/content/blog/es +src/content/authors/en +src/content/authors/ar +src/content/authors/es +``` + +Configure content types: + +- page +- blog +- author + +Use field names aligned with Astro content schemas. + +Useful fields: + +- title +- description +- slug +- date +- updatedDate +- author +- category +- tags +- featuredImage +- alt +- canonical +- draft +- lang +- translationKey + +Choice fields: + +```txt +lang: en, ar, es +draft: true, false +``` + +Make images selectable from: + +```txt +public/assets/images +src/assets/images +``` + +## Design system + +Create: + +```txt +src/styles/variables.css +src/styles/typography.css +src/styles/layout.css +src/styles/components.css +src/styles/forms.css +src/styles/blog.css +src/styles/rtl.css +src/styles/global.css +``` + +Infer the current site’s visual language from the mirrored CSS and HTML. + +Use design tokens such as: + +```css +:root { + --color-primary: ; + --color-primary-dark: ; + --color-secondary: ; + --color-accent: ; + --color-background: ; + --color-surface: ; + --color-text: ; + --color-muted: ; + --color-border: ; + + --font-sans: ; + --font-heading: ; + + --space-xs: ; + --space-sm: ; + --space-md: ; + --space-lg: ; + --space-xl: ; + + --radius-sm: ; + --radius-md: ; + --radius-lg: ; + + --shadow-sm: ; + --shadow-md: ; + + --container: ; +} +``` + +Document assumptions in: + +```txt +reports/cleanup-log.md +``` + +## Components + +Create reusable Astro components. + +Required components: + +```txt +Header.astro +Footer.astro +MainNav.astro +MobileNav.astro +LanguageSwitcher.astro +Hero.astro +ServiceCard.astro +BlogCard.astro +ConsultationCTA.astro +InsuranceStrip.astro +LocationCard.astro +FAQAccordion.astro +LikeViewCounter.astro +Seo.astro +FormShell.astro +``` + +Header and footer should be driven by JSON files in: + +```txt +src/data/ +``` + +Do not hardcode navigation in multiple templates. + +## Data files + +Create: + +```txt +src/data/navigation.en.json +src/data/navigation.ar.json +src/data/navigation.es.json +src/data/site.json +src/data/redirects.json +src/data/services.json +``` + +Navigation should include primary and footer sections. + +Example: + +```json +{ + "primary": [ + { "label": "ABA Therapy", "href": "/aba" }, + { "label": "Autism Evaluations", "href": "/autismevaluations" }, + { "label": "Learner Social Club", "href": "/learnersocialclub" }, + { "label": "Library", "href": "/library" }, + { "label": "Contact", "href": "/client-consultation" } + ] +} +``` + +## Layouts + +Create: + +```txt +src/layouts/BaseLayout.astro +src/layouts/PageLayout.astro +src/layouts/BlogPostLayout.astro +src/layouts/BlogIndexLayout.astro +``` + +`BaseLayout.astro` should include: + +- HTML `lang` +- HTML `dir` +- SEO component +- global styles +- header +- main slot +- footer +- scripts as needed + +## SEO component + +Create: + +```txt +src/components/Seo.astro +``` + +It should support: + +- title +- description +- canonical +- Open Graph tags +- Twitter card tags +- image +- noindex for drafts/placeholders +- language +- direction +- hreflang links where translation relationships are known +- JSON-LD/schema when extracted + +Preserve metadata from the mirror wherever possible. + +Generate: + +```txt +public/sitemap.xml +public/robots.txt +reports/seo-audit.md +``` + +The SEO audit should include: + +- URL +- old title +- new title +- old description +- new description +- canonical +- H1 +- notes +- missing metadata + +## Routes + +Create route files for English primary pages: + +```txt +src/pages/index.astro +src/pages/aba.astro +src/pages/autismevaluations.astro +src/pages/learnersocialclub.astro +src/pages/client-consultation.astro +``` + +Create blog routes: + +```txt +src/pages/library/index.astro +src/pages/library/[slug].astro +src/pages/library/page/[page].astro +``` + +Create multilingual catch-all routes: + +```txt +src/pages/ar/index.astro +src/pages/ar/[...slug].astro +src/pages/es/index.astro +src/pages/es/[...slug].astro +``` + +Implement routing in a clean, maintainable way. + +## Extraction scripts + +Create: + +```txt +tools/extract-site.mjs +tools/crawl-live-site.mjs +tools/audit-links.mjs +tools/generate-redirects.mjs +tools/generate-sitemap.mjs +``` + +### `extract-site.mjs` + +This script should: + +- scan the mirror +- identify HTML files +- infer URL paths +- identify page type +- identify blog posts +- identify listing pages +- extract title/meta/H1/body/main content +- extract canonical and Open Graph metadata +- extract schema/JSON-LD where present +- convert blog posts to Markdown where feasible +- create page Markdown where useful +- copy/normalize assets +- rewrite local asset references +- create initial reports + +The script does not need to be perfect, but it should be useful and documented. + +### `crawl-live-site.mjs` + +This script should: + +- attempt to crawl the live site if internet is available +- discover URLs from sitemap and internal links +- compare discovered URLs against the mirror +- document missing URLs/assets +- avoid aggressive crawling +- respect the scope of `www.azinstitute4autism.com` + +### `audit-links.mjs` + +This script should: + +- inspect generated content and/or built output +- identify internal links that do not resolve +- identify external links if easy to check +- produce: + +```txt +reports/broken-links.md +``` + +### `generate-redirects.mjs` + +This script should: + +- read URL inventory and redirect map +- generate nginx rewrite rules +- output: + +```txt +reports/nginx-rewrites.conf +``` + +Use this style: + +```nginx +rewrite ^/old-path/?$ /new-path permanent; +``` + +### `generate-sitemap.mjs` + +This script should: + +- generate or validate sitemap output +- include language routes where appropriate +- avoid drafts/placeholders if marked noindex + +## Asset handling + +Extract/download/self-host assets into: + +```txt +public/assets/ +src/assets/ +``` + +Use `public/assets` for assets referenced directly in Markdown/frontmatter. + +Use `src/assets` for component-imported assets and Astro optimization. + +Organize: + +```txt +public/assets/images/ +public/assets/fonts/ +public/assets/media/ +public/assets/downloads/ +``` + +Normalize filenames where practical: + +```txt +hero-home.webp +aba-therapy-child-session.webp +blog-autism-play.webp +aia-logo.svg +``` + +Do not destroy originals unless they are duplicated and unused. + +Create: + +```txt +reports/asset-inventory.csv +``` + +Include: + +- original URL/path +- new path +- file type +- used by +- notes + +## Forms + +Recreate visible forms as styled HTML forms. + +Do not implement backend behavior. + +Use `FormShell.astro` where useful. + +Each form must include TODO comments. + +Example: + +```html +
+ + +
+``` + +Document form assumptions and missing backend work in: + +```txt +reports/migration-summary.md +``` + +## Like/view counter + +Create: + +```txt +src/components/LikeViewCounter.astro +src/scripts/likes-views.ts +``` + +Use: + +```txt +PUBLIC_AIA_API_BASE=https://api.azinstitute4autism.com +``` + +Add `.env.example`: + +```txt +PUBLIC_AIA_API_BASE=https://api.azinstitute4autism.com +``` + +The frontend should: + +- fetch counts when possible +- allow like/unlike behavior if the existing API supports it +- not break the page when the API is unavailable +- avoid blocking static builds +- document any uncertainty in the migration summary + +## Accessibility + +Improve obvious accessibility issues while preserving the design. + +Check for: + +- missing alt text +- multiple H1s +- skipped heading levels +- unlabeled form fields +- low-contrast text +- missing button labels +- empty links +- keyboard navigation issues +- missing nav labels +- mobile menu accessibility +- language and direction attributes + +Create: + +```txt +reports/accessibility-audit.md +``` + +## Reports + +Create all of these: + +```txt +reports/url-inventory.csv +reports/asset-inventory.csv +reports/seo-audit.md +reports/accessibility-audit.md +reports/broken-links.md +reports/cleanup-log.md +reports/redirect-map.csv +reports/nginx-rewrites.conf +reports/migration-summary.md +``` + +### `migration-summary.md` + +Include: + +- what was successfully migrated +- what was approximated +- what requires manual review +- pages migrated +- blog posts migrated +- media copied +- external dependencies remaining +- forms requiring backend integration +- multilingual placeholder status +- SEO issues found +- accessibility issues found +- broken links +- build results +- recommended next steps + +## Package scripts + +Add scripts similar to: + +```json +{ + "scripts": { + "dev": "astro dev", + "build": "astro check && astro build", + "preview": "astro preview", + "extract": "node tools/extract-site.mjs", + "crawl": "node tools/crawl-live-site.mjs", + "audit:links": "node tools/audit-links.mjs", + "generate:sitemap": "node tools/generate-sitemap.mjs", + "generate:redirects": "node tools/generate-redirects.mjs" + } +} +``` + +If `astro check` requires an additional package, install/configure the needed package or adjust the script appropriately. + +## README + +Create: + +```txt +www/README.md +``` + +It should explain: + +- what the project is +- where the raw mirror lives +- how the migration was performed +- how to install dependencies +- how to run local dev +- how to build +- how to preview +- how to add a blog post +- how to add a page +- how to add an Arabic translation +- how to add a Spanish translation +- how to edit navigation +- how to configure the likes/views API base URL +- how forms are currently handled +- where reports live +- how to review nginx rewrites + +Include: + +```sh +npm install +npm run dev +npm run build +npm run preview +``` + +## Build and validation + +After implementation, run: + +```sh +npm install +npm run build +npm run audit:links +``` + +Fix errors when practical. + +If something cannot be completed, document it in: + +```txt +reports/migration-summary.md +``` + +## Acceptance criteria + +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 +- blog posts are migrated into file-based Markdown where feasible +- Markdown files work with Front Matter CMS +- MDX is available but not overused +- media is self-hosted wherever practical +- current URL paths are preserved wherever possible +- nginx rewrite rules are generated for changed paths +- forms are styled and marked with TODO backend comments +- the like/view counter is isolated and environment-configured +- English, Arabic, and Spanish structure exists +- Arabic RTL support exists +- CSS is organized into design-token-based plain CSS files +- reusable Astro components exist +- SEO metadata is preserved or documented +- audit/report files exist +- README explains how to continue development + +## Working order + +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. + +Prioritize a clean, maintainable foundation over a messy pixel-perfect clone. \ No newline at end of file diff --git a/codex-auto b/codex-auto new file mode 100755 index 0000000..aa9d414 --- /dev/null +++ b/codex-auto @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +set -euo pipefail + +repo_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" + +if [[ "${1:-}" == "exec" ]]; then + shift + set -- exec --skip-git-repo-check "$@" +fi + +exec codex \ + --profile-v2 azi4a2-autonomous \ + --strict-config \ + --cd "$repo_root" \ + "$@"