# AI build guide (`ai-build-guide.md`)

Use this file **before** letting an autonomous agent modify Criazo’s Laravel project. It mirrors `resources/design-system/ai-guide.php` (rendered with copy buttons on `/dashboard/design-system`).

## Operating rules (non-negotiable)

1. **Read** [`README.md`](README.md) first — scope + links to deep docs.
2. **Read** [`design.md`](design.md) before inventing new visual motifs.
3. **Read** [`components.md`](components.md) + `resources/design-system/components.php` before creating Blade partials.
4. **Read** [`page-patterns.md`](page-patterns.md) before adding routes/views.
5. **Reuse** existing `@include('components.*')` partials when possible.
6. **Never** duplicate brand colors or spacing — follow [`tokens.md`](tokens.md) + Tailwind extends in `layouts/app.blade.php`.
7. **Preserve** middleware contracts:
   - Public marketing: `locale`, `page.cache` as currently registered.
   - Dashboard: `auth` only (no `page.cache` on personalized views).
8. **Never** publish dashboard-only documentation to public web roots.
9. **Never** install package managers (no `npm` reliance today) without explicit human approval.
10. **Preserve** analytics (GA4 + Clarity) + lead tracking endpoints when editing footers/forms.
11. **Maintain** SEO parity: canonical, hreflang, structured data, translation integrity.
12. **Do not** redesign brand palette or migrate to a different CSS framework casually.

## Repository map agents must respect

| Concern | Path |
| --- | --- |
| Public layout | `resources/views/layouts/app.blade.php` |
| SEO config | `config/seo.php` |
| SEO helper | `app/Helpers/SeoHelper.php` |
| Routes | `routes/web.php` |
| Lead APIs | `routes/web.php` (`api/leads/*`) + `LeadController` |
| Programmatic data | `data/*.php` caches via `CachedData` |
| Dashboard | `resources/views/dashboard/**` |

## Copy-paste prompt — new service page

```
You edit the production Criazo Laravel project. Constraints:
- Clone structure of nearest neighbor in resources/views/pages/service-detail.blade.php.
- Extend layouts.app with proper @section(title/meta/canonical).
- Register slug + translation keys across resources/lang/*/messages.php and nav datasets.
- Include components.sticky-cta-bar mirroring sibling props (?service slug, simulate URL optional).
- Append components.explore-site-section footer module.
- Do not hardcode HEX colors outside existing Tailwind token names.

Deliverable: cohesive diff referencing exact files touched.
```

## Copy-paste prompt — new industry/programmatic SEO trio

```
Add industry combination following ServiceIndustryController patterns.
- Respect route order (/services/{service}/{industry}/{location}).
- Update translation + taxonomy configs as necessary.
- Generate FAQ accordion + mirrored SeoHelper::generateFaqSchema payload.
- Keep internal linking symmetrical with footer expectations.
Forbidden: renaming legacy slugs without 301 blueprint.
```

## Copy-paste prompt — new portfolio case study

```
Add portfolio slug following data/portfolio-data.php conventions & PortfolioController/show expectations.
Portfolio detail Blade must retain challenge/solution/metrics arcs.
Imagery receives width/height + descriptive ALT mirroring hyphenated filenames.
```

## Copy-paste prompt — new landing / vertical

```
Implement VerticalLandingController method + mirrored localized routes following existing vertical sample.
Sticky CTA + story partials must mimic components used in verticals/restaurants.blade.php.
Declare GET paths in BOTH default english group and localized `{locale}` group when required.
Document internal linking anchors to canonical service + contact routes.
```

## Copy-paste prompt — new SEO/indexable informational page

```
Create page extending layouts.app registered under middleware group locale + page.cache.
Provide unique title + meta_description + canonical.
Push structured data ONLY if textual content aligns (FAQ, breadcrumb lists, etc.).
If locale lacks translation completeness, obey SeoHelper::hasLocaleTranslationsForIndexing guards.
Attach to correct sitemap builder if volumetric cluster emerges.
```

## Copy-paste prompt — new authenticated dashboard module

```
Add route under middleware auth prefix dashboard.
Standalone Blade MUST NOT extend layouts.app; match dashboard/leads/index.blade.php visual language:
Inter font, Tailwind CDN inline extend, rounded-criazo-lg cards on #f5f5f7 background.
Honor CSRF for fetch POST/PATCH endpoints.
Exclude marketing analytics bundles unless materially required.
```

## Copy-paste prompt — new Blade component (`components/{name}`)

```
Create reusable partial ONLY if THREE OR MORE invocation sites justified.
Expose props via @props or documented @php block with defaults.
Add documentation row to docs/design-system/components.md + resources/design-system/components.php.
Include accessibility semantics (roles/labels) proactively.
Reference buttons.md/forms.md for sizing/radius coherence.
```

## Copy-paste prompt — audit existing page vs system

```
You are auditing file: ____ against docs/design-system.
Output structured report:
SECTION: SEO → PASS/FAIL + evidence (meta, canonical, hreflang, structured parity)
SECTION: Conversion → PASS/FAIL (CTAs, sticky duplication, funnel gaps)
SECTION: Components → redundancy vs reusable partial inventory
SECTION: Tokens → offending hardcoded HEX / spacing inconsistencies
SECTION: Accessibility → focus traps, headings, semantics
SECTION: Perf → LCP preload, CLS on images

Finish with prioritized fix backlog (ranked P0/P1/P2).
```

## Copy-paste prompt — iterative improvement preserving consistency

```
Apply improvements to ____ without renaming routes/middleware/trans keys.
Maintain translation-first policy.
Honor prefers-reduced-motion when adjusting animations.
Retain explore-site + footer linkage unless logically broken — if removal required, compensate with purposeful internal anchors.
Regression test: php artisan route:list, php artisan test, php artisan view:cache (if Blade touched).
```

## Escalate to humans when...

- Fundamental domain / GA / Clarity IDs must rotate.
- New translation locale claims index readiness but lacks minimum translation volume.
- Large-scale taxonomy rename touches thousands of programmatic URLs simultaneously.