# AI Workflow

## AI Workflow

**Skill level:** Beginner

Two ways to work, depending on whether your assistant can open your project folder. Pick the tab that matches your tool.

<Tabs>
  <TabItem label="AI editor (recommended)">
    <Steps>

    1. **Open the whole `techlo` project folder** in the tool (the folder with `package.json`), not a single file or the unzipped download around it. The tool needs that folder to find `AGENTS.md` and its own rules file.

    2. **Start the site** with `npm run dev` and keep it open at `http://localhost:4321`, so you see each change.

    3. **Save a checkpoint.** If you use git, commit. If not, copy the folder. See [Editing Content Safely](/techlo/beginner/editing-content/).

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/techlo/ai-customization/ai-overview/) load the theme's rules on their own. If your tool isn't listed, or its answers ignore the rules, start your first request with "Read AGENTS.md first." For a bigger job, add "Follow the matching recipe in SKILLS.md." The [Prompt Library](/techlo/ai-customization/prompt-library/) has ready-made requests.

    5. **Review what changed.** Every tool shows a list of edited files and the changes ("diff"). Check the list against the review checklist below before you accept.

    6. **Check the result** in the browser, at a narrow window and at `/ar/`. `npm run dev` regenerates the config from `config.toml` when it starts, and picks up saved content changes on its own. Restart it after you change `src/config/fonts.json`, `src/config/language.json`, `trailingSlash`, or anything in `[settings.multilingual]`: Astro reads those only when it starts. Ask the assistant to run `npm run astro-check`, or run it yourself.

    </Steps>
  </TabItem>
  <TabItem label="Chat assistant">
    <Steps>

    1. **Give it the rules.** Open `AGENTS.md` from the theme folder, copy all of it, and paste it into a new conversation with one line: "These are the rules for the Astro theme I am customizing. Follow them."

    2. **Paste the file you want to change**, with its path. For example: "Here is `src/content/sections/english/banner.md`:" and the whole file.

    3. **Ask for the change**, and say what must stay the same: "Keep every key, option, and icon name. Only change the text values."

    4. **Copy the answer back** into the same file in your editor, save, and look at the page.

    5. **Repeat for every language.** Ask for the French and Arabic versions of the same file in the same conversation, so the keys stay identical.

    </Steps>

    Chat assistants work best for text: rewriting copy, translating, writing blog posts and service descriptions. For a change that touches several files, such as a new section or a new language, an AI editor saves a lot of copying.
  </TabItem>
</Tabs>

### What To Tell The Assistant
The more of this you give, the less it has to invent.

- **The file.** "Edit `src/content/sections/english/services-section.md`", not "edit the services".
- **The page.** "The section under the hero on `/about/`."
- **Your company.** One paragraph: what you build, for whom, and what makes you different. Paste it into every copywriting request.
- **Your real figures.** Prices, team size, years in business, projects you can show. If you don't give them, tell the assistant to keep the sample values and list them for you to replace.
- **The layout value.** Copy it from the comment next to `options.layout` in the section file: "use the `[VALUE]` layout of the projects section".
- **What must not change.** "Keep every key, option, and the number of items."
- **The recipe.** For bigger jobs, point to `SKILLS.md`, which most tools don't read on their own: "Follow the 'Add or remove a language' skill in SKILLS.md."

<Aside type="caution" title="A homepage route can override the layout you set">
  Section layouts come from `options.layout` in the section content file, but a
  homepage route file can also pass a layout through the section's `content`
  prop, and that wins. If you change `options.layout` and the homepage doesn't
  follow, ask the assistant to check the route file in `src/pages/[...lang]/`.
  Block names also matter: a name that is not a key of `sectionsSchema` in
  `src/sections.schema.ts` is dropped without an error.
</Aside>

### Review Checklist
Go through this before you accept a change.

- [ ] Text was changed in `src/content/`, `src/config/`, or `src/i18n/`, not typed into a component.
- [ ] Every language was updated: each language folder under `src/content/`, `src/i18n/<language>.json`, and `src/config/menu.<language>.json` (unless you turned a language off).
- [ ] Prices and other numbers are identical in the pricing file of every language.
- [ ] `customSlug` has the same value in every language for the same entry.
- [ ] Keys, ids, and indentation in Markdown frontmatter, TOML, and JSON still look like the rest of the file.
- [ ] Named blocks use names that exist in `src/sections.schema.ts`.
- [ ] No new colors like `text-[#123456]` in components. Techlo uses its theme tokens (`bg-primary`, `bg-primary-soft`, `bg-accent`, `bg-theme-light`, `text-dark`).
- [ ] New or changed CSS uses logical classes (`ms`, `me`, `ps`, `pe`, `text-start`), not `ml`, `pr`, or `text-left`.
- [ ] No client names, testimonials, project results, metrics, or prices were made up. Where you didn't provide them, the assistant kept the sample items and told you which ones to replace.
- [ ] `npm run astro-check` reports no errors.
- [ ] The changed pages look right in the browser:
  - at about **375 px** wide and at **1280 px**
  - in **every language** (the language switch, or `/fr/` or `/ar/` in front of the path). Arabic pages should read right to left

`astro-check` validates only `homepage`, `pages`, `services`, `projects`, `blog`, and `team`. Everywhere else a wrong option value passes the check. Only the page shows those mistakes.

### When Something Goes Wrong
- **The build or the check fails.** Paste the whole error, including the file and line, and ask for the cause and the smallest fix.
- **`astro-check` complains about the config.** Run `npm run toml:watch` once: the check needs `.astro/config.generated.json`.
- **The build warns about the site URL.** `baseUrl` in `[site]` ships as a placeholder and `src/lib/integrations/siteUrlCheck.ts` warns while it is one. Set your own domain.
- **The change does nothing.** Ask: "Which file does this text come from on this page? Check the named block in the page's frontmatter, whether its name is a key of `sectionsSchema`, the `content` prop the route passes, and the section file in `src/content/sections/english/`." A named block, and a route's `content` prop, override the section file (see [How The Theme Is Organized](/techlo/beginner/theme-mental-model/)). If the change is in `config.toml`, restart `npm run dev`.
- **The wrong header shows, or the language switcher is missing.** Those are props on `<Base>` in the page's route file: `headerLayout` (`one`, `two`, `three`; default `two`) and `headerPosition` (`fixed`, `static`, `sticky`; default `sticky`). Layout `three` has no language switcher. The footer's background comes from `hasFooterDarkBackground`.
- **I can't find a section's content file.** The older pairs aren't named the modern way: `Features.astro` reads `features.md`, `TestimonialGrid.astro` reads `testimonial.md`. Ask the assistant which file a component reads.
- **The layout broke at `/ar/`.** Ask the assistant to replace physical classes with logical ones, and to add `rtl:` handling for `translate-x-*`, transform origins, and gradient directions, which don't flip by themselves.
- **It keeps ignoring a rule.** Say "Re-read AGENTS.md, section [NAME], then redo this."

<Aside type="caution" title="Never paste secrets">
  Never paste passwords, API keys, or private customer data into an AI chat.
  Techlo doesn't need any to be customized: the form endpoint and analytics IDs
  are public values.
</Aside>