docs: update API documentation for single POST upsert endpoint

- Replace separate POST/PUT endpoints with unified POST upsert endpoint
- Add comprehensive API usage examples with automatic ID generation
- Simplify content management to single endpoint for create/update operations
- Document element_context for backend ID generation and version control features

COMMANDS.md

@@ -120,13 +120,97 @@ When running `insertr serve`, these endpoints are available:
 - `GET /api/content?site_id={site}` - Get all content for site
 - `GET /api/content/{id}?site_id={site}` - Get single content item
 - `GET /api/content/bulk?site_id={site}&ids[]={id1}&ids[]={id2}` - Get multiple items
-- `POST /api/content` - Create new content
+- `POST /api/content` - Create or update content (upsert)
-- `PUT /api/content/{id}` - Update existing content
+- `DELETE /api/content/{id}?site_id={site}` - Delete content
+
+#### Site Enhancement
+- `POST /api/enhance?site_id={site}` - Manually trigger site file enhancement
 
 #### Version Control
 - `GET /api/content/{id}/versions?site_id={site}` - Get content history
 - `POST /api/content/{id}/rollback` - Rollback to previous version
 
+### Content Management API Details
+
+#### Create/Update Content (Upsert)
+```
+POST /api/content[?site_id={site}]
+```
+
+**Request Body:**
+```json
+{
+  "id": "optional-content-id",
+  "site_id": "site-identifier",
+  "value": "content-value",
+  "type": "text|markdown|link",
+  "element_context": {
+    "tag": "h1",
+    "classes": ["insertr", "title"],
+    "original_content": "Default Title",
+    "parent_context": "hero-section"
+  }
+}
+```
+
+**Key Features:**
+- **Automatic ID Generation**: If no `id` provided, generates deterministic ID from `element_context`
+- **Content Type Detection**: Automatically determines type if not specified
+- **Version History**: Preserves existing content as version before update
+- **Flexible Site ID**: Can be provided in URL parameter or request body
+- **Auto-Enhancement**: Triggers file enhancement if site has `auto_enhance: true`
+
+**Response:**
+```json
+{
+  "id": "generated-or-provided-id",
+  "site_id": "site-identifier", 
+  "value": "content-value",
+  "type": "text|markdown|link",
+  "created_at": "2024-01-01T00:00:00Z",
+  "updated_at": "2024-01-01T00:00:00Z",
+  "last_edited_by": "user-id"
+}
+```
+
+**Usage Examples:**
+
+```bash
+# Create with automatic ID generation
+curl -X POST http://localhost:8080/api/content?site_id=demo \
+  -H "Content-Type: application/json" \
+  -d '{
+    "value": "New Homepage Title",
+    "element_context": {
+      "tag": "h1",
+      "classes": ["insertr"],
+      "original_content": "Welcome"
+    }
+  }'
+
+# Update existing content by ID
+curl -X POST http://localhost:8080/api/content \
+  -H "Content-Type: application/json" \
+  -d '{
+    "id": "homepage-title-abc123",
+    "site_id": "demo",
+    "value": "Updated Title",
+    "type": "text"
+  }'
+
+# Create markdown content
+curl -X POST http://localhost:8080/api/content?site_id=demo \
+  -H "Content-Type: application/json" \
+  -d '{
+    "value": "# New Article\n\nThis is **markdown** content.",
+    "type": "markdown",
+    "element_context": {
+      "tag": "div",
+      "classes": ["insertr", "content"]
+    }
+  }'
+```
+
 ## ⚙️ Configuration
 
 ### YAML Configuration File

README.md

@@ -297,6 +297,35 @@ export INSERTR_SITE_ID="production"
 - **Links/Buttons** (`a`, `button`) → Text + URL fields
 - **Containers** (`div`, `section`) → Expand to viable children
 
+## 🔌 API Reference
+
+### **Simple Content Management**
+```bash
+# Create or update content (single endpoint for both)
+curl -X POST http://localhost:8080/api/content?site_id=demo \
+  -H "Content-Type: application/json" \
+  -d '{"value": "New content", "type": "text"}'
+
+# Get all content for a site
+curl http://localhost:8080/api/content?site_id=demo
+
+# Get specific content by ID
+curl http://localhost:8080/api/content/content-id?site_id=demo
+
+# View edit history
+curl http://localhost:8080/api/content/content-id/versions?site_id=demo
+
+# Rollback to previous version
+curl -X POST http://localhost:8080/api/content/content-id/rollback \
+  -d '{"version_id": 123}'
+```
+
+**Key Features:**
+- **Single POST endpoint** handles both create and update (upsert)
+- **Automatic ID generation** from element context if no ID provided
+- **Version control** preserves all changes with user attribution
+- **Auto-enhancement** updates static files when content changes
+
 ## 🔧 Development Workflow
 
 ### **Live Development with Hot Reload**