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
-- `PUT /api/content/{id}` - Update existing content
+- `POST /api/content` - Create or update content (upsert)
+- `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