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

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/lumio/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](/lumio/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/about-hero.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/contact-section.md`", not "edit the contact page".
- **The page.** "The section under the hero on `/about/`."
- **Your company.** One paragraph: what you do, for whom, and what makes you different. Paste it into every copywriting request.
- **Your real figures.** Package prices, team size, years in business, results you can back up. If you don't give them, tell the assistant to keep the sample values and list them for you to replace.
- **The variant name.** Lumio's alternatives are separate components: `HomeBanner`, `HomeBannerTwo`, `HomeBannerThree`, and the same for testimonials and others. Say which one you want, and remember each has its own content file.
- **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 page override only survives if the schema allows the key">
  A page changes a section for itself with the `content` prop in its route, with
  the values kept in the page's own content file. That works as written in
  collections without a schema, such as `about`, `homepage`, and `contact`. In
  `pages`, `services`, `blog`, `case-studies`, `team`, and `testimonial`, a key
  the schema does not list is dropped without an error, so use a key of
  `sectionsSchema` or ask the assistant to add one to `src/content.config.ts`.
</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.
- [ ] A key added to a page in `pages`, `services`, `blog`, `case-studies`, `team`, or `testimonial` exists in the schema.
- [ ] No new colors like `text-[#123456]` in components. Lumio 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, case-study 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 `pages`, `services`, `blog`, `case-studies`, `team`, and `testimonial`. Everywhere else a wrong value passes the check, and `menu.<lang>.json`, `src/i18n/<lang>.json`, and `config.toml` aren't validated at all. 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.
- **The config seems out of date.** `npm run toml:watch` regenerates `.astro/config.generated.json`. `astro-check`, `build`, `preview`, and `npm test` run it for you; `generate-favicons` needs it to have run.
- **The change does nothing.** Ask: "Which file does this text come from on this page? Check the route in `src/pages/[...lang]/`, the `content` prop it passes, and the section file in `src/content/sections/english/`." The page's own values win when the route passes them (see [How The Theme Is Organized](/lumio/beginner/theme-mental-model/)). If the change is in `config.toml`, restart `npm run dev`.
- **The wrong header or footer shows.** Those are props on `<Base>` in the page's route file: `header="one|two|three"` and `footer="one|two"`. The defaults are header one and footer two.
- **A new field is ignored.** In a collection with a schema, a key that is not in `src/content.config.ts` is dropped. Ask the assistant to add it.
- **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. AOS slide mirrors live in `src/styles/rtl-theme.css`.
- **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.
  Lumio doesn't need any to be customized: the form endpoint, the Mailchimp
  URL, and analytics IDs are public values.
</Aside>