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

    4. **Ask for one change.** Name the file if you know it. The tools listed in the [AI Overview](/looka/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](/looka/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` generates the config from `config.toml` and keeps watching it, 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, 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 firm.** One paragraph: what you do, for which industries, and what makes you different. Paste it into every copywriting request.
- **Your real figures.** Fees, team size, years in business, client 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 option name.** Copy it from the comment next to the option in the section file: "set `showServicesAs` 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="A page block only works if the route passes it">
  A page changes a section by putting a block in its own frontmatter, which the
  route file then hands to the section: `<ServicesSection
  content={homepage?.data.servicesSection} />`. Blocks are not matched by name.
  A block the route file doesn't pass in does nothing, with no error. If a change
  seems to have no effect, ask the assistant to check the route file in
  `src/pages/[...lang]/` as well as the content file.
</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, and the plan labels still match `common.monthlyPlan` in that language's i18n file.
- [ ] 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.
- [ ] No new colors like `text-[#123456]` in components. Looka uses its theme tokens (`bg-primary`, `bg-accent`, `bg-theme-light`, `text-dark`). Note that `light` is a grey text color, while `theme-light` is the pale background.
- [ ] 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 `blog`, `services`, `case-studies`, and `pages`. In those four, a key the schema does not list is dropped without an error, so the component never sees it. Everywhere else a wrong key or option value passes the check, and a wrong icon name fails only in the browser. 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 to generate `.astro/config.generated.json`.
- **The change does nothing.** Ask: "Which file does this text come from on this page? Check the block in the page's frontmatter, whether the route file in `src/pages/[...lang]/` passes that block to the section, and the section file in `src/content/sections/english/`." The block wins when it is passed (see [How The Theme Is Organized](/looka/beginner/theme-mental-model/)). If the change is in `config.toml`, restart `npm run dev`.
- **A section disappeared.** Check `enable` in its section content file: `enable: false` hides it without removing it.
- **A new field is ignored.** In `blog`, `services`, `case-studies`, and `pages`, a key that is not in `src/content.config.ts` is dropped. Ask the assistant to add it to the schema.
- **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.
  Looka doesn't need any to be customized: the form endpoint, the Mailchimp
  URL, and analytics IDs are public values.
</Aside>