# 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 `folex` 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](/folex/beginner/editing-content/).

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/folex/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](/folex/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-agency.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 project 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 studio.** One paragraph: what you make, who you make it for, and what makes your work different. Paste it into every copywriting request.
- **Your real figures.** Rates, project counts, years in business, client names you are allowed to show. If you don't give them, tell the assistant to keep the sample values and list them for you to replace.
- **The layout name.** Copy it from the comment next to `options.layout` in the section file: "use the `grid` layout of the portfolio 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="Block names have to be real">
  A page changes a section with a named block in its frontmatter, such as
  `teamSection:` or `ctaSection:`. The name must be a key of `sectionsSchema` in
  `src/sections.schema.ts`. A misspelled block is ignored without any error, so
  the page just keeps the section's own text. If a change seems to do nothing,
  ask the assistant to check the block name against that file.
</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.
- [ ] 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. Folex uses its theme tokens (`bg-primary`, `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, awards, 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 `pages`, `services`, `blog`, `portfolio`, and `team`. A wrong option value in a `sections`, `homepage`, `about-us`, `contact`, `faq`, `pricing`, or `author` file passes the check, and an unknown icon name fails only in the browser. 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 change does nothing.** Ask: "Which file does this text come from on this page? Check the named block in the page's frontmatter, the block name against `src/sections.schema.ts`, and the section file in `src/content/sections/english/`." A named block overrides the section file (see [How The Theme Is Organized](/folex/beginner/theme-mental-model/)). If the change is in `config.toml`, restart `npm run dev`.
- **The wrong footer or header shows.** Those are props on `Base.astro` in the page's route file: `footerLayout` (`footer-1`, `footer-2`, `footer-3`), `headerPosition`, and `hasHeaderDarkBackground`.
- **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.
  Folex doesn't need any to be customized: the form endpoint, the Mailchimp
  URL, and analytics IDs are public values.
</Aside>