AI Ad Generator (internal MVP)

This document uses ASD-STE100 Simplified Technical English.

TL;DR: This is an internal tool. It makes a locked brand kit from a brand URL. Then it makes four 9:16 static ads from a product URL with the a11 Studio Bold colour studio recipe. The image model paints the headline. You approve each headline before the tool renders. Then you fix text, blend the real packshot and mark the image that you use. The tool uses Convex + React.

Live: https://glad-dodo-78.convex.site (allow-listed accounts only) · Deploys: automatic when a PR merges to main

Paste the URL of a brand website. The tool gives you a locked brand kit. Paste a product URL. Start a batch. The tool gives you a maximum of four draft ads. The approval step always has four concepts: when compliance or the copy rules reject a written concept for good, a code-built product-as-subject concept takes its slot:

• The run config is fixed: look bold (Bold colour studio), engines Original, Original, Wild, Wild, funnel jobs ToF pain, MoF mechanism, MoF proof, BoF objection.
• Each ad is 9:16 (1152×2048). The tool composes it for the 4:5 feed area.
• GPT Image 2.5 Sunburst paints the headline, the sticker and the scene text (ai_painted). The image has no CTA. The CTA is the Meta button.
• The market is Singapore by default (S$, Singapore English). You can change it in Settings → Pipeline.

The source of the recipe is docs/a11-bold-spec.md (the a11 Studio spec). The prompts in the code are the verbatim text of that spec, with the deviations that the note at the top of the spec lists (safe zone, prop limit, palette size, no CTA). docs/ad-research.md gives the research rules that the tool also uses.

Stack: Vite + React + TypeScript SPA · Convex (DB, auth, storage, scheduled actions, live queries) · Convex static hosting (.convex.site) · Convex Auth (email + password, allow-listed emails) · Tailwind v4 + shadcn/ui + Fluid Functionalism (@fluid registry) · Firecrawl (scrape + search) · OpenRouter (anthropic/claude-haiku-5.5, strict JSON schema when the provider supports it, else JSON-object mode) · Replicate (GPT Image 2.5 Sunburst, background remover) · jimp + resvg (crops and composites in a Convex Node action).

The tool has no payments and no public links. Each allow-listed user who is signed in can open all workspaces. That user can also write comments.

---

How it works

Rule of the owner: an LLM does every step that an LLM can do. The only required human step is the approval stop: read and choose the headlines and stickers, approve, then click Render. After that, everything is automatic. You click Mark used on the image that you spend on. The manual text-fix, blend and regenerate are optional advanced tools under More.

A batch is one run of the recipe. It goes through these steps (convex/pipeline.ts). Each automatic step is a scheduled action. The batch view shows the current step.

Time limits, progress and retry

• Time limits. Each provider request has a time limit: Firecrawl scrape 100 s, search 120 s, map 60 s; OpenRouter 120 s for each try; Replicate 90 s to start a prediction, 30 s for each status check and 6 minutes in total (then the tool tries to cancel the prediction; the cancel request can fail); a candidate image download 20 s in total (all redirects and the full body), a Replicate output download 60 s; the DNS check of a candidate image 5 s. One candidate image (download, decode and store) has 45 s. After that, the tool skips it and continues with the other candidates. A Firecrawl, OpenRouter or Replicate timeout (also while the body is read) gives a TIMEOUT: ... error. An image download timeout drops that candidate. A Replicate status check that gives 408, 409, 425 or 429 is tried again. Another 4xx status stops the prediction wait at once, also when the body is empty. A Shopify JSON timeout makes intake use Firecrawl only. A timed-out OpenRouter call keeps its reserved cost on the ledger, because the provider can still bill it.

• Step deadline. Each automatic step must finish in 8.5 minutes (convex/lib/http.ts). Convex stops an action at 10 minutes, and then the action cannot write its status. Thus the step writes failed and sends a Sentry report before that limit.

• Watchdog. Every 5 minutes, convex/watchdog.ts (convex/crons.ts) looks for work with no progress for 12 minutes. Each progress write sets heartbeatAt. A batch in research or concepts becomes failed. An ad that is working becomes failed (or ready with a note when it has an image). An ad at the approval stop that is busy (Swap concept, the silent check after an edit, Improve) goes back to its concept. Each case goes to Sentry (step ad-stalled for ads).

• Progress text. The batch shows the sub-step, for example “Searching the web (2 of 3 done: brand pages, reviews)…”, “Downloading candidate photos (3 of 8)…”, “Checking photo 2 of 4 (unit) for page text, round 1…” and “Writing concepts (1 of 3 writers done)…”.

• Retry from this step. A failed batch shows Retry from … when an automatic step failed before rendering started. The retry keeps the work that the batch has already paid for and uses the settings that the batch started with. It starts at the first step that has no saved result:

  • research;
  • the brief (it uses the saved search results again when the search queries did not change);
  • reference photos;
  • art direction;
  • concepts (it writes all 4 concepts again);
  • approval (all concepts are saved: no paid call).

  After a timeout, wait 2 minutes before you retry. The old step can still be stopping. After rendering started, use the actions on each ad.

• Image memory. Pages often list one photo at many sizes (for example Webflow -p-500 … -p-2600). The tool keeps one size for each photo, near 1600 px. It asks the Shopify CDN for a 1600 px copy. It downloads 2 candidates at a time, decodes photos above 2 megapixels one at a time and keeps reference images at a maximum of 2048 px. The tool does not decode an image above 6 megapixels or above 6000 px on one side (a 3840×5760 JPEG used about 600 MB in jimp). It reads the pixel size from the PNG, JPEG, GIF or BMP header. It does not decode a file in another format (except SVG and WebP) above 2 MB. For a Webflow original that is too large (in pixels or above the 15 MB download limit), it tries the -p-1600, -p-1080 and -p-800 sizes of the same photo. If no size is small enough, it skips the image. A candidate that is still working after its time limit deletes its stored file when it ends. For other hosts, a ?w= or ?width= value selects the size, like the Webflow rule. Vision models in the batch pipeline get each image as a URL when the file is 3.5 MB or less (brand analysis is different: see Brand extraction). A larger file (for example a full-size PNG draft) goes as a data URI at a maximum of 1568 px, because Anthropic models refuse images above 5 MB. The data URI is JPEG. An image with transparency stays PNG; if that PNG is still above 3.5 MB, it becomes JPEG on white at 1024 px, then at 768 px. If it is still too large, the tool sends the original URL. The asset-pick vision call gets copies at a maximum of 1024 px (made one at a time). Exception: a WebP image cannot be decoded here. The tool keeps the original WebP file, does not crop it and does not make it smaller. We expect these limits to keep the asset step below the memory limit of a Convex action. This is not yet confirmed on Convex.

• Research retry. A retry of the research step uses the saved search results again. Only the searches that failed run again.

• Thinking effort. Some models think before they answer (for example anthropic/claude-haiku-5.5). The thinking tokens count against max_tokens. Haiku 5.5 has no thinking budget in tokens: it takes an effort level (low, medium, high). Each LLM job sends its effort (reasoning.effort, with the reasoning excluded from the reply): low for the text check, reference crop, asset pick, compliance rating, research plan and brand vision; medium for the brief, art direction, image prompt writer, draft review and brand kit analysis; high for the Original and Wild copywriters and the concept review (Anthropic: high effort for strict instruction following). The effort is a setting for each job (LLM_JOBS in convex/lib/settingsRegistry.ts). This applies only when the model endpoints accept reasoning (OpenRouter /models/{id}/endpoints); when the lookup fails or the model does not reason, the call sends no effort and max_tokens is the answer room. With reasoning, max_tokens keeps the full answer room after 8,000 thinking tokens and after a thinking budget of the effort’s share of max_tokens (low 0.2, medium 0.5, high 0.8: how OpenRouter can turn an effort into a budget for Anthropic models) (REASONING_HEADROOM, completionCap in convex/lib/openrouter.ts). max_tokens is only a limit, and OpenRouter charges only for the tokens that the model uses. The old token budget (reasoning.max_tokens) overran by 1.5 times, and with a cap of answer + 4 × budget, 7 replies in the B3 batches were all thinking and 0 characters of text. A reply with no JSON is noted in the spend log with its thinking tokens and effort. If a provider refuses reasoning with a 400, the tool sends the call one more time without it.

• Strict JSON and model parameters. Before an LLM call, the tool reads the supported parameters of the model from OpenRouter (/models/{id}/endpoints, kept for the life of the process). It uses strict output only when an endpoint supports it. The tool sends no temperature (Haiku 5.5 refuses a value other than the default). If the lookup fails, the tool sends no reasoning. A selected WebP unit, in-use or scale photo that needs a crop is dropped; only a WebP packshot stays (uncropped).

• Product name. Intake keeps the raw page title in title and a clean name in name (for example “Iced Oat Latte”). The name comes from the Shopify product title, the Firecrawl product title, or a short LLM clean-up of the page title, og:title and first heading (model of the Brief job, effort low). If the LLM call fails, takes longer than 45 s or hits a spend cap, a rule-based clean-up is used (intake does not fail because of the name). Product cards, batch labels and research queries use the name. Read the page again to get a name for an old product.

There is no promote step and there are no finals. Each ad keeps its image versions (the last 10, Settings → Pipeline). The version that is marked used is always kept. You can restore an old version, download the image, write comments and export a ZIP (the images in the format of each stored draft, JPEG for new drafts and PNG for old drafts, + concepts.csv). The CSV has a row for each concept, also before its draft renders. The CSV prefixes a cell that starts with =, +, - or @ with ', so a spreadsheet does not run it as a formula.

Meta safe zones (approved change to the spec)

han approved this change to the spec: Meta’s 9:16 Reels and Stories interface covers more than the spec says. The values come from Meta’s safe-zone help page (https://www.facebook.com/business/help/980593475366490) and Meta’s Ads Guide numbers. convex/lib/frame.ts has the sources.

• The tool composes for the 4:5 feed area.
• Each sticker, badge, logo and important text keeps its bottom edge at or above 65% of the height, stays clear of the 6% side margins (within 6% to 94% of the image width) and stays out of the rail.
• Reels ads with a disclaimer need the bottom 40% clear. The tool does not add disclaimers.
• convex/lib/frame.ts is the one source of the numbers. The safe-zone overlay, draft-review rule H, the layout warning, zoneBreaches, moveInstruction, the safe fit and the sticker lift read it. convex/lib/defaults.ts uses the same constants in the spec text. Do not write the numbers as literals in other files. assertZoneNumbers checks the code defaults of the safe-zone prompts (the draft-review default and draft-review rules E to H) when the module loads: a percentage that is not a value from frame.ts stops the Convex deploy. It does not check prompt text that a user saves on the Settings page. Rule H is always added by code, so its numbers stay correct after a Settings edit. The band-render prompt defaults (imagePromptSystem, textModeRules, the four composition guides) have no percentages at all: noPercent in convex/lib/defaults.ts stops the deploy when one has a percentage, and a module-load check in frame.ts stops it when BAND leaves the safe area.
• Generation uses stricter targets than the safe area, because image placement is not precise (PLACE and AIM): the logo and the headline start at least 18% down from the top, and the prompt aims at about 21% for the logo and 23% for the headline (the model places elements a few percent higher than asked); each text, logo, sticker and badge ends at most 62% down; the sticker aim is a centre at about 54% (an aim, not a limit); below 65% there are only the product base, props and the backdrop.
• The Safe zones button on a draft card shows the overlay: the area outside the 4:5 band is dark, the Meta interface zones have rose hatching with dashed edges, and the safe area has a green outline. There is no sticker guide.

Layout archetypes

Each slot has a different composition, so the four ads look different in the feed (Meta’s Andromeda delivery needs different creatives). All four use the shared Bold colour studio look. The two Wild slots break the grid.

The archetype text is in Settings → Prompts (Composition). The names are in convex/lib/recipe.ts. These archetypes replace the real-place compositions of the spec (wide real moment, top-down flatlay, macro close-up, in hand), because the draft review blocked studio renders that did not show a real place.

Stage per ad (colour field, layout, sticker style, real-world state)

Code sets the stage of each ad (convex/lib/stage.ts). The stage is not stored. Code makes it again from the batch palette, the slot position and the batch id (stageOf). It costs nothing.

• Colour field: each ad of a batch gets a different field from the art-direction palette. The MoF proof slot always gets a two-colour split (brand colour and pack colour, one straight line). The other three slots get the brand colour on a paper sweep, a warm off-white with one brand-colour block, and a printed page with a thin brand-colour border, in an order that changes with the batch. The render prompt does not get the look’s Background: line. The stage block replaces it.
• Layout: the product side (left or right) alternates from slot to slot. The sticker sits under the headline or on the side opposite the product. It never sits on the product side. The headline is aligned opposite the product (centred on the flat-lay). The band render gives the heights.
• Sticker style: a plain line of set type in the supporting typeface, with an optional thin rule. There is no blob, cloud, scalloped, starburst or tilted badge. Only the BoF offer ad (slot 4) can use one flat tag.
• Real-world state (physicsBlock): the prompt states the real state of the product (condensation on a cold product, a drip on a poured drink, a torn sachet edge), the real colour of the prepared product (from the in-use reference description), one small imperfection, contact shadows, true sizes and no stock props (closed laptop, blank notepad, blank paper bag, plain pillow, bedside lamp, generic mug) unless the headline names them.
• Scene rules for the writers (SCENE_RULES): the concept writers and the concept review get the same physics and prop rules, and they do not describe the backdrop colour.
• Scene lint (sceneProblems, no LLM call): code reads the concept scene and layout text before the render. An object that floats or balances, an object on a pouring or tipped object (not one held in a hand), a stock prop that the headline does not name, an empty glass, cup or bottle when the headline says the product is stirred or mixed in, or an abstract prop (abstractProps: a sphere, disc, plain ball, cube, cylinder, plinth or blank card; a block only in the look’s props line, because in a scene a block is the split field) becomes a line in SCENE CORRECTIONS at the top of the real-world state block. The prompt writer follows the correction. The concept is not dropped and not rewritten.
• Real props: the look text asks for concrete everyday objects from the buyer’s world (a ceramic cup, a measuring spoon, a ginger root) and never abstract shapes. The spec text “at most two props, simple in shape” made the art director write “a single lemon-yellow disc or a pale pink block” (B6, B7). When the batch look’s props line still names an abstract shape, each render prompt gets a correction to ignore it. Offline on B1 to B7: 8 of 16 batch looks and 4 of 56 concept scenes named a primitive (tests/props.test.ts).
• Brand colour (brandBackdrop in convex/lib/color.ts): the art direction gets the brand kit’s primary colour. When the palette that the art direction reads off the pack and the logo has a close colour (RGB distance 40 or less), code puts that colour first as the backdrop, so the brand field, the logo contrast and the review use the brand colour. The label colours stay the second field and accents. A kit primary that the pack and logo do not show (for example a site link colour) changes nothing.
• The style anchor (ad 1, attached to ads 2 to 4) sets the type, the palette, the light and the finish. It does not set the colour field.

Why: the graded B2 and B3 ads had one backdrop colour for the whole batch, a perfect seamless sweep, the same blob sticker on 10 of 11 ads, the product on the right in 9 of 11 ads, stock props and impossible physics. The reference brands (Graza, Olipop, Ritual) change the field and the layout from ad to ad.

Copy tournament (diagnostics only)

convex/lib/tournament.ts picks the best headline of N for one ad. One call asks for 8 candidates (Original copywriter model and effort); the model can return fewer. Code lints each candidate for format (2 words or more, a capital first letter, a full stop) and with the rules of the concept (length, pushiness, spec list, sticker echo, product name, funnel job), the viewer rule (no “you”, assumesViewerProblem) and no repeat of another ad’s headline. The current headline and the clean candidates then go into a knockout. A judge (concept review model, effort low) compares two headlines at a time, with reference headlines (Graza, Olipop, Ritual) and the buyer’s own words as anchors. The A and B sides come from a hash of the pair, not from the list order. Operator edits that are headline-sized go in as `` blocks (at most 5). The prompts put the data in XML tags first and the task last.

The pipeline does not use it yet. diagnostics:copyTournament runs it on a stored batch and writes nothing: npx convex run diagnostics:copyTournament '{"batchId":"..."}'. It returns the candidates, the lint drops, the duels and the winner for each ad, for a blind comparison with the shipped headlines.

Playbook

The Settings → Playbook tab has the playbook sections. Their first text is from the appendix of the spec. Each step gets only its sections, as ## title and then the body (spec §6):

The copy and metaphor steps also get the last 8 headline edits (before → after) that operators made for the brand.

Prompt hygiene (PLAYBOOK in convex/lib/defaults.ts, tests/prompts.test.ts): the playbook text of each step agrees with what the pipeline does. The copy writers get no “present the headlines for approval” line (the approval stop is in the app), no Meta UI frame and no CTA bar (no CTA is painted), and the headline rules once (in the copy rules). The Wild method has no image-prompt phase (the image-prompt writer does that) and is always grounded wild. The image-prompt writer gets no halation, theatre spotlight, phone-flash, illustration mode or “different genre per card” (the batch has one studio look). A test fails when one of these comes back. The LLM steps for concepts (Original, Wild, rewrite, compliance rating, concept review) send their data in XML tags (, , , , , , ``) and put the task last (tag, userPrompt in convex/lib/compose.ts; Anthropic prompting guide).

Budget

Before each paid call, the tool records an estimated cost in the spend table (convex/lib/metered.ts). When a billed attempt is not used (a reply that is not JSON, a reply that is cut off, a provider error or a timeout), the row also gets a short note with the reason. The tool blocks the call if the cost goes above a cap:

• The monthly cap (default $20) applies to all paid calls.
• The per-batch cap (default $1, han’s limit for 4 ads) is a hard stop. It applies to all calls of a batch (OpenRouter, Replicate and Firecrawl), also the text-fixes and blends that you do later. While the automatic steps run, the batch keeps the cap from its start. Operator actions (Swap concept, the silent check after an edit, the advanced text-fix and blend) always use the current cap, also while the batch renders. The automatic repairs after the text check use the cap from the start of the batch.

OpenRouter reports a real cost, and that cost replaces the estimate. Firecrawl and Replicate calls keep the estimate. Sunburst has no published price for each image. Thus the image costs are settings (draft low, medium, edit high) in Settings → Costs & budget. Check the Replicate bill and change them if necessary. convex/lib/estimate.ts calculates the estimate for each batch. The Settings page preview uses the same function. The estimate has a typical value and a worst case. The worst case counts every retry path (Wild metaphor ratings, duplicate repairs, all rewrite rounds and the safer angle), 3 paid attempts for each LLM call and the more expensive automatic fix for each ad. If the typical cost is more than the per-batch cap, the tool refuses the batch before it starts. The worst case can be more than the cap: then the budget reservation refuses the paid calls past the cap. Research, references, art direction and concept calls keep money for the four first drafts (when the optional rewrite rounds, the safer angle or the new concepts would use that money, they stop, and the batch goes on with the concepts it has), and the automatic repairs keep money for the drafts that wait (keepUsd), so such a batch loses repairs, not drafts. The cap applies to reservations: an OpenRouter call reserves its estimate and then settles at its real cost, so the real total can pass the cap by the difference on the last calls (cents). The Start dialog shows the typical cost, the worst case and the hard stop.

Convex usage (database I/O and data egress)

The owner uses the Convex Starter plan (since 2026-10-16). The plan includes 1 GB of database I/O and 1 GB of data egress each month. Usage past these amounts is billed to the owner’s card ($0.22 for each GB of database I/O, $0.132 for each GB of egress, US prices at https://www.convex.dev/pricing). The owner wants this cost as low as possible. In October 2026 the app used more than the included amounts in 15 days. Thus the code obeys these rules:

• Cost contract tests. tests/cost.test.ts runs the hot queries and mutations on realistic data (tests/fixtures.ts: 30 batches, a live batch with 4 ads and 12 drafts, 90 spend rows) through a meter (tests/meter.ts). The meter counts the bytes of each document that a function reads and writes (a patch writes the full document again). Each function has a byte budget. When a change makes a hot path read more, npm test fails. Lower a budget when a change makes a path cheaper. Raise a budget only with the reason in the PR.

• Measure prod, do not guess. CONVEX_DEPLOY_KEY=... python3 scripts/convex-usage.py --minutes 12 prints one row for each function from the execution log of the deployment (the newest ~1000 executions): the calls, the cache hits, the total database I/O, and the averages per call of the bytes read, written and returned. Use --minutes to follow a batch while it runs. Use --jsonl out.jsonl to keep the raw row of each execution. The dashboard bars cover the full billing period and can include old code.

• Spend totals. budget.reserve and budget.settle keep running totals in the spendTotals table, in the same transaction as the spend row. The key is month: or batch:. When the totals exist, the cap checks, the budget meter (budget.summary) and the batch view read one small document. They do not read all spend rows. When a total does not exist (a new month or an old batch before rebuildTotals), the code reads the spend rows one time. A mutation then saves the total; a query does not. Do not write spend rows in other code, because the totals do not see them. If a total is wrong, run npx convex run budget:rebuildTotals '{"month":"2026-10"}'. This mutation calculates the totals again from the rows. You can run it again with no effect. The list of recent calls is a separate query (budget.recent, 40 rows). Only Settings → Spend reads it.

• Small batch documents. Every status write rewrites the whole batch document, and the batch list (30 batches), the budget checks and the watchdog read batch documents. Thus the batch document holds only the status fields and small metadata (ids, the settings snapshot, the product label, the cut-out state; about 0.5 KB with the default settings). The settings snapshot holds only the settings that differ from the code defaults; a long prompt override on the Settings page makes it, and each batch read and write, larger. The plan of a batch (research summary, brief, references, art direction, look, logo variants) is in batchPlans (planFields in convex/schema.ts). withPlan (convex/lib/plan.ts) adds the plan to a batch for the batch view and the pipeline, and patchBatch sends plan fields to batchPlans. The research text (about 40 KB for each batch) is in batchResearch; only the research step reads it. The batch keeps a copy of the product label (productTitle, productUrl), so the batch list does not read the product page text. Do not add large fields to batches. Put them in their own table.

• Small draft documents. The Sunburst or edit prompt of a draft (about 2.4 KB) is in draftPrompts. No code reads it; it is only for diagnosis. The batch view, the version strip and the pipeline read the draft without it.

• No live re-run for each paid call. A paid call writes the spend totals up to two times (the reserve, and the settle when the real cost or a note arrives), about 140 to 180 times for each batch. The batch cost is its own query (budget.batchSpend), so the batch view (batches.get, about 27 KB for each run) does not run again for each paid call. tests/cost.test.ts checks which writes re-run which live queries.

• Product page only where needed. loadForPipeline reads the product page and the brand kit (about 20 KB) only with inputs: true (research, references, art direction). The concept, render and repair steps do not read them.

• JPEG draft images. The Sunburst request asks for JPEG (output_format: "jpeg", output_compression 95), and storeDraft stores each new full-size draft as JPEG (it re-encodes any other format it gets) quality 95 with full colour resolution (encodeMaster, MASTER_JPEG_QUALITY in convex/lib/imaging.ts). A full-size draft is about 0.6 MB instead of a 3 MB PNG (44.5 to 47 dB PSNR on four B5 drafts; no visible change in 3x crops of small label text; three more encodes lose less than 0.1 dB). Each full-size image moves several times for each draft: the download from Replicate, the image edits (Replicate reads the base image), the code repairs (safe fit, logo pill, sticker lift, text-fix read it), the download and the ZIP export. Drafts before 2026-10-16 stay PNG; the download and the ZIP use the extension of the file. The field keeps the name pngStorageId. Reference images, the logo, logo variants and cut-outs stay PNG (they need transparency). Exception: the asset pick keeps a chosen WebP candidate as WebP (it cannot be decoded here).

• Draft previews. Each new draft normally also has a JPEG preview (previewStorageId, long side 1568 px, about 125 KB). If the preview step fails, the draft has no preview and these places use the full-size image (more egress). The cards, the version strip, the text-fix and blend dialogs, the draft review, the text check and the style anchor use the preview. The download, the ZIP export and the pixel edits use the full-size image. Each download from Convex storage counts as data egress, also a download by OpenRouter or Replicate and a download by our own actions.

• Reference copies for vision. For a reference above 150 KB, visionRefs (convex/pipeline.ts, table visionCopies) tries to make one small JPEG copy (long side 1568 px, on white when the reference is a cut-out) at its first vision check. The later draft reviews and text checks of the batch send the copy when it exists. If the copy fails (for example a WebP file or a decode error), they send the original. Renders and edits still send the original reference to Replicate.

• No download to measure a file. visionSafeUrls gets the size of our own stored files (refBytes, the draft bytes). It does not download a file only to measure it.

• One-time data moves (run them after the deploy; the deploy does not run them). Each move is idempotent. Each call does one page: run it again with {"cursor":""} until isDone is true, also in a dry run. The plan and prompt move (2026-10-16) has dryRun: true: run npx convex run migrations:splitColdFields '{"dryRun":true}' for every page, then the same pages without dryRun; do the same for migrations:moveDraftPrompts; then npx convex run migrations:verifySplit (both counts must be 0). The legacy logoVariant files are not deleted by the move; remove orphaned files with a dry run and a backup list first. Older moves (no dry run): npx convex run migrations:slimBatches (25 batches for each call; run it again with {"cursor":""} until isDone is true), npx convex run budget:rebuildTotals, and for the newest batches npx convex run previews:backfill '{"batches":3}'. Each download for a preview backfill counts as egress, so do not run it for all batches.

---

Settings (/settings, gear icon in the top bar)

The Settings page is one global location for the recipe. It applies to all brand workspaces. A workspace cannot override it. Each allow-listed user who is signed in can see and edit it.

Precedence: Settings page value (DB) > Convex env var > code default.

• convex/lib/settingsRegistry.ts declares each tunable one time (type, range, default, optional env var).
• The default prompts and playbook sections come from convex/lib/defaults.ts. That file uses convex/lib/specText.ts, which scripts/gen-spec-text.py makes from the verbatim code blocks of docs/a11-bold-spec.md.
• Provider API keys, ALLOWED_EMAILS and ALLOWED_EMAIL_DOMAIN are env-only. They never show on the page.

Each batch keeps a record of its settings (batches.settingsVersion / batches.settingsSnapshot). The automatic steps use that snapshot, also if the settings change during the batch. The operator actions (Swap concept, the silent check after an edit, regenerate, the advanced text-fix and blend) use the current settings. The automatic repairs use the snapshot.

---

Setup

Prerequisites: Node 22 (CI uses this version), a Convex account, and API keys for Firecrawl, OpenRouter and Replicate.

1. Install and create the Convex project

npm install
npx convex dev          # log in, create a project; writes CONVEX_DEPLOYMENT + VITE_CONVEX_URL to .env.local

Keep npx convex dev in operation in one terminal. It pushes the functions and makes convex/_generated again.

2. Convex Auth keys

npx @convex-dev/auth    # sets SITE_URL, JWT_PRIVATE_KEY and JWKS on the dev deployment

SITE_URL must be the address of the SPA. For dev, use http://localhost:5173. For prod, see step 6.

3. Access list (email + password)

Sign-in uses the Password provider of Convex Auth. You do not need a Google Cloud setup. Only allow-listed emails can create an account:

npx convex env set ALLOWED_EMAILS "[email protected],[email protected]"
# optional: let anyone on a domain in
npx convex env set ALLOWED_EMAIL_DOMAIN yourcompany.com

The server applies the list in three locations:

• The Password profile() (sign-up and sign-in).
• beforeSessionCreation.
• requireUser() in each query/mutation.

If neither variable is set, no person can sign in. The tool fails closed. If you remove an email from the list, that person loses access at their next request. Passwords must have 10 or more characters.

Note: the tool does not verify emails. For strict access, add the exact emails of teammates. Do not add a full domain.

4. Provider keys and budget

npx convex env set FIRECRAWL_API_KEY fc-...
npx convex env set OPENROUTER_API_KEY sk-or-v1-...
npx convex env set REPLICATE_API_TOKEN r8_...
npx convex env set MONTHLY_SPEND_CAP_USD 20
npx convex env set PER_RUN_SPEND_CAP_USD 2

FIRECRAWL_BASE_URL, OPENROUTER_BASE_URL and REPLICATE_BASE_URL are optional. Do not set them in production. A local test deployment can set them to a mock server. Then the full pipeline runs with no paid calls.

You change all other values on the Settings page (models, prompts, pipeline, cost estimates, caps). The env vars in .env.example also work. They are a fallback with a lower precedence than the Settings page.

5. Run locally

npm run dev             # vite on :5173 + convex dev

6. Deploy (Convex static hosting)

Set the same env vars on the production deployment (add --prod). Set SITE_URL to the static site:

npx convex env set --prod SITE_URL https://.convex.site
npx convex env set --prod ALLOWED_EMAIL_DOMAIN yourcompany.com
npx convex env set --prod ALLOWED_EMAILS ...      # etc. for every variable above
# JWT_PRIVATE_KEY / JWKS for prod:
npx @convex-dev/auth --prod

Then use one command to build, push the backend and upload the SPA:

npm run deploy          # = npx @convex-dev/static-hosting deploy

The app is live at https://.convex.site. The HTTP routing is “app-owned root”. convex/http.ts registers the Convex Auth routes (/api/auth/*, /.well-known/*) first. It registers the static SPA catch-all last.

---

Production, CI/CD and workflow

Workflow rules (for people and AI agents):

1. Do not commit to main directly.
2. Make a branch (feat/…, fix/…, ci/…, docs/…) and open a PR.
3. Wait until CI and the Cubic AI review are complete.
4. Correct the valid Cubic findings.
5. Squash-merge the PR. Do not merge while Cubic is in progress.
6. A merge to main is the deploy. Do not run npm run deploy manually. Run it only if CI is broken.
7. Do not commit secrets or .env.local. Keep provider keys only in Convex env vars. Keep the deploy key only in GitHub Actions secrets.
8. If you change the schema, make it backwards compatible with the prod data. Convex validates the schema on deploy. If the schema is not compatible, the deploy fails.
9. Cost is important. Keep the code default draft quality at low. Change it only if the owner tells you to. (The team changes these values on the Settings page.)

---

Monitoring (Sentry)

The tool sends errors to Sentry (org ai-ad-generator, project ai-ad-generator, US region). The DSN is public because it can only send events. Thus the repo has the DSN as a fallback. Env vars can override it.

• Frontend (src/main.tsx):
  • @sentry/react with an ErrorBoundary, React 19 root error hooks and browserTracingIntegration (tracesSampleRate 0.2).
  • No session replay.
  • environment = Vite mode. release = the commit SHA (GITHUB_SHA in CI).
  • No automatic PII. Sentry gets only the email of the signed-in user.
  • DSN: VITE_SENTRY_DSN (build time) or the committed fallback.
• Backend (convex/lib/sentry.ts):
  • reportError(err, context) has no dependencies. It uses fetch to POST an event envelope. It never throws, and it has a 3 s timeout.
  • The code calls it each time a pipeline step, a batch, a product ingest or a brand extraction fails. The steps are: research, assets, art-direction, concepts, improve, render, auto-regenerate, draft-review, auto-edit, text-check, text-fix, cutout and blend. The watchdog also reports stalled batches (with their step) and stalled ads (step ad-stalled).
  • Tags: kind (pipeline | batch | product-ingest | brand-extraction), step, adId / batchId / productId / workspaceId.
  • The code reports BUDGET (spend-cap) errors at level info, not as errors.
  • Mutations cannot use fetch. Thus they schedule internal.monitoring.report.
  • The code redacts raw model output in error messages.
  • DSN: SENTRY_DSN on the Convex deployment (npx convex env set SENTRY_DSN ... --prod) or the committed fallback.
  • The default environment is production. To label a dev deployment, set SENTRY_ENVIRONMENT on it.
• Triage: Hark (the assistant of the owner) reads Sentry through the Sentry MCP server each morning at 09:00 SGT. Hark does these tasks:
  • It corrects real bugs through the usual flow: branch → PR → CI + Cubic → merge.
  • It resolves noise and expected errors (for example, BUDGET).
  • It escalates all issues that touch auth, billing or secrets.

Engineering principles: the team works by poteto’s pstack principles (Lauren Tan, MIT, https://github.com/cursor/plugins/tree/main/pstack). AGENTS.md section 4, “How we work (pstack)”, gives the rules for this repo.

---

Notes for AI agents

• Before you change convex/, read AGENTS.md / CLAUDE.md and convex/_generated/ai/guidelines.md (official Convex guidance). The Convex agent skills are in .agents/skills.
• The recipe is docs/a11-bold-spec.md. Do not change the prompt text in convex/lib/specText.ts by hand. Change the spec and run python3 scripts/gen-spec-text.py. Put changes to the spec (for example the Reels safe zone) in convex/lib/defaults.ts, with a comment.
• convex/lib/settingsRegistry.ts declares each tunable (precedence: DB > env > default). convex/lib/config.ts is env-only (access, provider keys, provider base URLs). To add a setting:
  1. Add it to the registry, with a default.
  2. Read it from the resolved Settings object.
  3. The Settings page then shows it automatically.
• Queries/mutations load the settings with loadSettings(ctx) (convex/lib/settings.ts). Automatic pipeline steps use the snapshot of the batch (settingsFromSnapshot). Operator actions call internal.settings.loadInternal. Do not read tunables from process.env directly.
• LLM calls go through chatJson (convex/lib/openrouter.ts) with a schema name from convex/lib/schemas.ts. The call asks for a strict JSON schema (response_format: json_schema, strict: true) and provider.require_parameters. If no provider supports it, the call uses JSON-object mode with the schema in the prompt. The code still checks each field (asStr, asConcept, …). It makes a maximum of 3 attempts. It does not try again after a BUDGET error or a missing API key.
• Image calls go through sunburst() (convex/lib/replicate.ts). It always sends the input object of the spec: aspect_ratio 1536x1152 for a draft (band render), 1152x2048 for a whole-image edit (for a crop edit such as a text-fix or the sticker removal: the accepted size nearest to the crop aspect, EDIT_SIZES in convex/lib/imaging.ts; the crop grows to that aspect first. Sunburst refuses other sizes with a 422 error), quality, output_format png, number_of_images 1, background opaque, moderation. Do not leave size or quality to the model defaults.
• Image work (crop, paste back, composite) is in convex/lib/imaging.ts ("use node", jimp + resvg). Only "use node" files can import it.
• Message formats (brief as text, look string, reference block, playbook) are in convex/lib/compose.ts. The frozen run config is in convex/lib/recipe.ts. The safe zones are in convex/lib/frame.ts.
• The access control is in convex/lib/access.ts. Each paid call goes through convex/lib/metered.ts with an estUsd from a cost setting and the batchId.
• Use reportError (convex/lib/sentry.ts) with a step name to report new failure paths. In a mutation, schedule internal.monitoring.report instead.
• The tables runs, ads, adVersions and fonts are legacy. They stay in the schema only so that prod data validates. Run legacy:purge to delete their rows. A later change can then remove them.
• To check your work, run npm run typecheck, npm test and npx vite build. CI runs the same steps.
• The UI primitives are in src/components/ui/. Use them again. Do not add new component libraries. Button is whitespace-nowrap/shrink-0. Thus, in a row, give the inputs next to it min-w-0 flex-1.
• Auth uses email + password with an allow-list. To give a person access, add their exact email to ALLOWED_EMAILS (comma-separated) on the prod deployment.

---

UI components (Fluid Functionalism)

components.json registers the @fluid registry. The Fluid components in src/components/ui/ (button, card, badge, tabs, dialog, tooltip, banner, thinking-indicator) came from these commands:

npx shadcn@latest registry add @fluid
npx shadcn@latest add @fluid/button @fluid/card @fluid/badge @fluid/tabs @fluid/dialog @fluid/tooltip @fluid/thinking-indicator @fluid/banner

The repo has two local changes:

• Upstream, card.tsx imports next/link. For Vite, a plain `` shim replaces it.
• src/lib/utils.ts uses clsx + tailwind-merge. The registry changed it to use a cn package that does not exist.

Plain inputs are in src/components/ui/field.tsx. To add more components, use npx shadcn@latest add @fluid/.

Motion (transitions.dev)

The UI transitions come from transitions.dev by Jakub Antalik (free tier). Thank you to Jakub Antalik for these transitions.

• The CSS is in src/styles/transitions.css. src/index.css imports it.
• The React helpers are in src/lib/motion.tsx. The menu dropdown is in src/components/ui/menu-dropdown.tsx.
• The app uses these free transitions: modal open and close, menu dropdown, panel reveal, card resize, text states swap, number pop-in, icon swap, success check and error state shake. The app uses no Pro transitions.
• Each transition has a prefers-reduced-motion: reduce guard. When the user’s system asks for reduced motion, the content changes immediately, with no movement.
• The Transitions.dev License allows use in a product. Do not publish src/styles/transitions.css as a separate transitions library.

---

Project layout

docs/
  a11-bold-spec.md     the recipe (verbatim prompts)
  ad-research.md       research rules
convex/
  schema.ts            tables: workspaces, brandKits, products, batches, batchResearch, batchAds, adDrafts, visionCopies, playbookEdits,
                       comments, spend, spendTotals, settingsVersions, modelCatalog (+ auth; + legacy runs, ads, adVersions, fonts)
  auth.ts, auth.config.ts, http.ts, convex.config.ts
  workspaces.ts        list/create/re-extract (one workspace per brand)
  brandExtract.ts      escalating brand extraction (action)
  brandKits.ts         versions (keep 5), roll back, edit
  products.ts          add/list/read again
  productIngest.ts     intake: Shopify JSON + Firecrawl, blocked-page retry (action)
  batches.ts           batch queries, start (budget pre-flight), approval, text-fix, blend, Mark used, versions
  pipeline.ts          research → brief → assets → art direction → concepts; render → review → auto fix → text check;
                       text-fix, cut-out, blend ("use node" actions)
  legacy.ts            purge the rows of the removed pipeline
  settings.ts          global settings: get/save/restore/history (keep 20), OpenRouter model catalogue
  comments.ts, budget.ts   budget: reserve/settle keep spendTotals; summary reads one document
  migrations.ts, previews.ts   one-time data moves (slimBatches, preview backfill); run by hand after deploy
  monitoring.ts        Sentry report action (for mutations, which can't fetch)
  probe.ts             internal image probe: one metered Sunburst call (spend kind "probe"); run from the admin API
  lib/                 settingsRegistry + defaults + specText (tunables, prompts, playbook), schemas (strict JSON),
                       compose (message formats), recipe, frame (safe zones), estimate, imaging, config, access,
                       provider clients, metering, sentry
src/
  App.tsx, main.tsx, pages/, features/ (batch/: BatchesPanel, ConceptCard, DraftCard, TextFixDialog, BlendDialog), components/ui/, lib/
tests/                 behavior tests (Vitest): price lint, safe zones, JSON repair, budget
scripts/
  gen-spec-text.py     makes convex/lib/specText.ts from the spec

Scripts

• npm run dev: starts the frontend and backend dev servers.
• npm run build: does a type check and a Vite build.
• npm run typecheck: does a type check of the app, Convex and the tests.
• npm test: runs the behavior tests in tests/ (Vitest, one run). The tests make no network calls and no paid calls. tests/budget.test.ts and tests/cost.test.ts use convex-test, an in-memory Convex backend.
• npm run deploy: deploys the backend and the static site to Convex production.
• python3 scripts/convex-usage.py: prints the Convex cost of each function for each call, from the prod execution log (read-only; needs CONVEX_DEPLOY_KEY in the environment).

Known limitations (MVP)

• Sunburst has no published price for each image. The image costs are estimates (Settings → Costs & budget). Check the Replicate bill.
• jimp cannot read WebP. The tool keeps a WebP candidate photo without a crop. It drops a WebP photo that needs a crop (but it keeps a WebP packshot without a crop).
• The claim filter compares URLs by host and path. A claim from a brand page that the search did not return is dropped, also if it is true.
• The text check and the draft review are vision models. They can miss errors. Use the text-fix tool for text that they miss.
• For successful Firecrawl/Replicate calls, the cost records use estimates. For OpenRouter, the cost records use the cost that the provider reports, when it is available.