@itayzrihan/create-box-app 1.0.0 → 1.0.2

package/bin/create-box-app.js

@@ -69,7 +69,9 @@ function copyDir(src, dest) {
 
   files.forEach(file => {
     const srcPath = path.join(src, file);
-    const destPath = path.join(dest, file);
+    // Rename _gitignore back to .gitignore (npm ignores .gitignore files)
+    const destFile = file === '_gitignore' ? '.gitignore' : file;
+    const destPath = path.join(dest, destFile);
     const stat = fs.statSync(srcPath);
 
     if (stat.isDirectory()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itayzrihan/create-box-app",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Create a new BOX Framework application with one command",
   "main": "bin/create-box-app.js",
   "bin": {

package/template/.vscode/extensions.json

@@ -0,0 +1,13 @@
+{
+  "recommendations": [
+    "bradlc.vscode-tailwindcss",
+    "formulahendry.auto-rename-tag",
+    "formulahendry.auto-close-tag",
+    "christian-kohler.path-intellisense",
+    "pranaygp.vscode-css-peek",
+    "zignd.html-css-class-completion",
+    "ecmel.vscode-html-css",
+    "ritwickdey.liveserver"
+  ],
+  "unwantedRecommendations": []
+}

package/template/.vscode/launch.json

@@ -0,0 +1,25 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "BOX Dev Server",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "cwd": "${workspaceFolder}",
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"]
+    },
+    {
+      "name": "BOX Production Server",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/dist/server.js",
+      "cwd": "${workspaceFolder}",
+      "preLaunchTask": "npm: build",
+      "console": "integratedTerminal",
+      "skipFiles": ["<node_internals>/**"]
+    }
+  ]
+}

package/template/.vscode/settings.json

@@ -1,11 +1,44 @@
 {
+  // Associate .box files with HTML for syntax highlighting
   "files.associations": {
     "*.box": "html"
   },
+  
+  // Enable Emmet in .box files for fast HTML typing
   "emmet.includeLanguages": {
     "box": "html"
   },
+  
+  // Enable autocomplete in strings (useful for box-bind attributes)
   "editor.quickSuggestions": {
     "strings": true
+  },
+  
+  // Format on save for consistent code style
+  "editor.formatOnSave": true,
+  
+  // Use 2 spaces for indentation (HTML/CSS/JS standard)
+  "editor.tabSize": 2,
+  
+  // Wrap long lines for readability
+  "editor.wordWrap": "on",
+  
+  // Show matching brackets clearly
+  "editor.bracketPairColorization.enabled": true,
+  
+  // Auto-close HTML tags
+  "html.autoClosingTags": true,
+  
+  // Show color decorators in CSS
+  "css.colorDecorators": true,
+  
+  // Exclude build artifacts from explorer and search
+  "files.exclude": {
+    "**/node_modules": true,
+    "**/dist": false
+  },
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/dist": true
   }
 }

package/template/README.md

@@ -1,6 +1,11 @@
-# BOX Project
+# 🚀 BOX Project
 
-Auto-generated BOX Framework project. Edit your `.box` files in the `src/` folder and run `npm run dev` to see live updates!
+Welcome to your BOX Framework application! This is a fully functional starter template with examples showing how to:
+
+- Build **reactive components** with state management
+- Create **API endpoints** (backend routes)
+- Use **component composition** with `<include />`
+- Develop with **instant hot-reload** (HMR)
 
 ## Quick Start
 
@@ -9,4 +14,148 @@ npm install
 npm run dev
 ```
 
-Visit http://localhost:3000
+Visit **http://localhost:3000** and start building!
+
+## 📁 Project Structure
+
+```
+my-box-app/
+├── .vscode/
+│   ├── settings.json     # IDE settings (.box → HTML highlighting)
+│   ├── extensions.json   # Recommended VS Code extensions
+│   └── launch.json       # Debug configurations
+├── src/
+│   ├── main.box          # App entry point
+│   ├── counter.box       # State management example
+│   ├── api-demo.box      # API integration example
+│   ├── learning-guide.box # Complete framework guide
+│   ├── api+hello.box     # GET /api/hello
+│   └── api+echo.box      # POST /api/echo
+├── assets/               # Static files (images, fonts)
+├── dist/                 # Build output (auto-generated)
+├── package.json
+└── README.md
+```
+
+## 🎯 Development Workflow
+
+1. Edit `.box` files in `src/`
+2. Save and browser auto-refreshes
+3. See your changes instantly (no build step needed!)
+4. Use `npm run build` for production
+
+## 📚 Key Concepts
+
+### .box File Structure
+
+Every `.box` file has three sections:
+
+```html
+<style>
+  /* Scoped CSS - won't leak to other components */
+  .my-class { color: blue; }
+</style>
+
+<template>
+  <!-- HTML with special attributes -->
+  <div class="my-class">
+    <span box-bind="count">0</span>
+    <include src="./other.box" />
+  </div>
+</template>
+
+<script>
+  // Vanilla JavaScript
+  Box.state.count = 42;
+</script>
+```
+
+### Reactive State
+
+```javascript
+// Set state (auto-updates DOM elements with box-bind="count")
+Box.state.count = 0;
+Box.state.count++;  // UI updates automatically!
+
+// Listen for changes
+Box.on('count:changed', (value) => console.log(value));
+
+// Emit custom events
+Box.emit('user:login', userData);
+```
+
+### API Endpoints
+
+Files named `api+name.box` become routes:
+
+| File | Route |
+|------|-------|
+| `api+hello.box` | `GET /api/hello` |
+| `api+echo.box` | `POST /api/echo` |
+| `api+users+list.box` | `GET /api/users/list` |
+
+## 🛠 Available Scripts
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server with HMR |
+| `npm run build` | Build for production |
+| `npm run start` | Run production server |
+| `npm run preview` | Build and run production |
+
+## 🔌 VS Code Setup
+
+Your project comes pre-configured with:
+
+- ✅ `.box` files recognized as HTML (syntax highlighting)
+- ✅ Emmet support for fast HTML typing
+- ✅ Recommended extensions for better DX
+- ✅ Debug configurations ready to use
+
+**Open the project folder in VS Code** to activate all settings.
+
+## 🤖 AI-Friendly Code
+
+Copy any `.box` file into Claude, ChatGPT, or your favorite AI assistant.
+The pure HTML/CSS/JS structure makes it perfect for AI-assisted development.
+
+### Prompt Template
+
+```
+I'm using BOX Framework. Here's my component:
+
+[paste your .box file]
+
+Help me [describe what you want to do].
+
+Note: BOX uses:
+- Box.state for reactive state
+- box-bind="property" for two-way binding
+- <include src="./file.box" /> for composition
+- api+name.box files for backend endpoints
+```
+
+## 📦 Production Build
+
+```bash
+npm run build
+```
+
+This generates `dist/` containing:
+- `index.html` - Compiled frontend
+- `style.css` - Minified styles  
+- `app.js` - Minified JavaScript
+- `server.js` - Node.js backend server
+
+Deploy `dist/` to any Node.js hosting (Vercel, Railway, Render, etc.)
+
+## 📚 Learn More
+
+- 📖 [BOX Framework GitHub](https://github.com/itayzrihan/box)
+- 📦 [npm: @itayzrihan/box-framework](https://www.npmjs.com/package/@itayzrihan/box-framework)
+
+Check the example components in `src/` - they're heavily commented with tips!
+
+---
+
+**Happy Vibe Coding! 🎉**

package/template/_gitignore

@@ -0,0 +1,27 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Logs
+*.log
+npm-debug.log*
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE (keep .vscode for settings)
+.idea/
+*.swp
+*.swo
+
+# Environment variables (if you add any)
+.env
+.env.local
+.env.*.local
+
+# Debug
+*.pid
+*.seed

package/template/assets/README.md

@@ -0,0 +1,26 @@
+# Assets Folder
+
+Put your static files here:
+
+- Images (`.png`, `.jpg`, `.svg`, `.gif`, `.webp`)
+- Fonts (`.woff`, `.woff2`, `.ttf`)
+- Icons (`favicon.ico`)
+- Any other static assets
+
+These files will be copied to `dist/assets/` during build.
+
+## Usage in .box files
+
+Reference assets with relative paths:
+
+```html
+<img src="./assets/logo.png" alt="Logo" />
+```
+
+Or in CSS:
+
+```css
+.hero {
+  background-image: url('./assets/hero-bg.jpg');
+}
+```

package/template/package.json

@@ -3,17 +3,19 @@
   "version": "1.0.0",
   "description": "A BOX Framework application",
   "scripts": {
-    "build": "box build",
     "dev": "box dev",
-    "start": "node dist/server.js"
+    "build": "box build",
+    "start": "node dist/server.js",
+    "preview": "npm run build && npm run start"
   },
   "keywords": [
     "box",
-    "framework"
+    "framework",
+    "vibe-coding"
   ],
   "author": "",
   "license": "MIT",
-  "devDependencies": {
-    "box-framework": "^1.0.0"
+  "dependencies": {
+    "@itayzrihan/box-framework": "^1.0.0"
   }
 }

package/template/src/api+echo.box

@@ -0,0 +1,40 @@
+/*
+ * BOX API ENDPOINT: POST /api/echo
+ * =================================
+ * 
+ * Example POST endpoint that echoes back what you send.
+ * Test with:
+ * 
+ * fetch('/api/echo', {
+ *   method: 'POST',
+ *   headers: { 'Content-Type': 'application/json' },
+ *   body: JSON.stringify({ name: 'Alice', message: 'Hello!' })
+ * })
+ */
+
+/* BOX_CONFIG: { "method": "POST", "auth": false } */
+
+export default async (req, res, ctx) => {
+  try {
+    // req.body contains the parsed JSON body
+    const { name, message } = req.body || {};
+    
+    if (!name || !message) {
+      return { 
+        status: 400, 
+        error: "Missing required fields: name, message" 
+      };
+    }
+    
+    return { 
+      status: 200, 
+      data: {
+        received: { name, message },
+        echo: `${name} says: "${message}"`,
+        timestamp: new Date().toISOString()
+      }
+    };
+  } catch (err) {
+    return { status: 500, error: err.message || "Server error" };
+  }
+};

package/template/src/api+hello.box

@@ -1,15 +1,41 @@
+/*
+ * BOX API ENDPOINT: /api/hello
+ * =============================
+ * 
+ * This file creates a GET endpoint at /api/hello
+ * 
+ * FILE NAMING CONVENTION:
+ * - api+name.box → GET /api/name
+ * - api+users+list.box → GET /api/users/list
+ * - Use BOX_CONFIG to change HTTP method (GET, POST, PUT, DELETE)
+ * 
+ * AVAILABLE IN HANDLER:
+ * - req.body: Request body (for POST/PUT)
+ * - req.query: URL query parameters (?name=value)
+ * - req.headers: Request headers
+ * - ctx.env: Environment variables (process.env)
+ * 
+ * RETURN FORMAT:
+ * - { status: 200, data: {...} } → JSON response
+ * - { status: 404, error: "Not found" } → Error response
+ */
+
 /* BOX_CONFIG: { "method": "GET", "auth": false } */
 
-export default async (req, res, context) => {
+export default async (req, res, ctx) => {
   try {
+    // Example: Access query parameters
+    // const name = req.query.name || 'World';
+    
     const greeting = {
       message: "Hello from BOX API!",
       timestamp: new Date().toISOString(),
-      framework: "BOX Framework v1.0.0"
+      framework: "BOX Framework v1.0.0",
+      tip: "Edit src/api+hello.box to customize this endpoint"
     };
     
     return { status: 200, data: greeting };
   } catch (err) {
-    return { status: 500, error: "Server error" };
+    return { status: 500, error: err.message || "Server error" };
   }
 };

package/template/src/api-demo.box

@@ -0,0 +1,79 @@
+<style>
+  /* API INTEGRATION COMPONENT
+     This component shows how to fetch data from BOX API endpoints */
+  
+  .api-demo {
+    padding: 2rem;
+    background: #f8f9fa;
+    border-radius: 12px;
+    border-left: 4px solid #667eea;
+  }
+
+  .api-demo h3 {
+    margin-top: 0;
+    color: #667eea;
+  }
+
+  .api-response {
+    background: white;
+    padding: 1rem;
+    border-radius: 8px;
+    margin-top: 1rem;
+    font-family: 'Courier New', monospace;
+    font-size: 13px;
+    overflow-x: auto;
+  }
+
+  .loading {
+    color: #667eea;
+    font-style: italic;
+  }
+
+  .error {
+    color: #e74c3c;
+  }
+
+  .success {
+    color: #27ae60;
+  }
+</style>
+
+<template>
+  <div class="api-demo">
+    <h3>📡 API Call Example</h3>
+    <p>Click below to fetch data from your BOX API endpoint:</p>
+    <button id="fetchBtn" style="padding: 0.5rem 1rem; cursor: pointer;">
+      Fetch from /api/hello
+    </button>
+    <div id="response" class="api-response loading">
+      Click the button to see the response...
+    </div>
+  </div>
+</template>
+
+<script>
+  /* CALLING BOX APIS: BOX automatically generates API routes
+     from files named api+name.box
+     So api+hello.box → GET /api/hello */
+  
+  const fetchBtn = document.querySelector('#fetchBtn');
+  const responseDiv = document.querySelector('#response');
+
+  fetchBtn.addEventListener('click', async () => {
+    responseDiv.className = 'api-response loading';
+    responseDiv.textContent = 'Loading...';
+
+    try {
+      /* FETCH WITH FULL URL: In development (http://localhost:3000)
+         and production, all API calls are relative to the app root */
+      const response = await fetch('/api/hello');
+      const data = await response.json();
+
+      responseDiv.className = 'api-response success';
+      responseDiv.textContent = JSON.stringify(data, null, 2);
+    } catch (error) {
+      responseDiv.className = 'api-response error';
+      responseDiv.textContent = `Error: ${error.message}`;
+    }
+  });
+</script>

package/template/src/counter.box

@@ -0,0 +1,136 @@
+<style>
+  /* BOX Scoping: Each component's styles are automatically scoped
+     with a data-box attribute, preventing CSS collisions across your app */
+  .counter {
+    padding: 2rem;
+    background: white;
+    border-radius: 12px;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+    text-align: center;
+    max-width: 400px;
+  }
+
+  .counter h2 {
+    color: #667eea;
+    margin: 0 0 1.5rem 0;
+    font-size: 24px;
+  }
+
+  .counter-display {
+    font-size: 48px;
+    font-weight: bold;
+    color: #764ba2;
+    margin: 2rem 0;
+    font-family: 'Courier New', monospace;
+  }
+
+  .counter-controls {
+    display: flex;
+    gap: 1rem;
+    justify-content: center;
+    flex-wrap: wrap;
+  }
+
+  .btn {
+    padding: 0.75rem 1.5rem;
+    font-size: 16px;
+    border: none;
+    border-radius: 8px;
+    cursor: pointer;
+    font-weight: 600;
+    transition: all 0.3s ease;
+  }
+
+  .btn-decrease {
+    background: #ff6b6b;
+    color: white;
+  }
+
+  .btn-decrease:hover {
+    background: #ee5a52;
+    transform: translateY(-2px);
+  }
+
+  .btn-increase {
+    background: #667eea;
+    color: white;
+  }
+
+  .btn-increase:hover {
+    background: #5a67d8;
+    transform: translateY(-2px);
+  }
+
+  .btn-reset {
+    background: #95a5a6;
+    color: white;
+  }
+
+  .btn-reset:hover {
+    background: #7f8c8d;
+    transform: translateY(-2px);
+  }
+
+  .counter-note {
+    font-size: 12px;
+    color: #7f8c8d;
+    margin-top: 1.5rem;
+    line-height: 1.6;
+  }
+</style>
+
+<template>
+  <div class="counter">
+    <h2>Counter Demo</h2>
+    <div class="counter-display" box-bind="count">0</div>
+    
+    <div class="counter-controls">
+      <button class="btn btn-decrease">− Decrease</button>
+      <button class="btn btn-increase">+ Increase</button>
+      <button class="btn btn-reset">⟲ Reset</button>
+    </div>
+
+    <div class="counter-note">
+      💡 <strong>Vibe Coding Tip:</strong> This counter demonstrates two-way binding.
+      The <code>box-bind="count"</code> attribute keeps the DOM in sync with
+      <code>Box.state.count</code> automatically. Change state, see the UI update instantly!
+    </div>
+  </div>
+</template>
+
+<script>
+  /* REACTIVE STATE: Box.state uses JavaScript Proxy for reactivity
+     Any property you add to Box.state automatically updates the DOM
+     where it's referenced with box-bind="propertyName" */
+  
+  Box.state.count = 0;
+
+  /* EVENT HANDLING: Query selectors work just like vanilla JS.
+     BOX components are scoped, so event handlers won't collide */
+  
+  const decreaseBtn = document.querySelector('.btn-decrease');
+  const increaseBtn = document.querySelector('.btn-increase');
+  const resetBtn = document.querySelector('.btn-reset');
+
+  decreaseBtn.addEventListener('click', () => {
+    Box.state.count--;
+    Box.emit('count:changed', Box.state.count);
+  });
+
+  increaseBtn.addEventListener('click', () => {
+    Box.state.count++;
+    Box.emit('count:changed', Box.state.count);
+  });
+
+  resetBtn.addEventListener('click', () => {
+    Box.state.count = 0;
+    Box.emit('count:changed', Box.state.count);
+  });
+
+  /* LIFECYCLE: Components run their script when they load.
+     Use Box.on() to listen for custom events or state changes */
+  
+  Box.on('count:changed', (newCount) => {
+    console.log(`Count is now: ${newCount}`);
+  });
+</script>

package/template/src/learning-guide.box

@@ -0,0 +1,208 @@
+<style>
+  .learning-guide {
+    max-width: 900px;
+    margin: 0 auto;
+    padding: 2rem;
+    background: #fafafa;
+    border-radius: 12px;
+    line-height: 1.8;
+  }
+
+  .learning-guide h2 {
+    color: #667eea;
+    margin-top: 2rem;
+  }
+
+  .learning-guide h3 {
+    color: #764ba2;
+    margin-top: 1.5rem;
+  }
+
+  .learning-guide code {
+    background: #f0f0f0;
+    padding: 0.25rem 0.5rem;
+    border-radius: 4px;
+    font-family: 'Courier New', monospace;
+    color: #e74c3c;
+  }
+
+  .tip-box {
+    background: #e8f4f8;
+    border-left: 4px solid #667eea;
+    padding: 1rem;
+    margin: 1rem 0;
+    border-radius: 4px;
+  }
+
+  .tip-box strong {
+    color: #667eea;
+  }
+
+  .code-block {
+    background: #2c3e50;
+    color: #ecf0f1;
+    padding: 1rem;
+    border-radius: 8px;
+    overflow-x: auto;
+    margin: 1rem 0;
+    font-family: 'Courier New', monospace;
+    font-size: 13px;
+  }
+</style>
+
+<template>
+  <div class="learning-guide">
+    <h1>🎓 Vibe Coding Guide for BOX Framework</h1>
+
+    <p>
+      Welcome! This template shows you how to build amazing web apps with BOX Framework.
+      BOX is all about <strong>zero dependencies</strong>, <strong>component-driven development</strong>,
+      and <strong>AI-friendly code</strong>.
+    </p>
+
+    <h2>🏗️ Project Structure</h2>
+    <p>Your app is organized in the <code>src/</code> folder:</p>
+    <ul>
+      <li><code>main.box</code> - Your app's entry point</li>
+      <li><code>welcome.box</code> - The beautiful welcome screen</li>
+      <li><code>counter.box</code> - Example: Interactive state management</li>
+      <li><code>api-demo.box</code> - Example: API integration</li>
+      <li><code>api+hello.box</code> - Backend API endpoint</li>
+    </ul>
+
+    <h2>📝 Understanding .box Files</h2>
+    <p>Each <code>.box</code> file is a complete component with three sections:</p>
+
+    <h3>1. &lt;style&gt; - Scoped CSS</h3>
+    <div class="tip-box">
+      <strong>💡 Vibe Tip:</strong> Your styles are automatically scoped!
+      BOX adds a unique <code>data-box</code> attribute to prevent collisions.
+      Write CSS naturally without worrying about class name conflicts.
+    </div>
+
+    <h3>2. &lt;template&gt; - HTML Structure</h3>
+    <p>Use standard HTML with special BOX attributes:</p>
+    <ul>
+      <li><code>box-bind="propertyName"</code> - Two-way binding with state</li>
+      <li><code>&lt;include src="./other.box" /&gt;</code> - Nest components</li>
+    </ul>
+
+    <div class="tip-box">
+      <strong>💡 Vibe Tip:</strong> <code>box-bind</code> automatically syncs your component
+      with <code>Box.state</code>. Change state, see the UI update instantly!
+    </div>
+
+    <h3>3. &lt;script&gt; - Component Logic</h3>
+    <p>Vanilla JavaScript! No special syntax required.</p>
+
+    <h2>⚡ Key BOX Concepts</h2>
+
+    <h3>Reactive State</h3>
+    <div class="code-block">Box.state.myValue = 'hello';
+Box.state.counter = 0;
+
+// Any property you add automatically updates the DOM
+Box.state.counter++; // Updates all box-bind="counter" elements</div>
+
+    <div class="tip-box">
+      <strong>💡 Vibe Tip:</strong> BOX uses JavaScript Proxy for reactivity.
+      It's simple, no virtual DOM, and super performant.
+    </div>
+
+    <h3>Event Handling</h3>
+    <p>Use vanilla DOM queries and event listeners:</p>
+    <div class="code-block">const btn = document.querySelector('.my-button');
+btn.addEventListener('click', () => {
+  Box.state.count++;
+});</div>
+
+    <h3>Emitting Custom Events</h3>
+    <div class="code-block">// In one component:
+Box.emit('user:logged-in', userData);
+
+// In another component:
+Box.on('user:logged-in', (data) => {
+  console.log('User logged in:', data);
+});</div>
+
+    <h2>🔌 API Endpoints</h2>
+    <p>Files named <code>api+name.box</code> become API routes:</p>
+    <ul>
+      <li><code>api+hello.box</code> → <code>GET /api/hello</code></li>
+      <li><code>api+users.box</code> → <code>GET /api/users</code></li>
+      <li><code>api+post+create.box</code> → <code>POST /api/post/create</code></li>
+    </ul>
+
+    <h3>API Box Structure</h3>
+    <div class="code-block">/* BOX_CONFIG: { "method": "POST", "auth": false } */
+
+export default async (req, res, context) => {
+  try {
+    const result = { success: true, data: req.body };
+    return { status: 200, data: result };
+  } catch (err) {
+    return { status: 500, error: err.message };
+  }
+};</div>
+
+    <div class="tip-box">
+      <strong>💡 Vibe Tip:</strong> You write plain async functions.
+      BOX handles the HTTP routing, request parsing, and response formatting automatically.
+    </div>
+
+    <h2>🚀 Development Workflow</h2>
+    <ol>
+      <li>Edit <code>.box</code> files in <code>src/</code></li>
+      <li>Save the file</li>
+      <li>Browser auto-refreshes (HMR)</li>
+      <li>See your changes instantly</li>
+    </ol>
+
+    <div class="tip-box">
+      <strong>💡 Vibe Tip:</strong> BOX watches for changes and rebuilds automatically.
+      No manual build step needed during development!
+    </div>
+
+    <h2>📦 Building for Production</h2>
+    <div class="code-block">npm run build</div>
+    <p>This generates <code>dist/</code> with:</p>
+    <ul>
+      <li><code>index.html</code> - Compiled frontend</li>
+      <li><code>app.js</code> - Minified frontend code</li>
+      <li><code>style.css</code> - Minified styles</li>
+      <li><code>server.js</code> - Node.js backend server</li>
+    </ul>
+
+    <h2>🎯 Next Steps</h2>
+    <ol>
+      <li>✅ Run <code>npm run dev</code> to start the development server</li>
+      <li>✅ Edit <code>src/main.box</code> to customize your app</li>
+      <li>✅ Create new <code>.box</code> components in <code>src/</code></li>
+      <li>✅ Use <code>api+name.box</code> for backend endpoints</li>
+      <li>✅ Build with <code>npm run build</code> for production</li>
+    </ol>
+
+    <h2>📚 Learn More</h2>
+    <ul>
+      <li>📖 <a href="https://github.com/itayzrihan/box" target="_blank">BOX Framework GitHub</a></li>
+      <li>💬 Check the other example components: <code>counter.box</code> and <code>api-demo.box</code></li>
+      <li>🤖 These .box files are AI-friendly! Paste the entire component into Claude, ChatGPT, etc. for help</li>
+    </ul>
+
+    <h2>🎨 Your Turn!</h2>
+    <p>
+      Now that you understand the basics, start building! Edit <code>main.box</code> and add
+      your own components. BOX is designed to get out of your way so you can focus on
+      building great UIs.
+    </p>
+
+    <p style="text-align: center; margin-top: 3rem; color: #667eea; font-size: 18px;">
+      <strong>Happy Vibe Coding! 🚀</strong>
+    </p>
+  </div>
+</template>
+
+<script>
+  // This is just a documentation component, no logic needed!
+  console.log('📚 Learning guide loaded. Check the examples in counter.box and api-demo.box!');
+</script>

package/template/src/main.box

@@ -3,15 +3,88 @@
     min-height: 100vh;
     display: flex;
     flex-direction: column;
+    background: linear-gradient(135deg, #f5f7fa 0%, #c3cfe2 100%);
+    padding: 2rem;
+  }
+
+  .app-container {
+    max-width: 1200px;
+    margin: 0 auto;
+    width: 100%;
+  }
+
+  .app-header {
+    text-align: center;
+    margin-bottom: 3rem;
+  }
+
+  .app-header h1 {
+    color: #667eea;
+    margin: 0;
+    font-size: 32px;
+  }
+
+  .app-header p {
+    color: #7f8c8d;
+    margin: 0.5rem 0 0 0;
+  }
+
+  .examples-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+    gap: 2rem;
+    margin-bottom: 3rem;
+  }
+
+  @media (max-width: 768px) {
+    .examples-grid {
+      grid-template-columns: 1fr;
+    }
+
+    .app-header h1 {
+      font-size: 24px;
+    }
   }
 </style>
 
 <template>
   <div class="app">
-    <include src="./welcome.box" />
+    <div class="app-container">
+      <div class="app-header">
+        <h1>⚡ BOX Framework</h1>
+        <p>Zero-dependency, full-stack web framework</p>
+      </div>
+
+      <!-- Learning Guide -->
+      <include src="./learning-guide.box" />
+
+      <!-- Examples Section -->
+      <div style="text-align: center; margin-top: 3rem; margin-bottom: 1rem;">
+        <h2 style="color: #667eea;">📖 Live Examples</h2>
+        <p style="color: #7f8c8d;">Click around to see BOX in action</p>
+      </div>
+
+      <div class="examples-grid">
+        <include src="./counter.box" />
+        <include src="./api-demo.box" />
+      </div>
+
+      <div style="text-align: center; margin-top: 3rem; padding: 2rem; background: rgba(255,255,255,0.8); border-radius: 12px;">
+        <h3 style="color: #667eea; margin-top: 0;">Ready to build?</h3>
+        <p style="color: #7f8c8d;">
+          Edit files in <code style="background: #f0f0f0; padding: 0.25rem 0.5rem; border-radius: 4px;">src/</code>
+          and watch changes live. Check <code style="background: #f0f0f0; padding: 0.25rem 0.5rem; border-radius: 4px;">counter.box</code> 
+          and <code style="background: #f0f0f0; padding: 0.25rem 0.5rem; border-radius: 4px;">api-demo.box</code> for code examples.
+        </p>
+      </div>
+    </div>
   </div>
 </template>
 
 <script>
+  // This is your app's entry point
+  // BOX automatically includes all files referenced with <include />
+  console.log('🚀 BOX App loaded successfully!');
+</script>
   console.log('📦 BOX App initialized!');
 </script>