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

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/veltro/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](/veltro/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, service descriptions, and job ads. 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, 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 layout value.** Take it from `src/enum.ts`: "set the services card layout to `carousel`".
- **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="Page blocks are mostly inert in Veltro">
  A section's own file in `src/content/sections/<language>/` changes it on every
  page that uses it. A route overrides it only when it passes `content`, as
  `faq.astro` does with `faqSection`. A block sitting in a page's frontmatter
  does nothing until its route passes it: the `servicesSection`, `ctaSection`,
  and `teamSection` blocks in `src/content/homepage/` have no effect today,
  because the homepage routes pass none. If you want one to work, ask the
  assistant to add `content={homepageContent?.data.ctaSection}` to that section
  in the route.
</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 new page block is actually passed to its section in the route file.
- [ ] Any `options.layout` value exists in `src/enum.ts` for that card.
- [ ] Button `variant`, `hoverEffect`, and `class` values come from `sharedButton` in `src/sections.schema.ts`, not from an out-of-date comment.
- [ ] No new colors like `text-[#123456]` in components. Veltro uses its theme tokens (`bg-primary`, `bg-accent`, `bg-theme-light`, `text-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, 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 the collections that have a schema. The `sections`, `about`, `awards`, `faq`, `pricing`, and `author` collections have none, so a wrong option value there passes the check, and a key no schema declares is dropped silently. 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 section file in `src/content/sections/english/`, and whether the route in `src/pages/[...lang]/` passes a `content` prop that overrides it." A page's frontmatter block only wins when the route passes it (see [How The Theme Is Organized](/veltro/beginner/theme-mental-model/)). If the change is in `config.toml`, restart `npm run dev`.
- **A new field is ignored.** A frontmatter key that no schema declares is dropped. Ask the assistant to add it to `src/sections.schema.ts` or `src/content.config.ts`.
- **A card layout value does nothing.** The comment beside `options.layout` is out of date in some files. The real values are in `src/enum.ts`: `ServiceCard` grid, card, carousel; `BlogCard` card, grid, horizontal, creative; `PortfolioCard` grid, masonry, horizontal; `TestimonialCard` carousel-full, carousel, card; `IndustryCard` list, grid.
- **A list page ignores an option.** List pages read `options` from that collection's `-index.md`, not from the section file.
- **The header behaves oddly on one page.** Those are `Base.astro` props in the route: `headerPosition` (sticky, fixed, static), `headerBorderOnScroll`, `hideOffcanvas`, `hideHeader`.
- **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.
  Veltro doesn't need any to be customized: the form endpoint, the Mailchimp
  URL, and analytics IDs are public values.
</Aside>