User Guide

What this tool does

When people search on Google, it decides which shops to show using the text on each page. Good text = more visitors. Writing it by hand for hundreds of products takes days.

This tool connects to a Shopify store and uses AI to write that text for you:

• Product descriptions: the text shoppers read on a product page.
• Meta titles & meta descriptions: the blue headline and the short grey text Google shows in its results.
• Image alt text: a short description of each product photo, for Google Images and for blind shoppers.
• Collection pages: text for category pages like "Snowboards".

It can also score a store's SEO out of 100, undo anything it published, and work on several client stores (Version 3).

Words you'll see

SEO

Search Engine Optimisation: making pages easy for Google to understand, so they show up higher in search results.

Shopify

A popular platform for running an online shop.

Dev store

A free practice Shopify store for developers. The demo uses one with sample snowboards.

Product

One item for sale, e.g. "The Complete Snowboard".

Collection

A group of products, like a category page ("Snowboards", "Gift ideas").

Meta title

The clickable blue headline in Google results. Best under 60 characters.

Meta description

The short summary under that headline. Best around 140–160 characters.

Alt text

A short written description of a photo (under 125 characters). Google reads it, and so do screen readers for blind shoppers.

Guess

Something the AI wrote that isn't backed by real product information, e.g. "waterproof" when nobody said it was.

Approve

Your OK that a piece of text is ready to go live.

Dry run

A practice publish: it lists what would change, but changes nothing.

Push / Publish

Sending approved text to the real Shopify store.

CSV

A simple spreadsheet file you can open in Excel or Google Sheets.

Backup

A copy of what the store had right before something was published. Undo uses it.

Audit

A check of every page against SEO rules, with a score out of 100.

Client store

Another person's Shopify store that you work on, connected with their permission.

The pages

Demo vs owner

This website can be used in two ways:

Product SEO (Version 1)

Write new descriptions, meta titles and meta descriptions for your products.

1. Open Review → Products tab.
2. For a first try, type 3 in Limit, then click 1. Generate. A black box shows progress. Each product takes about 10–20 seconds.
3. Read each product card. The left side is what's in the store now; the right side is the AI's version.
4. Change anything you like by typing in the boxes. It saves when you click outside the box. The counters (e.g. 43/60) turn red if text is too long. Click Show preview to see the description as shoppers will.
5. Tick Approve on the ones you're happy with.
6. Tick Dry run and click 2. Push approved to Shopify. The black box lists what would change. Nothing is changed yet.
7. Untick Dry run, click 2. Push approved to Shopify again and confirm. The badge turns green: published.

Guess checker (Version 2)

AI sometimes "fills in the gaps" and invents details. Example: it called a snowboard "perfect for the terrain park" when the product information never said that. The guess checker is a second AI that compares the text with the real product facts (name, brand, type, tags, original description) and flags anything that isn't backed up.

1. It runs automatically after each Generate. For older text, click Check for guesses at the top of the Review page.
2. Click the Has guesses filter. Each flagged card shows a yellow box listing the guesses and why each one was flagged.
3. Click Remove guesses from description to delete them in one go (the whole bullet point or sentence is removed). Or edit the text yourself.
4. Guesses inside the meta title or meta description aren't removed automatically. Edit those boxes by hand.

A green box (✓ everything is backed by your product info) means nothing was flagged.

Image alt text (Version 2)

The AI looks at each product photo and writes a short, accurate description, e.g. "The Complete Snowboard showing the teal and purple abstract geometric base and top design."

1. Open Review → Image alt text tab.
2. Click 1. Generate. Each photo appears with its old and new alt text.
3. Edit if needed (max 125 characters), tick Approve, then Dry run → Push as above.

Collections (Version 2)

Collections are category pages. The AI writes their description, meta title and meta description using the collection's name and the products inside it.

1. Open Review → Collections tab.
2. Click 1. Generate, check the guesses, edit, approve, then Dry run → Push.

Backup & undo (Version 3)

Changed your mind after publishing? Undo puts the old text back on the store.

1. Every time you publish, the tool first saves a backup: an exact copy of what the store had.
2. On the Review page, published cards have an ↶ Undo button. Click it and confirm.
3. The old text is back on Shopify, and the card shows undone. The AI's text is still there, so you can approve and publish it again any time.
4. Clicking Undo one more step goes back one more publish, if there was one.

Owners can download every backup as a spreadsheet at /download/backups.

SEO audit & score (Version 3)

The Audit page checks every product and collection against simple SEO rules and gives each a score out of 100. The store score is the average. It uses no AI, so it's free and takes seconds.

• Meta titles: missing, longer than 60 characters, very short, or the same on two pages.
• Meta descriptions: missing, longer than 160 characters, or very short.
• Descriptions: missing, or under 50 words (30 for collections).
• Image alt text: photos without alt text, or alt text over 125 characters.

Two kinds of audit

Problems marked Fix with AI → can be fixed on the Review page: Generate, check, approve, publish. Then run the audit again and watch the score go up.

Client stores (Version 3)

Work on a client's store with their permission. Each store keeps its own CSVs, backups and audit, so stores never mix.

1. Open Stores (owner only). It lists the exact steps, with copy buttons.
2. Make one small app for the client in the Shopify Dev Dashboard, and choose Custom distribution for their store.
3. Paste that app's Client ID and Client secret into Add store, then click Connect and approve on Shopify's page.
4. Click Work on this store. A yellow label in the top bar shows which client store you're on. Review, Audit and Chat now use that store.
5. To go back to the demo store, open Stores and click Work on this store on the main store.

Using the chat

The Chat page does everything above by typing normal sentences. Some examples:

When a job is running, a live progress box appears in the chat. For a real publish or an undo, the chat always shows a "Yes, …" button first. It never changes the store on its own.

Excel / CSV (optional)

Prefer spreadsheets? Click Download CSV on the Review page (one file per tab) and open it in Excel or Google Sheets. The new_… columns are the AI's text, and current_… is what's in the store now. On your own computer you can edit the file, type yes in the approved column, save it, close Excel, and then publish.

Safety: nothing changes without you

• Generating only saves suggestions. The store is untouched until you push.
• Only approved items are published, and each one only once.
• Dry run lets you preview every publish.
• If you edit text after publishing, it's marked edited and needs approving again.
• Every publish saves a backup first, and Undo puts the old text back.
• Empty fields are never sent, so existing text can't be wiped by accident.
• Online, visitors are read-only and the owner needs a password.

Set it up for your own store

About 20 minutes, completely free. Click each step to open it.

SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_CLIENT_ID=your-client-id
SHOPIFY_CLIENT_SECRET=your-secret
GEMINI_API_KEY=your-gemini-key

venv\Scripts\activate
python cli.py check      # tests the Shopify + AI connection
python app.py            # starts the website

FAQ