insforge 0.3.3 → 1.3.0

package/docs/deprecated/insforge-debug.md

@@ -1,65 +1,65 @@
-# Insforge Debug Guide
-
-## When Your API Code Fails
-
-**Start here** → `get-instructions` and `get-backend-metadata` (understand system state)
-**Read docs** → `get-db-api`, `get-auth-api`, `get-storage-api` (read ALL of them)
-**Check table** → `get-table-schema` with your table name
-**Test endpoint** → Use curl with exact API format from docs
-
-## Critical Rule: Read Documentation First
-
-Before debugging, you MUST read all documentation to understand how the API works.
-
-## Common API Issues
-
-**Table created but API fails** → Check field names match schema exactly
-**Array required** → PostgREST requires POST requests as arrays `[{...}]`
-**Foreign key error** → Parent record must exist before child
-**Permission denied** → Write operations need `Authorization: Bearer <accessToken>`
-**JWSError** → JWT token expired or invalid - user needs to login again
-**PATCH increment fails** → PostgREST doesn't support SQL expressions like `count + 1`
-
-## Debug Workflow
-
-1. **Always** call `get-backend-metadata` first
-2. Read the relevant API documentation completely
-3. Check your table schema matches your API calls
-4. Test with curl using exact format from docs
-5. Verify response matches documentation
-
-### Example Debug Tests
-
-```bash
-# Test GET endpoint
-# Windows PowerShell: use curl.exe
-curl -X GET http://localhost:7130/api/database/records/your_table \
-  -H "Authorization: Bearer YOUR_TOKEN" | jq .
-
-# Test POST with array format
-# Mac/Linux
-curl -X POST http://localhost:7130/api/database/records/your_table \
-  -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Prefer: return=representation' \
-  -d '[{"field": "value"}]' | jq .
-
-# Windows PowerShell (use curl.exe) - different quotes for nested JSON
-curl.exe -X POST http://localhost:7130/api/database/records/your_table \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer YOUR_TOKEN" \
-  -H "Prefer: return=representation" \
-  -d '[{\"field\": \"value\"}]' | jq .
-```
-
-## Key Rules
-
-- Backend runs on port 7130
-- **READ operations**: No authentication required
-- **WRITE operations**: Need `Authorization: Bearer <accessToken>` header
-- POST requests must be arrays `[{...}]`
-- System tables (prefixed with _) need special APIs
-- No escaped characters in JSON
-- Login/register returns JWT tokens directly in `accessToken` field
-
+# Insforge Debug Guide
+
+## When Your API Code Fails
+
+**Start here** → `get-instructions` and `get-backend-metadata` (understand system state)
+**Read docs** → `get-db-api`, `get-auth-api`, `get-storage-api` (read ALL of them)
+**Check table** → `get-table-schema` with your table name
+**Test endpoint** → Use curl with exact API format from docs
+
+## Critical Rule: Read Documentation First
+
+Before debugging, you MUST read all documentation to understand how the API works.
+
+## Common API Issues
+
+**Table created but API fails** → Check field names match schema exactly
+**Array required** → PostgREST requires POST requests as arrays `[{...}]`
+**Foreign key error** → Parent record must exist before child
+**Permission denied** → Write operations need `Authorization: Bearer <accessToken>`
+**JWSError** → JWT token expired or invalid - user needs to login again
+**PATCH increment fails** → PostgREST doesn't support SQL expressions like `count + 1`
+
+## Debug Workflow
+
+1. **Always** call `get-backend-metadata` first
+2. Read the relevant API documentation completely
+3. Check your table schema matches your API calls
+4. Test with curl using exact format from docs
+5. Verify response matches documentation
+
+### Example Debug Tests
+
+```bash
+# Test GET endpoint
+# Windows PowerShell: use curl.exe
+curl -X GET http://localhost:7130/api/database/records/your_table \
+  -H "Authorization: Bearer YOUR_TOKEN" | jq .
+
+# Test POST with array format
+# Mac/Linux
+curl -X POST http://localhost:7130/api/database/records/your_table \
+  -H 'Content-Type: application/json' \
+  -H 'Authorization: Bearer YOUR_TOKEN' \
+  -H 'Prefer: return=representation' \
+  -d '[{"field": "value"}]' | jq .
+
+# Windows PowerShell (use curl.exe) - different quotes for nested JSON
+curl.exe -X POST http://localhost:7130/api/database/records/your_table \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Prefer: return=representation" \
+  -d '[{\"field\": \"value\"}]' | jq .
+```
+
+## Key Rules
+
+- Backend runs on port 7130
+- **READ operations**: No authentication required
+- **WRITE operations**: Need `Authorization: Bearer <accessToken>` header
+- POST requests must be arrays `[{...}]`
+- System tables (prefixed with _) need special APIs
+- No escaped characters in JSON
+- Login/register returns JWT tokens directly in `accessToken` field
+
 **Remember**: MCP creates the structure, but you must follow API documentation exactly to use it.

package/docs/deprecated/insforge-instructions.md

@@ -1,124 +1,124 @@
-# Insforge OSS Instructions
-
-## What Insforge OSS Does
-
-Backend-as-a-service with database, authentication, and file storage. 
-
-**Key Concept**: InsForge replaces your traditional backend - implement business logic by calling database operations directly. Instead of building API endpoints, use our database API as your application's backend.
-
-## 🚨 Project Setup
-
-**Create your app in a NEW directory, not inside `insforge/`**
-
-The `insforge/` directory is the BaaS platform. Your app should live elsewhere:
-```
-~/projects/
-├── insforge/      # ← BaaS platform (don't work here)
-└── my-app/        # ← Your new app (work here)
-```
-
-## When to Use Tools
-
-**MUST DO FIRST** → Download project rules: `download-project-rules`
-**Start here** → `get-backend-metadata` (shows current database state)
-**Need docs** → `get-db-api`, `get-auth-api`, or `get-storage-api`
-**Create table** → `create-table` with explicit schema
-**Work with data** → Use database API endpoints directly
-
-## Critical Rule: 
-**MUST DO FIRST** → Call`download-project-rules` to download project ruless
-
-## Critical Rule: Check Metadata First
-
-Before ANY database operation, call `get-backend-metadata` to get the current database state.
-
-## Standard Workflow
-
-1. **Always** call `get-backend-metadata` first
-2. Check `get-instructions` if unfamiliar with the system
-3. Create tables with `create-table` if needed
-4. Use database API to insert/query/update/delete records
-5. Call `get-backend-metadata` again to verify changes
-
-## Key Rules
-
-- Frequently check `get-instructions` and `get-backend-metadata`
-- Always define explicit table schemas (no assumptions)
-- Every table gets auto ID, created_at, updated_at fields
-- **Database operations require**: JWT token (Authorization: Bearer header)
-- **API keys are for MCP testing** (use tokens for production)
-- File uploads work automatically with multipart/form-data
-
-## Authentication Requirements
-
-### Database Operations Need Authentication Token:
-1. **JWT Token**: `Authorization: Bearer your-jwt-token` - Authenticates the user
-
-**Important Note about API Keys:**
-- The `x-api-key` header is ONLY used for MCP (Model Context Protocol) testing
-- Production applications should NEVER use API keys
-- Always use JWT tokens from user/admin authentication for real applications
-
-Without the Bearer token, you'll get "permission denied" errors when trying to insert, update, or delete records.
-
-### Getting Authentication:
-```bash
-# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
-# 1. First login to get JWT token
-curl -X POST http://localhost:7130/api/auth/admin/sessions \
-  -H "Content-Type: application/json" \
-  -d "{\"email\":\"admin@example.com\",\"password\":\"your-password\"}"
-
-# Response includes token: {"accessToken": "eyJ...", "user": {...}}
-
-# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
-# 2. Use the auth token for database operations
-curl -X POST http://localhost:7130/api/database/records/products \
-  -H "Authorization: Bearer eyJ..." \
-  -H "Content-Type: application/json" \
-  -d "[{\"name\": \"Product\", \"price\": 99.99}]"
-```
-
-## Example: Comment Upvoting Feature
-
-- Check current tables: `get-backend-metadata`
-- Create comment_votes table: `create-table` with user_id, comment_id, vote_type fields
-- Frontend upvote action: `POST /api/database/records/comment_votes` with vote data
-- Frontend display scores: `GET /api/database/records/comment_votes?comment_id=eq.123` to count votes
-- No separate backend needed - frontend calls InsForge database API directly
-
-
-## Critical Rule: Test API Endpoints with curl
-
-After creating or modifying any API endpoint, always test it with curl to verify it works correctly.
-
-**Note:** Avoid special characters (!,$,`,\) in curl command data - they can cause bash interpretation issues. Use simple text for testing:
-
-```bash
-# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
-# Example: Test creating a record (requires JWT token)
-curl -X POST http://localhost:7130/api/database/records/posts \
-  -H "x-api-key: your-api-key" \
-  -H "Authorization: Bearer your-jwt-token" \
-  -H "Content-Type: application/json" \
-  -d '[{\"title\": \"Test Post\", \"content\": \"Test content\"}]'
-
-# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
-# Example: Test querying records (requires both API key and JWT token)
-curl http://localhost:7130/api/database/records/posts?id=eq.123 \
-  -H "x-api-key: your-api-key" \
-  -H "Authorization: Bearer your-jwt-token"
-
-# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
-# Example: Test authentication
-curl -X POST http://localhost:7130/api/auth/users \
-  -H "Content-Type: application/json" \
-  -d '{\"email\": \"test@example.com\", \"password\": \"testpass123\"}'
-```
-
-Always include:
-- **Both headers for database operations**: x-api-key AND Authorization: Bearer token
-- Correct HTTP method (GET, POST, PATCH, DELETE)
-- Valid JSON payload for POST/PATCH requests (remember: POST requires array format `[{...}]`)
-- Query parameters for filtering GET requests
+# Insforge OSS Instructions
+
+## What Insforge OSS Does
+
+Backend-as-a-service with database, authentication, and file storage. 
+
+**Key Concept**: InsForge replaces your traditional backend - implement business logic by calling database operations directly. Instead of building API endpoints, use our database API as your application's backend.
+
+## 🚨 Project Setup
+
+**Create your app in a NEW directory, not inside `insforge/`**
+
+The `insforge/` directory is the BaaS platform. Your app should live elsewhere:
+```
+~/projects/
+├── insforge/      # ← BaaS platform (don't work here)
+└── my-app/        # ← Your new app (work here)
+```
+
+## When to Use Tools
+
+**MUST DO FIRST** → Download project rules: `download-project-rules`
+**Start here** → `get-backend-metadata` (shows current database state)
+**Need docs** → `get-db-api`, `get-auth-api`, or `get-storage-api`
+**Create table** → `create-table` with explicit schema
+**Work with data** → Use database API endpoints directly
+
+## Critical Rule: 
+**MUST DO FIRST** → Call`download-project-rules` to download project ruless
+
+## Critical Rule: Check Metadata First
+
+Before ANY database operation, call `get-backend-metadata` to get the current database state.
+
+## Standard Workflow
+
+1. **Always** call `get-backend-metadata` first
+2. Check `get-instructions` if unfamiliar with the system
+3. Create tables with `create-table` if needed
+4. Use database API to insert/query/update/delete records
+5. Call `get-backend-metadata` again to verify changes
+
+## Key Rules
+
+- Frequently check `get-instructions` and `get-backend-metadata`
+- Always define explicit table schemas (no assumptions)
+- Every table gets auto ID, created_at, updated_at fields
+- **Database operations require**: JWT token (Authorization: Bearer header)
+- **API keys are for MCP testing** (use tokens for production)
+- File uploads work automatically with multipart/form-data
+
+## Authentication Requirements
+
+### Database Operations Need Authentication Token:
+1. **JWT Token**: `Authorization: Bearer your-jwt-token` - Authenticates the user
+
+**Important Note about API Keys:**
+- The `x-api-key` header is ONLY used for MCP (Model Context Protocol) testing
+- Production applications should NEVER use API keys
+- Always use JWT tokens from user/admin authentication for real applications
+
+Without the Bearer token, you'll get "permission denied" errors when trying to insert, update, or delete records.
+
+### Getting Authentication:
+```bash
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# 1. First login to get JWT token
+curl -X POST http://localhost:7130/api/auth/admin/sessions \
+  -H "Content-Type: application/json" \
+  -d "{\"email\":\"admin@example.com\",\"password\":\"your-password\"}"
+
+# Response includes token: {"accessToken": "eyJ...", "user": {...}}
+
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# 2. Use the auth token for database operations
+curl -X POST http://localhost:7130/api/database/records/products \
+  -H "Authorization: Bearer eyJ..." \
+  -H "Content-Type: application/json" \
+  -d "[{\"name\": \"Product\", \"price\": 99.99}]"
+```
+
+## Example: Comment Upvoting Feature
+
+- Check current tables: `get-backend-metadata`
+- Create comment_votes table: `create-table` with user_id, comment_id, vote_type fields
+- Frontend upvote action: `POST /api/database/records/comment_votes` with vote data
+- Frontend display scores: `GET /api/database/records/comment_votes?comment_id=eq.123` to count votes
+- No separate backend needed - frontend calls InsForge database API directly
+
+
+## Critical Rule: Test API Endpoints with curl
+
+After creating or modifying any API endpoint, always test it with curl to verify it works correctly.
+
+**Note:** Avoid special characters (!,$,`,\) in curl command data - they can cause bash interpretation issues. Use simple text for testing:
+
+```bash
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# Example: Test creating a record (requires JWT token)
+curl -X POST http://localhost:7130/api/database/records/posts \
+  -H "x-api-key: your-api-key" \
+  -H "Authorization: Bearer your-jwt-token" \
+  -H "Content-Type: application/json" \
+  -d '[{\"title\": \"Test Post\", \"content\": \"Test content\"}]'
+
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# Example: Test querying records (requires both API key and JWT token)
+curl http://localhost:7130/api/database/records/posts?id=eq.123 \
+  -H "x-api-key: your-api-key" \
+  -H "Authorization: Bearer your-jwt-token"
+
+# Works on both Windows and Unix (Windows PowerShell: use curl.exe)
+# Example: Test authentication
+curl -X POST http://localhost:7130/api/auth/users \
+  -H "Content-Type: application/json" \
+  -d '{\"email\": \"test@example.com\", \"password\": \"testpass123\"}'
+```
+
+Always include:
+- **Both headers for database operations**: x-api-key AND Authorization: Bearer token
+- Correct HTTP method (GET, POST, PATCH, DELETE)
+- Valid JSON payload for POST/PATCH requests (remember: POST requires array format `[{...}]`)
+- Query parameters for filtering GET requests
 - Prefer: return=representation header if you want to see the created/updated records

package/docs/deprecated/insforge-project.md

@@ -1,118 +1,118 @@
----
-description: Insforge AI Development Rules - Essential guidelines for BaaS platform development
-globs: 
-alwaysApply: true
----
-
-# Insforge Development Rules
-
-## Core Identity
-You are an exceptional software developer using Insforge Backend to assist building the product. Make it visually stunning, content-rich, professional-grade UIs.
-
-## 🔴 MANDATORY: cURL Test at EVERY Step
-
-**For AI Agents: Test with cURL repeatedly throughout development:**
-
-1. **Before coding** → Test endpoint exists, check response format
-2. **During coding** → Test when confused about any API behavior  
-3. **After coding** → Test complete user journey end-to-end
-4. **When debugging** → Test to see actual vs expected responses
-
-```bash
-# Mac/Linux
-curl -X POST http://localhost:7130/api/[endpoint] \
-  -H 'Content-Type: application/json' \
-  -d '[{"key": "value"}]' | jq .
-
-# Windows PowerShell (use curl.exe) - different quotes for nested JSON
-curl.exe -X POST http://localhost:7130/api/[endpoint] \
-  -H "Content-Type: application/json" \
-  -d '[{\"key\": \"value\"}]' | jq .
-```
-
-**You WILL get it wrong without testing. Test early, test often.**
-
-## Critical Architecture Points
-
-When in doubt, read instructions documents again.
-
-## 🚨 CRUD Operations - PostgREST NOT RESTful
-### PostgREST Database API Behavior
-
-**Critical PostgREST Rules:**
-
-1. **POST requires array**: `[{...}]` even for single record
-2. **Empty responses without `Prefer: return=representation`**:
-   - POST → `[]` (empty array)
-   - PATCH → 204 No Content
-   - DELETE → 204 No Content
-   - **DELETE is idempotent** - no error if record doesn't exist
-3. **With `Prefer: return=representation`**: 
-   - Returns affected records as array
-   - DELETE and PATCH returns `[]` if record didn't exist
-4. **Pagination**: 
-   - Request: `Range: 0-9` + `Prefer: count=exact`
-   - Response: `Content-Range: 0-9/100` header (shows total)
-   - Without `Prefer: count=exact`: `Content-Range: 0-9/*` (no total)
-5. **Query syntax**: `?field=operator.value`
-   - `?id=eq.123` (equals)
-   - `?age=gt.30` (greater than)
-   - `?name=like.*john*` (pattern match)
-
-## Auth Operations:
-
-### 🚨 IMPORTANT: Correct Auth Endpoints
-- **Register**: `POST /api/auth/users` - Create new user account
-- **Login**: `POST /api/auth/sessions` - Authenticate existing user
-- **Admin Login**: `POST /api/auth/admin/sessions` - Admin authentication
-- **Current User**: `GET /api/auth/sessions/current` - Get authenticated user info
-- `/api/auth/sessions/current` returns `{"user": {...}}` - nested structure
-- Store JWT tokens and include as `Authorization: Bearer {accessToken}` header
-- **Note**: Login/register returns `{accessToken, user}` with JWT token
-
-### Regular API Response Format
-
-**⚠️ IMPORTANT: Frontend Error Handling**
-- **PARSE** backend responses and display user-friendly messages
-- **DO NOT** show raw API responses directly to users
-- **TRANSFORM** error details into readable, actionable messages
-
-- Success: Data directly (object/array)
-- Error: `{error, message, statusCode}`
-- Empty POST/PATCH/DELETE: Add `Prefer: return=representation`
-
-### 🚨 Storage API Rules
-- **Upload Methods**: 
-  - **PUT** `/api/storage/buckets/{bucket}/objects/{filename}` - Upload with specific key
-  - **POST** `/api/storage/buckets/{bucket}/objects` - Upload with auto-generated key
-- **Authentication**: Upload operations require `Authorization: Bearer {accessToken}`
-- **Generate Unique Filenames**: Use POST for auto-generated keys to prevent overwrites
-- **Multipart Form**: Use FormData for file uploads
-- **URL Format**: Storage returns **ABSOLUTE URLs** (e.g., `http://localhost:7130/api/storage/buckets/{bucket}/objects/{filename}`)
-  - **IMPORTANT**: URLs are complete and ready to use - no need to prepend host or path
-  - Use the URL directly in `<img src>` or fetch requests
-
-## 🔥 Test EVERY Endpoint
-
-**Backend runs on port 7130**
-
-Always test with cURL before UI integration:
-- Include `Authorization: Bearer {accessToken}` for auth
-- Add `Prefer: return=representation` to see created data
-- Windows PowerShell: use curl.exe
-
-```bash
-# Mac/Linux
-curl -X POST http://localhost:7130/api/database/records/posts \
-  -H 'Authorization: Bearer TOKEN' \
-  -H 'Content-Type: application/json' \
-  -H 'Prefer: return=representation' \
-  -d '[{"user_id": "from-localStorage", "caption": "Test"}]'
-
-# Windows PowerShell (use curl.exe) - different quotes for nested JSON
-curl.exe -X POST http://localhost:7130/api/database/records/posts \
-  -H "Authorization: Bearer TOKEN" \
-  -H "Content-Type: application/json" \
-  -H "Prefer: return=representation" \
-  -d '[{\"user_id\": \"from-localStorage\", \"caption\": \"Test\"}]'
+---
+description: Insforge AI Development Rules - Essential guidelines for BaaS platform development
+globs: 
+alwaysApply: true
+---
+
+# Insforge Development Rules
+
+## Core Identity
+You are an exceptional software developer using Insforge Backend to assist building the product. Make it visually stunning, content-rich, professional-grade UIs.
+
+## 🔴 MANDATORY: cURL Test at EVERY Step
+
+**For AI Agents: Test with cURL repeatedly throughout development:**
+
+1. **Before coding** → Test endpoint exists, check response format
+2. **During coding** → Test when confused about any API behavior  
+3. **After coding** → Test complete user journey end-to-end
+4. **When debugging** → Test to see actual vs expected responses
+
+```bash
+# Mac/Linux
+curl -X POST http://localhost:7130/api/[endpoint] \
+  -H 'Content-Type: application/json' \
+  -d '[{"key": "value"}]' | jq .
+
+# Windows PowerShell (use curl.exe) - different quotes for nested JSON
+curl.exe -X POST http://localhost:7130/api/[endpoint] \
+  -H "Content-Type: application/json" \
+  -d '[{\"key\": \"value\"}]' | jq .
+```
+
+**You WILL get it wrong without testing. Test early, test often.**
+
+## Critical Architecture Points
+
+When in doubt, read instructions documents again.
+
+## 🚨 CRUD Operations - PostgREST NOT RESTful
+### PostgREST Database API Behavior
+
+**Critical PostgREST Rules:**
+
+1. **POST requires array**: `[{...}]` even for single record
+2. **Empty responses without `Prefer: return=representation`**:
+   - POST → `[]` (empty array)
+   - PATCH → 204 No Content
+   - DELETE → 204 No Content
+   - **DELETE is idempotent** - no error if record doesn't exist
+3. **With `Prefer: return=representation`**: 
+   - Returns affected records as array
+   - DELETE and PATCH returns `[]` if record didn't exist
+4. **Pagination**: 
+   - Request: `Range: 0-9` + `Prefer: count=exact`
+   - Response: `Content-Range: 0-9/100` header (shows total)
+   - Without `Prefer: count=exact`: `Content-Range: 0-9/*` (no total)
+5. **Query syntax**: `?field=operator.value`
+   - `?id=eq.123` (equals)
+   - `?age=gt.30` (greater than)
+   - `?name=like.*john*` (pattern match)
+
+## Auth Operations:
+
+### 🚨 IMPORTANT: Correct Auth Endpoints
+- **Register**: `POST /api/auth/users` - Create new user account
+- **Login**: `POST /api/auth/sessions` - Authenticate existing user
+- **Admin Login**: `POST /api/auth/admin/sessions` - Admin authentication
+- **Current User**: `GET /api/auth/sessions/current` - Get authenticated user info
+- `/api/auth/sessions/current` returns `{"user": {...}}` - nested structure
+- Store JWT tokens and include as `Authorization: Bearer {accessToken}` header
+- **Note**: Login/register returns `{accessToken, user}` with JWT token
+
+### Regular API Response Format
+
+**⚠️ IMPORTANT: Frontend Error Handling**
+- **PARSE** backend responses and display user-friendly messages
+- **DO NOT** show raw API responses directly to users
+- **TRANSFORM** error details into readable, actionable messages
+
+- Success: Data directly (object/array)
+- Error: `{error, message, statusCode}`
+- Empty POST/PATCH/DELETE: Add `Prefer: return=representation`
+
+### 🚨 Storage API Rules
+- **Upload Methods**: 
+  - **PUT** `/api/storage/buckets/{bucket}/objects/{filename}` - Upload with specific key
+  - **POST** `/api/storage/buckets/{bucket}/objects` - Upload with auto-generated key
+- **Authentication**: Upload operations require `Authorization: Bearer {accessToken}`
+- **Generate Unique Filenames**: Use POST for auto-generated keys to prevent overwrites
+- **Multipart Form**: Use FormData for file uploads
+- **URL Format**: Storage returns **ABSOLUTE URLs** (e.g., `http://localhost:7130/api/storage/buckets/{bucket}/objects/{filename}`)
+  - **IMPORTANT**: URLs are complete and ready to use - no need to prepend host or path
+  - Use the URL directly in `<img src>` or fetch requests
+
+## 🔥 Test EVERY Endpoint
+
+**Backend runs on port 7130**
+
+Always test with cURL before UI integration:
+- Include `Authorization: Bearer {accessToken}` for auth
+- Add `Prefer: return=representation` to see created data
+- Windows PowerShell: use curl.exe
+
+```bash
+# Mac/Linux
+curl -X POST http://localhost:7130/api/database/records/posts \
+  -H 'Authorization: Bearer TOKEN' \
+  -H 'Content-Type: application/json' \
+  -H 'Prefer: return=representation' \
+  -d '[{"user_id": "from-localStorage", "caption": "Test"}]'
+
+# Windows PowerShell (use curl.exe) - different quotes for nested JSON
+curl.exe -X POST http://localhost:7130/api/database/records/posts \
+  -H "Authorization: Bearer TOKEN" \
+  -H "Content-Type: application/json" \
+  -H "Prefer: return=representation" \
+  -d '[{\"user_id\": \"from-localStorage\", \"caption\": \"Test\"}]'
 ```