How Prompting Works

When you type a prompt and press Enter, VoxelSite doesn't just forward your text to an AI model. It runs a structured pipeline that assembles the right context, selects the right strategy, and constrains the AI to produce reliable output.

This page explains what happens under the hood — useful for understanding why VoxelSite produces better results than a generic AI chat, and how to get the most from it.

The pipeline

Every prompt goes through five stages:

1. Action detection — what kind of task is this?
2. Context assembly — what does the AI need to know?
3. Budget management — how much fits in the AI's context window?
4. Generation — the AI produces output with real-time progress
5. Post-processing — files are written, CSS is compiled, quality is checked

Each stage is engineered to reduce waste, prevent errors, and produce consistent results.

Action detection

Not every prompt needs the same treatment. A typo fix and a full site creation are fundamentally different tasks — they need different instructions, different context, and different output budgets.

VoxelSite routes your prompt to a specialised action type based on how you triggered it:

Each action type carries its own instruction set, context profile, and output budget. A visual section edit gets a compact, focused prompt and a tight context window. A full site creation gets the complete instruction manual and maximum output budget.

This is why the same AI model produces more reliable results in VoxelSite than in a generic chat interface — it's not seeing the same thing every time.

Context assembly

Before the AI sees your prompt, VoxelSite builds a context package — a structured snapshot of everything relevant about your current site. This is the most important engineering decision in the entire product.

What goes into context

Not every action needs all of this. A section edit doesn't need the full image library. An inline code edit doesn't need form schemas. The action type determines which sections are assembled.

Priority tiers

Context sections are ranked into three priority tiers:

• Essential — always included regardless of budget: site info, design tokens, current page content, page structure
• Important — included when space allows: image library, form schemas, data files, navigation, footer
• Optional — included last: full compiled CSS, icon reference

If the budget is tight, optional sections are dropped first, then important, keeping essential information intact. This is why VoxelSite works well even with smaller AI models — it prioritises the information that matters most.

Conversation continuity

Multi-turn conversations are tracked as proper message exchanges. When you follow up with "make it darker" or "add another card", the AI sees your previous instructions and its own responses as structured context — not a flat text dump. This gives the model proper conversational awareness, so follow-up prompts don't need to re-explain what you've already established.

History is automatically trimmed to the most recent exchanges to stay within the context budget.

Budget management

Every AI model has a finite context window — the total amount of text it can process at once. A model with a 200K context window sounds enormous, but after the system prompt, your conversation history, and the output reservation, the space for site context is smaller than you'd think.

VoxelSite calculates the available budget automatically:

Available context = Model's context window
                  − System prompt (~18K tokens)
                  − Action prompt (~1-4K tokens)
                  − Output reservation (16-64K tokens)
                  − Conversation history
                  − Safety buffer

Action-specific budgets

For focused actions, VoxelSite caps the budget more aggressively. A single-file edit doesn't need 50,000 characters of context — a focused window produces faster, more precise results:

When the budget is capped, the progressive trimmer drops lowest-priority sections first. For a capped inline edit, this typically means the icon list, full CSS, and image library are dropped — leaving the essentials: design tokens, page content, and site structure.

What this means for you

• You never manage context manually. VoxelSite handles budgeting automatically based on the action type and model.
• Smaller models still work. The budget system gracefully degrades — if there's less space, lower-priority context is dropped, but essential information is always preserved.
• Focused actions are faster. Section edits and inline code edits deliberately use a smaller context window, which means quicker time-to-first-token from the AI.
• The logs show what happened. If you're curious about context composition for a specific request, check _studio/logs/ — every request logs which sections were included, which were trimmed, the total budget, and the percentage used.

System prompt engineering

The system prompt is the instruction manual the AI receives on every request. It defines the rules for code generation, design standards, architectural patterns, and quality expectations.

VoxelSite's system prompt isn't a paragraph of generic instructions — it's a structured document covering:

• Architecture rules — PHP partial structure, file organisation, how pages compose
• Design mandate — Typography hierarchy, colour theory, spacing rhythm, animation philosophy
• CSS strategy — Tailwind utility classes in HTML, design tokens in :root, no component classes in the stylesheet
• Data patterns — JSON data files, Schema.org markup, form handling
• Memory system — How to store and recall business facts, track confidence, handle rejected directions
• Design intelligence — How to track and reuse design decisions across sessions
• Quality guardrails — Accessibility, responsive behaviour, semantic HTML, no external dependencies

Action prompts

Each action type receives a supplementary action prompt that adds task-specific constraints on top of the system prompt. Some examples:

• Section edit — preserve design language, stay within existing Tailwind classes, maintain responsive breakpoints, modify only the target section
• Add section — generate one new section matching the site's existing design language, fonts, colours, and spacing rhythm
• Inline edit — scope control (modify only what was asked), pattern preservation (match existing code style), file-type-aware rules (different rules for PHP, CSS, JS, and data files)
• Edit page — use Site Memory for business facts, update Design Intelligence when making visual changes, sync data files when editing structured content
• Create site — full creative freedom, but within the architectural constraints
• Import site — interpret a reference website's design language and translate it into clean Tailwind CSS
• Restyle — transform the visual identity while keeping existing content intact
• AEO optimise — audit structured data, Schema.org markup, and AI discoverability endpoints

This layered approach means the same underlying AI model behaves differently depending on the task — focused and constrained for small edits, creative and expansive for new sites.

Customising the system prompt

Advanced users can view and edit the system prompt directly in the Code Editor. Your customisations are saved separately from the defaults in a dedicated custom_prompts/ directory, so VoxelSite updates never overwrite your changes. Reset to the default at any time with the reset button in the file tree.

Image library intelligence

VoxelSite ships with a built-in library of background textures, gradients, and gallery images. Each image filename encodes structured metadata — subject, mood, tone, contrast — that the AI reads to make appropriate visual selections.

For example, a background image might be tagged as warm · texture · earthy · light, while a gallery image might carry food · coffee · warm · high-contrast. When the AI builds your site or adds a section, it picks images that match the mood and tone you've established.

As you upload your own images, the AI gives them priority over library images. You can always replace library images with your own at any point.

Real-time progress

During generation, VoxelSite streams results in real-time. You see exactly what the AI is doing:

• Timer — elapsed time since generation started
• Current step — what phase the engine is in (reading, generating, writing, compiling)
• Token count — how much the AI has generated so far
• Stop button — cancel generation at any time

This applies everywhere: the chat, the visual editor, and the code editor's inline AI. All three use the same full-page overlay design — a centred status card with a backdrop that blocks the entire interface during generation. You're never left staring at a spinner wondering what's happening, and you can't accidentally interrupt a generation by clicking elsewhere.

Steps you'll see

Post-processing

After the AI finishes generating, VoxelSite runs several automated steps before showing the result:

1. File validation — paths are checked for safety (no directory traversal, no writes to system directories)
2. Auto-repair — common AI model mistakes are automatically fixed (CSS encoding issues, PHP escaping, structural errors)
3. Icon resolution — icon name aliases are normalized (e.g. home → house), unresolved icon names are logged, and the icon hydration script is ensured in the footer
4. Tailwind compilation — CSS utility classes used in the HTML are compiled into a clean stylesheet. This runs on a built-in PHP compiler — no Node.js or build tools needed.
5. Snapshot capture — a before/after revision is created so you can undo any change
6. Page registry sync — the site map and page structure are updated
7. SEO regeneration — structured data files (schema.php, llms.txt, robots.txt, mcp.php) are updated to reflect the new content

These steps run automatically. You see the result in the live preview within seconds of generation completing.

Why this matters

Most AI website builders send your prompt to a model with minimal context and hope for the best. VoxelSite's approach is different:

• Action-aware routing ensures the AI gets the right instructions for the specific task — not a one-size-fits-all prompt
• Structured context gives the AI complete awareness of your existing site without overwhelming it
• Budget management keeps generation fast and focused, even on large sites with many pages
• Memory and design intelligence maintain consistency across sessions — the AI doesn't forget what it learned about your business or your design preferences
• Data dependency tracking prevents the silent breakage that happens when one file changes but its dependents don't
• Post-processing catches and fixes common AI output issues automatically

The result is a system where the AI produces reliable, production-quality output — not because the AI model is inherently better, but because the engineering around it is purpose-built for website generation.

Related

• The AI Engine — Technical overview of the generation pipeline
• Prompting Basics — How to write effective prompts
• Visual Editor — Click-and-edit with AI-powered section editing
• Code Editor — Inline AI editing with Cmd+K
• Design System — How colours, typography, and tokens work