Leon4gr45/builder

1# Working with AI2 3**Get the best results from AI when building your websites.**4 5This guide covers how to interact with AI effectively, understand its capabilities, and make the most of OSW Studio's dual-mode system.6 7---8 9## Chat Mode vs Code Mode10 11OSW Studio has two modes that control what AI can do to your project:12 13### 💬 Chat Mode (Read-Only)14 15**Use when you want to explore without making changes.**16 17In Chat mode, the AI is limited to read-only shell commands. It can read files and analyze your project structure, but cannot write, edit, or delete anything.18 19AI can:20- Answer questions about your code21- Explain how things work22- Suggest improvements23- Help you plan features24- Review code structure25- Show you how it understands your project26 27AI cannot:28- Create or modify files29- Delete anything30- Make changes to your project31 32**Perfect for:**33- Learning about your codebase34- Planning before building35- Getting second opinions36- Understanding unfamiliar code37- Seeing how the AI interprets your project structure38 39**Pro tip**: If you're unsure how to proceed, start with Chat mode to discuss the project with the AI and see how it would approach the work.40 41**Example prompts:**42```43How does the navigation menu work?44```45```46What would be the best way to add a blog section?47```48```49Can you explain this JavaScript function?50```51 52### 🔧 Code Mode (Full Access)53 54**Use when you want AI to build and modify your project.**55 56In Code mode, the AI has full access to all shell commands. It can create, edit, delete, and restructure files as needed.57 58AI can:59- Create new files and folders60- Edit existing code61- Delete files62- Restructure your project63- Implement complete features64- Fix bugs65- One-shot build entire multi-page websites (though smaller, focused tasks are generally more consistent)66 67**Perfect for:**68- Building new features69- Making design changes70- Fixing bugs71- Refactoring code72- Implementing your plans73- Creating complete websites from scratch74 75**Example prompts:**76```77Add a contact form to the contact page78```79```80Make the header sticky when scrolling81```82```83Change the color scheme to dark mode84```85 86### Switching Modes87 88Toggle between modes using the switch at the top of the chat panel.89 90**Pro tip**: Plan in Chat Mode, build in Code Mode.91 92---93 94## Working with Files95 96### Creating Files97 98**Let AI create files for you:**99 100```101Create a new file called contact.html with a contact form102```103 104**Or do it manually:**1051. Right-click in File Explorer1062. Select **New File**1073. Enter filename1084. Press Enter109 110### Editing Files111 112**With AI:**113```114Update the CSS to make the header sticky115```116 117**Manually:**1181. Click file in File Explorer1192. Edit in Code Editor1203. Save with `Cmd/Ctrl+S`121 122### Deleting Files123 124**With AI:**125```126Delete the unused about.html file127```128 129**Manually:**1301. Right-click file in File Explorer1312. Select **Delete**1323. Confirm133 134---135 136## Writing Good Prompts137 138### Be Specific139 140❌ **Vague**: "Make it look better"141✅ **Specific**: "Add a gradient background from #667eea to #764ba2 in the hero section"142 143❌ **Vague**: "Add a form"144✅ **Specific**: "Add a contact form with fields for name, email, and message, with a blue submit button"145 146### One Thing at a Time147 148Break complex requests into steps:149 150❌ **Too much**:151```152Create a blog with posts, categories, tags, search, pagination,153comments, and social sharing154```155 156✅ **Step by step**:157```1581. First: Create a blog page with a list of 3 sample posts1592. Then: Add categories to organize the posts1603. Then: Add a search feature161... and so on162```163 164### Provide Context165 166Help AI understand your goals:167 168❌ **No context**: "Add a section"169 170✅ **With context**:171```172Add a testimonials section below the features section.173Show 3 testimonials in a row with photos, names, and quotes.174Match the existing blue color scheme.175```176 177### Show Examples178 179Describe what you want to see:180 181```182Add a pricing table with 3 tiers: Basic ($9/mo), Pro ($29/mo),183and Enterprise ($99/mo). Each tier should show 5 features184and have a "Get Started" button. Make the Pro tier highlighted.185```186 187### Ask for Explanations188 189If you want to learn:190 191```192Add smooth scrolling to the page, and explain how it works193```194 195---196 197## Common Tasks198 199### Building Features200 201```202Add a hamburger menu for mobile screens203```204 205```206Create a photo gallery with lightbox effect207```208 209```210Add a newsletter signup form that's centered on the page211```212 213### Styling & Design214 215```216Change the font to Inter throughout the site217```218 219```220Make the hero section full-height with centered content221```222 223```224Add hover effects to all buttons with a slight scale animation225```226 227### Fixing Issues228 229```230The mobile menu isn't closing when I click a link. Can you fix that?231```232 233```234Images are overflowing their containers on mobile. Fix the sizing.235```236 237```238The contact form isn't visually aligned. Center it properly.239```240 241### Modifying Content242 243```244Update the hero heading to say "Welcome to My Portfolio"245```246 247```248Add 2 more project cards to the projects section249```250 251```252Change all instances of "Company" to "Studio"253```254 255---256 257## Understanding AI Responses258 259### Tool Execution260 261When AI works in Code Mode, all file operations run through a single `shell` tool. You'll see commands like:262 263**Creating files:**264```265🔧 shell: cat > index.html << 'EOF' ...266✅ Created index.html267```268 269**Editing files:**270```271🔧 shell: sed -i 's/old/new/' styles.css272✅ Updated styles.css273```274or for larger edits:275```276🔧 shell: ss /styles.css << 'EOF'277search===replace278EOF279```280 281**Reading files:**282```283🔧 shell: cat index.html284📄 Read file contents285```286 287**Checking compilation:**288```289🔧 shell: build290✅ Build successful — 0 errors291```292 293### Status Updates294 295AI will tell you what it's doing:296 297- "I'll create a new navigation menu..."298- "Updating the CSS to make buttons larger..."299- "I've added the contact form. Here's how it works..."300 301### Explanations302 303AI often explains its changes. Read these to learn:304 305> "I've added flexbox to center the content. Flexbox is a CSS layout306> method that makes it easy to align items..."307 308---309 310## Cost Tracking311 312OSW Studio tracks how much you're spending on AI calls.313 314> **Note**: Accurate cost tracking currently only works with **OpenRouter**. Other providers may show no cost data or inaccurate values.315 316### Viewing Costs317 318Click the **💰** icon in the settings to see:319- Cost per message320- Total session cost321- Model pricing rates322 323### Saving Money324 325**Use efficient models:**326- `gpt-4o-mini` - Good balance of cost and quality327- `claude-3-5-haiku` - Fast and affordable328- Avoid expensive models for simple tasks329 330**Be concise:**331- One clear request beats multiple vague ones332- Smaller context = lower cost333 334**Use Chat Mode for questions:**335- Read-only mode uses fewer tokens336- Save Code Mode for actual changes337 338---339 340## Best Practices341 342### ✅ Do's343 344**DO start simple:**345Get basic structure working first, then add complexity346 347**DO test as you go:**348Check the preview after each change349 350**DO ask for explanations:**351Learning helps you write better prompts352 353**DO use templates:**354Starting from a template saves time and tokens355 356**DO break big tasks into steps:**357Incremental progress is more reliable358 359### ❌ Don'ts360 361**DON'T ask for everything at once:**362Complex multi-feature requests often fail363 364**DON'T ignore errors:**365If something breaks, ask AI to fix it before continuing366 367**DON'T assume AI remembers:**368Reference earlier work explicitly if needed369 370**DON'T keep working on errors:**371Stop and fix issues when they appear372 373---374 375## Examples: Good vs Bad Prompts376 377### Example 1: Adding a Feature378 379❌ **Bad:**380```381make a contact page382```383 384✅ **Good:**385```386Create a contact page with:387- Page title "Get In Touch"388- Contact form (name, email, message fields)389- Submit button in blue390- Add to navigation menu391```392 393### Example 2: Styling394 395❌ **Bad:**396```397better colors398```399 400✅ **Good:**401```402Change color scheme:403- Primary: #3B82F6 (blue)404- Secondary: #8B5CF6 (purple)405- Background: #F9FAFB (light gray)406Update buttons, links, and headings to use these colors407```408 409### Example 3: Fixing Issues410 411❌ **Bad:**412```413it's broken414```415 416✅ **Good:**417```418The mobile menu isn't working. When I click the hamburger icon,419nothing happens. Can you fix the JavaScript?420```421 422---423 424## Server Context (Server Mode Only)425 426In Server Mode, the AI can understand your published deployment's backend features when you select a deployment from the dropdown in the workspace header.427 428### What the AI Knows429 430When a deployment is selected, the AI has access to:431- **Edge Functions** - Available API endpoints432- **Database Schema** - Tables, columns, and types433- **Server Functions** - Reusable helper code434- **Scheduled Functions** - Cron schedules and linked functions435- **Secrets** - Available secret names (not values)436 437### Example Prompts438 439```440What edge functions are available?441```442 443```444Create an endpoint to fetch all users from the database445```446 447```448I need to use the STRIPE_KEY secret in a payment function449```450 451```452Show me the current database schema453```454 455```456Set up a scheduled function to clean up old records every night at 3am457```458 459### How It Works460 461OSW Studio mounts a `/.server/` hidden folder containing JSON files with your deployment's backend context. The LLM reads these to understand what exists and writes to them to extend them.462 463See **[Backend → AI Integration](?doc=backend-features#ai-integration)** for more details.464 465---466 467## Visual Context & Control468 469### Focus Tool470 471Click the **crosshair** icon in the preview toolbar, then click any element to attach it as context to your next message. The AI receives the element's HTML, path, and surrounding structure, so you can say "make this bigger" instead of describing what you mean.472 473### Semantic Blocks474 475Open the **Blocks** palette in the preview toolbar and drag any of the 36 blocks (hero, pricing, gallery, contact form, etc.) onto the preview at the position you want. The AI writes code that integrates with your existing project's style — blocks are specifications, not pre-built snippets.476 477### Image Attachments478 479Drop images into the chat input to include them as context. Works with any vision-capable model — the model selector shows a **Vision** badge for supported models.480 481### Pause, Continue, Retry482 483- **Stop** - Click Stop during generation to halt the AI immediately.484- **Continue** - If the AI stops because of an API error or timeout, Continue resumes with feedback about what went wrong.485- **Retry** - Every user message has a Retry button that rewinds to the checkpoint before that message and re-runs it.486 487---488 489## Advanced Tips490 491### Reference Specific Files492 493```494In styles.css, change the button padding to 12px 24px495```496 497### Request Multiple Variations498 499```500Show me 3 different color schemes for the hero section501```502 503### Ask for Best Practices504 505```506Is this the best way to structure my HTML for SEO?507What improvements would you suggest?508```509 510### Combine Changes511 512```513Make the header sticky AND add a shadow when scrolling514```515 516### Request Cleanup517 518```519Remove any unused CSS and organize the file by sections520```521 522---523 524## Troubleshooting525 526### AI Isn't Understanding527 528- Be more specific about what you want529- Break the request into smaller parts530- Provide visual examples or references531 532### Changes Aren't Showing533 534- Check if you're in Code Mode (not Chat Mode)535- Refresh the preview536- Check for JavaScript errors in browser console537 538### Code Looks Wrong539 540```541This doesn't look right. Can you review and fix any issues?542```543 544### Want to Undo545 546- Use checkpoints to restore earlier versions547- Ask AI to revert specific changes548 549```550Undo the last change you made to the CSS551```552 553---554 555**Next Steps:**556 557- **[Templates](?doc=templates)** - Start faster with templates558- **[Skills](?doc=skills)** - Teach AI your preferences559- **[FAQ](?doc=faq)** - Common questions answered560