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

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/techbyte/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](/techbyte/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 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.** Take it from `src/enum.ts`: "set `cardLayout` on the services section to `[VALUE]`".
- **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="Two ways a page block silently does nothing">
  A page changes a section with a named block in its frontmatter, and its route
  passes the block on: `<TeamSection content={page?.data.teamSection} />`. The
  block is ignored, with no error, if its name is not a key of `sectionsSchema`
  in `src/sections.schema.ts`, or if the route doesn't pass it. If a change seems
  to do nothing, ask the assistant to check both.
</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`, and the route passes each one.
- [ ] Any `cardLayout` or `options.layout` value exists in `src/enum.ts`.
- [ ] No new colors like `text-[#123456]` in components. Techbyte 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, 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 `pages`, `services`, `blog`, `projects`, `team`, and `testimonial`. 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 change does nothing.** Ask: "Which file does this text come from on this page? Check the named block in the page's frontmatter, whether the route passes that block, whether the block name is a key of `sectionsSchema`, and the section file in `src/content/sections/english/`." Homepage copy lives in the section files, not in `src/content/homepage/`, which holds only the title and meta (see [How The Theme Is Organized](/techbyte/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-1` and `footer-2`, and `footer-1` also renders `ContactSection` above the footer.
- **I edited a section and the wrong page changed.** Many sections have a second version with its own file, such as `hero-section.md` and `hero-section-two.md`. Ask the assistant which route uses which one.
- **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.
  Techbyte doesn't need any to be customized: the form endpoint, the Mailchimp
  URL, and analytics IDs are public values.
</Aside>