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

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/upstart/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](/upstart/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/home-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 and integration 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/pricing-section.md`", not "edit the pricing".
- **The page.** "The section under the hero on `/features/`."
- **Your product.** One paragraph: what it does, who it is for, and its main features. Paste it into every copywriting request.
- **Your real figures.** Plan prices, limits, seats, integrations you actually have. If you don't give them, tell the assistant to keep the sample values and list them for you to replace.
- **The option name.** Copy it from the comment next to the key: "set `layoutType` to `modern` in `why-us.md`".
- **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 named block only works if a component reads it">
  Sections read their own file in `src/content/sections/<language>/` and merge
  the `content` prop over it. A page changes a section by passing that prop from
  a named block in its frontmatter, as `index.astro` does with `faqSection:`. A
  block no component reads is ignored, with no error. Note also that
  `FaqSection.astro` reads `src/content/faq/<language>/-index.md`, not a section
  file. If a change seems to do nothing, ask the assistant to check 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, the comparison table matches the plans, and the plan labels are spelled the same everywhere in the file.
- [ ] MDX shortcode tags and their props were kept intact in `blog`, `integration`, and `pages` content.
- [ ] Keys, ids, and indentation in Markdown frontmatter, TOML, and JSON still look like the rest of the file.
- [ ] No new colors like `text-[#123456]` in components. Upstart uses its theme tokens (`bg-primary`, `bg-secondary`, `bg-accent`, `bg-theme-dark`).
- [ ] New or changed CSS uses logical classes (`ms`, `me`, `ps`, `pe`, `text-start`), not `ml`, `pr`, or `text-left`.
- [ ] No testimonials, customer names, 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 the frontmatter of `blog`, `integration`, and `pages`. Everywhere else a wrong key or option value passes the check, and a wrong Lucide icon name only logs a browser console warning. 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` or a language script complains about the config.** Run `npm run toml:watch` once: both need `.astro/config.generated.json`.
- **The change does nothing.** Ask: "Which file does this text come from on this page? Check the route in `src/pages/[...lang]/`, the named block it passes as the `content` prop, and the section file in `src/content/sections/english/`." The passed block wins over the section file (see [How The Theme Is Organized](/upstart/beginner/theme-mental-model/)). If the change is in `config.toml`, restart `npm run dev`.
- **A section won't hide.** `enable: false` works in most section files, but `HomeBanner.astro` and `IntegrationSection.astro` don't read it: those have to be taken out of the page.
- **A heading looks like the wrong size.** A section title is `h2`, and the route whose page the section opens passes `headingTag="h1"` so each page has one `h1`. Don't add heading classes by hand.
- **An integration is missing from `/integration/`.** An integration with no category keeps its own page but is left out of the lists.
- **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.
  Upstart doesn't need any to be customized: the form endpoint, the Mailchimp
  URL, and analytics IDs are public values. Cloudflare and other deploy tokens
  belong in your host's dashboard, not in a chat or a file.
</Aside>