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

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/taxo/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](/taxo/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/hero-section.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 practice.** One paragraph: what you do, for which clients, in which country, and what makes you different. Paste it into every copywriting request.
- **Your real figures.** Fees, years in practice, team size, the qualifications and registrations you actually hold. 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, or name the prop: "`headerLayout="header-1"`".
- **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. See also
  [Homepage And Page Overrides](/taxo/beginner/homepage-and-page-overrides/).
</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).
- [ ] Fees 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`.
- [ ] Any Markdown link written inside a frontmatter string uses the language-prefixed path in the French and Arabic folders.
- [ ] No new colors like `text-[#123456]` in components. Taxo uses its theme tokens (`bg-primary`, `bg-secondary`, `bg-accent`, `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, savings figures, credentials, or fees 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 option value may pass 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 change does nothing.** Ask: "Which file does this text come from on this page? Check the named block in the page's frontmatter, whether that block name is a key of `sectionsSchema`, and the section file in `src/content/sections/english/`." A named block overrides the section file (see [How The Theme Is Organized](/taxo/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: `headerLayout` (`header-1`, `header-2`) and `footerLayout` (`footer-1`, `footer-2`). The defaults are `header-2` and `footer-1`.
- **A new entry breaks the build.** A new entry with only a title has to build. Ask the assistant to read optional fields with `?.` or a default, and to keep any new schema field optional.
- **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 client data into an AI chat. Taxo
  doesn't need any to be customized: the form endpoint, the Mailchimp URL, and
  analytics IDs are public values. Client tax data never belongs in a chat.
</Aside>