How the builder works

Explanation

The MaShop builder turns one chat message into real changes on your own infrastructure. It writes files into your GitHub repository and runs SQL migrations against your Supabase database. There is no separate "generate then export" step. The same loop that answers you in chat is the loop that commits the code. This page explains that loop, the tools it calls, and where multi-step work happens, so the model's behavior stops feeling like a black box.

The orchestrator loop

Every message you send runs through one orchestration function. It builds a prompt from your message plus project context, then iterates. The hard cap is 8 turns per message. On each turn the builder streams a model response, collects any tool calls the model made, runs those tools, feeds the results back, and starts the next turn. When a turn produces no tool calls, the loop stops and you get the final reply.

The turn order is fixed:

1. Build the prompt: system instructions, your message, and a compact <store_info> block (project name, site type, item count, categories, currency, language) plus any saved preferences.
2. Call the model with the full tool catalog and tool_choice: "auto", streaming the text back to your chat as it arrives.
3. Accumulate the model's tool calls from the stream.
4. If there are no tool calls, stop. Otherwise run every requested tool in parallel.
5. Append each tool result as a tool message and go to the next turn.

Tools in a single turn run together, not one after another, through a Promise.all over the requested calls. So if the model asks to read three files at once, those three reads happen concurrently and the loop waits for all of them before the next turn.

Why the loop ends

The loop stops on the first of these conditions:

• Natural stop. The model returns text with no tool calls. This is the normal ending.
• Turn cap. The loop reaches 8 turns.
• Token budget. A budget tracker watches total tokens across all turns. The default budget is 200,000 tokens. The loop short-circuits once the running total reaches 90 percent of the budget, or after at least three continuations where the last two turns each added under 500 tokens (diminishing returns). When either fires, the loop ends and returns the text it had accumulated up to that point.

If the upstream call throws, the loop catches the error and returns whatever text it had, prefixed with the error message, so a failure mid-build still surfaces a reply instead of hanging.

Model routing by tier

You do not have to pick a model. With the Auto setting, a lightweight classifier reads your message and the project's file count and judges the blast radius of the request, then routes to one of three tiers:

Tier	What it means	Examples
simple	A cosmetic or single-spot change touching at most one file, with no new logic.	Color, copy edit, spacing, swapping an image, toggling a setting.
medium	A feature or multi-file change with logic.	A new validated form, a new section with logic, wiring a data source, a targeted bug fix.
complex	Whole-site or architectural work touching many files.	Generate or redesign a full site, new page flows like checkout or booking, cross-cutting refactors.

The classifier judges blast radius, not message length. "Rebuild my store" is complex even though it is three words; a long, detailed message about one button is simple. If the previous turn on this conversation failed (a build error or a tool failure), the router bumps the request up one tier so the retry runs on a stronger model. If the classifier call itself fails, a keyword heuristic picks the tier instead.

The tool suite

The model never edits your repo by writing prose. It calls typed tools, and the builder runs the handler behind each one. The catalog the model sees groups into three kinds of work.

Files and database (your repo, your Supabase)

Tool	What it does
scaffold_next_project	Initializes a complete Next.js 15 project (package.json, tsconfig, next.config, Tailwind, layout, Supabase client, README, and more) in your GitHub repo. It is the required first call on an empty repo, and it is idempotent: if package.json already exists it returns a skipped result.
read_file	Loads a file's current content and SHA from your repo. Content is capped near 200 KB.
create_or_update_file	Writes one file to your repo as a commit. Guarded by read-before-write (see below).
delete_file	Removes a file from your repo as a commit.
run_migration	Writes a versioned SQL file under supabase/migrations/ in your repo and runs the SQL against your Supabase database through the Management API.
upload_image	Uploads an image to your Supabase Storage. PNG, JPEG, WebP, or GIF, up to 10 MB.
install_package	Adds npm dependencies to your package.json; the install runs on the next deploy.
read_supabase_schema	Introspects your database (tables, columns, types, RLS policies) so the model builds against the real schema instead of guessing.

Generation and design

• generate_store_website generates or rebuilds the full site as Next.js TSX components.
• generate_store_with_seo does the same and runs SEO optimization in parallel; this is the preferred call for first-time creation.
• modify_store_section changes one section (header, hero, footer) without rebuilding the rest.
• update_store_design updates global design tokens (palette, typography, density).
• generate_image_assets commits original visuals (SVG logos, hero illustrations, icon sets) as code.
• crawl_website fetches a public URL you reference and extracts its palette, fonts, and layout so the model can match a look.

Data, SEO, preferences, and operations

• execute_store_action runs dashboard actions: create products, configure shipping, create coupons, add blog posts.
• optimize_seo sets meta tags, JSON-LD, canonical URLs, hreflang, and sitemap entries.
• answer_analytics answers questions over real store data (sales, orders, top products) with no extra model call.
• save_preference stores a brand rule or preference so future conversations honor it; see Memory.
• ask_clarification asks you a question when the request is ambiguous instead of guessing.
• auto_fix_code, maintenance_scan, and attach_custom_domain validate code, scan the site for issues, and wire a custom domain on Netlify; see Auto-fix and Custom domains.

It commits real files and runs real migrations

When the model generates a site, the builder commits the generated files to your GitHub repo and reports back how many files were committed and how many failed. A deploy then ships that committed code, not a placeholder. The model also creates pages and components file by file through create_or_update_file, each one landing as a commit you can see in your repo history and revert through Git.

Database changes are the same shape. run_migration commits the SQL to supabase/migrations/ in your repo for version control, then executes it against your Supabase database. So your schema changes are both applied and tracked in code.

Read-before-write

To stop the model from clobbering a file based on a guess, overwrites are guarded. Before create_or_update_file can overwrite an existing file, the model must have called read_file on that exact path earlier in the same conversation, and the SHA it saw must still match the current SHA. If it skips the read, the write is refused and the error tells the model to call read_file on that path first so it can base the edit on the file's actual current content. If the file changed since the read, the write is refused for a stale SHA and the model is told to read it again. Brand-new files have nothing to clobber, so they write without a prior read.

Migration safety

A SQL safety guard rejects destructive statements before any migration runs. Refused patterns include DROP DATABASE, DROP SCHEMA, DROP ROLE, DROP USER, ALTER DATABASE, truncates or deletes against auth.* and storage.*, and direct writes to pg_catalog tables. A refused migration comes back as a "SQL refused" message naming the forbidden pattern, and nothing runs. Migrations are also rate-limited and capped at 100 KB of SQL.

Multi-step tool calls

Most tools do their work in a single call. Two run their own internal loop because the task genuinely needs multiple steps with branching.

• Deployment. A deploy is not one action. The deployment handler runs an internal tool loop that checks prerequisites (credit balance, project status), validates the build, executes the deploy to Netlify, runs post-deploy health checks (HTTP status, response time, SSL, critical pages), and rolls back to the previous version if the health checks fail.
• Maintenance. A maintenance scan runs its own loop that scans pages for render errors, audits SEO (meta tags, Open Graph, structured data, sitemap), checks performance, and applies code fixes when it can.

These internal loops are bounded too. The deployment loop is capped at 6 iterations and the maintenance loop at 8; reaching the cap ends the loop with a "max iterations reached" error rather than looping forever. Netlify is the deployment target. Vercel is not a deploy target you drive from the builder. See Deploy overview.

What a single message can produce

Putting the loop together, one message like "add a coupon system" can, within its 8-turn budget, read the files it needs, write new components and a server route, run a migration that creates the coupon tables on your database, and commit every change to your repo, then return a short summary in chat. You own all of it: the code lives in your GitHub repo and the schema lives in your Supabase project. Next, see Prompting for how to phrase requests, and Versions for how to roll changes back.