add instructions for AI and a readme for examples

examples/lang/readme.md

@@ -0,0 +1,202 @@
+# Basic DSL Usage
+
+## Overview
+
+The Masonry DSL (Domain Specific Language) is a unified syntax for defining full-stack applications. It allows you to describe servers, entities, API endpoints, and user interfaces in a single file, which can then be generated into various output formats including Go servers, HTML, and more.
+
+## Quick Start
+
+1. **Create a new Masonry file** (e.g., `app.masonry`)
+2. **Define your application structure** using the DSL syntax
+3. **Generate code** using the Masonry CLI
+
+## Basic DSL Structure
+
+A Masonry file consists of these main components:
+
+### 1. Server Configuration
+```masonry
+server MyApp {
+    host "localhost"
+    port 8080
+}
+```
+
+### 2. Entity Definitions
+Define your data models with fields, types, validation, and relationships:
+
+```masonry
+entity User desc "User account management" {
+    id: uuid required unique
+    email: string required validate email
+    name: string default "Anonymous"
+    created_at: timestamp default "now()"
+    profile_id: uuid relates to Profile as one
+}
+```
+
+**Supported field types:**
+- `uuid`, `string`, `text`, `int`, `boolean`, `timestamp`
+
+**Field modifiers:**
+- `required` - Field is mandatory
+- `unique` - Field must be unique
+- `indexed` - Field should be indexed
+- `default "value"` - Set default value
+- `validate email` - Email validation
+- `validate url` - URL validation
+- `validate min_length "5"` - Minimum length validation
+- `validate max_length "100"` - Maximum length validation
+
+**Relationships:**
+- `relates to EntityName as one` - One-to-one relationship
+- `relates to EntityName as many` - One-to-many relationship
+- `relates to EntityName as many through "table_name"` - Many-to-many through table
+
+### 3. API Endpoints
+Define REST API endpoints with parameters and responses:
+
+```masonry
+endpoint GET "/users" for User desc "List users" auth {
+    param page: int from query
+    param limit: int required from query
+    returns list as "json" fields [id, email, name]
+}
+
+endpoint POST "/users" for User desc "Create user" {
+    param user_data: object required from body
+    returns object as "json" fields [id, email, name]
+}
+```
+
+**HTTP methods:** `GET`, `POST`, `PUT`, `DELETE`
+
+**Parameter sources:**
+- `from query` - Query string parameter
+- `from path` - URL path parameter  
+- `from body` - Request body parameter
+
+**Features:**
+- `auth` - Requires authentication
+- `returns list/object` - Response type
+- `fields [...]` - Specify response fields
+
+### 4. User Interface Pages
+Define web pages with components and layouts:
+
+```masonry
+page UserManagement at "/admin/users" layout AdminLayout title "User Management" auth {
+    meta description "Manage system users"
+    
+    section main type container {
+        component UserTable for User {
+            fields [email, name, created_at]
+            actions [edit, delete, view]
+            data from "/users"
+        }
+    }
+}
+```
+
+**Page features:**
+- `layout LayoutName` - Page layout
+- `title "Page Title"` - Page title
+- `auth` - Requires authentication
+- `meta` - SEO metadata
+
+**Sections and Components:**
+- `section` - Layout containers with types (container, panel, tab, modal)
+- `component` - Reusable UI elements
+- `data from "/endpoint"` - Data binding
+
+## CLI Commands
+
+### Generate a Server
+Generate and optionally run a Go HTTP server:
+
+```bash
+# Generate server code
+./masonry.exe serve -f app.masonry -o server.go
+
+# Generate and run server
+./masonry.exe serve -f app.masonry -r
+```
+
+### Generate HTML
+Convert Masonry files to static HTML:
+
+```bash
+./masonry.exe generate html -i app.masonry -o ./output
+```
+
+### Template-based Generation
+Use custom templates for code generation:
+
+```bash
+# Use a single template file
+./masonry.exe template -i app.masonry -t my-template.tmpl -o output.go
+
+# Use a template directory
+./masonry.exe template -i app.masonry -d ./templates -r main.tmpl -o output.go
+```
+
+## Example Workflow
+
+1. **Create a simple blog application:**
+
+```masonry
+server BlogApp {
+    host "localhost"
+    port 8080
+}
+
+entity Post {
+    id: uuid required unique
+    title: string required
+    content: text required
+    published: boolean default "false"
+    created_at: timestamp default "now()"
+}
+
+endpoint GET "/posts" for Post {
+    returns list fields [id, title, published]
+}
+
+endpoint POST "/posts" for Post {
+    param post_data: object required from body
+    returns object
+}
+
+page PostList at "/posts" title "Blog Posts" {
+    component PostTable for Post {
+        fields [title, published, created_at]
+        data from "/posts"
+    }
+}
+```
+
+2. **Generate and run the server:**
+
+```bash
+./masonry.exe serve -f blog.masonry -r
+```
+
+3. **Visit http://localhost:8080 to see your generated application**
+
+## Advanced Features
+
+- **Conditional rendering** with `when` statements
+- **Complex layouts** with nested sections
+- **Form validation** and custom field types
+- **Authentication** and authorization
+- **Relationships** between entities
+- **Custom templates** for different output formats
+
+For a complete example showcasing all features, see the `example.masonry` file in this directory.
+
+## Next Steps
+
+- Explore the full `example.masonry` to see advanced features
+- Create custom templates for your preferred frameworks
+- Use the `setup` command to install required dependencies
+- Check out other examples in the `/examples` directory