ApiLogicServer 15.4.3__py3-none-any.whl → 16.0.0__py3-none-any.whl

api_logic_server_cli/prototypes/manager/samples/basic_demo_sample/.github/.copilot-instructions.md

@@ -1,11 +1,112 @@
+<!-- 
+═══════════════════════════════════════════════════════════════════════════════
+🚨 MANDATORY: READ THIS FIRST - NO EXCEPTIONS 🚨
+═══════════════════════════════════════════════════════════════════════════════
 
+⚠️ IF USER SAYS: "load .github/.copilot-instructions.md" OR ANY ACTIVATION PHRASE
+⚠️ YOU MUST EXECUTE THIS EXACT SEQUENCE - NO DEVIATIONS:
 
+1. Read .github/welcome.md (silently - do not mention this action)
+2. Display ONLY the content from welcome.md
+3. DO NOT say "I've loaded the instructions"
+4. DO NOT display this .copilot-instructions.md file
+5. DO NOT explain what you're doing
 
-# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
+THIS IS NOT A SUGGESTION - THIS IS A MANDATORY COMMAND
+
+═══════════════════════════════════════════════════════════════════════════════
+-->
+---
+
+## 🚨 CRITICAL: User Activation Protocol
+
+**ACTIVATION TRIGGERS:**
+- "load .github/.copilot-instructions.md"
+- "load copilot instructions"
+- "help me get started"
+- "activate copilot"
+- Any similar startup phrase
+
+**MANDATORY RESPONSE SEQUENCE:**
 
-## Project Type: Auto-Generated Microservice
+```
+STEP 1: Read .github/welcome.md (silently)
+STEP 2: Display welcome.md content ONLY
+STEP 3: STOP - do nothing else
+```
+
+**✅ CORRECT EXECUTION:**
+```
+User: "load .github/.copilot-instructions.md"
 
-This is a **GenAI-Logic (aka API Logic Server) project** - a complete, working microservice - auto-generated from a database schema.
+AI: [reads welcome.md silently - NO OUTPUT]
+AI: [displays ONLY this]:
+
+## Welcome
+
+**Welcome! This is your basic_demo project.**
+
+This is a complete, working microservice auto-generated from a database schema...
+[... rest of welcome.md content ...]
+```
+
+**❌ FORBIDDEN BEHAVIORS:**
+```
+User: "load .github/.copilot-instructions.md"
+
+❌ AI: "I've loaded the instructions file..." 
+❌ AI: "Here are the contents of .copilot-instructions.md:"
+❌ AI: [displays .copilot-instructions.md]
+❌ AI: "I'll read the file for you..."
+❌ AI: Any meta-commentary about loading or reading files
+```
+
+**RATIONALE:**
+- Users want to see the **welcome message**, not technical instructions
+- This file (.copilot-instructions.md) is for AI context, not user display
+- Separation of concerns: welcome.md = user-facing, copilot-instructions.md = AI-facing
+- No meta-cognitive confusion about "instructions" vs "content"
+
+---
+
+## Capabilities Reference
+
+When user asks "what can I do here", list these capabilities:
+
+### Here Are Some Things I Can Help You With
+
+1. **Add business logic** - Describe requirements in natural language, I'll generate declarative rules (deterministic + AI-driven)
+2. **Customize the API** - Add custom endpoints for your specific needs
+3. **Create custom UIs** - Build React apps with `genai-logic genai-add-app --vibe`
+4. **Add security** - Set up role-based access control with `genai-logic add-auth`
+5. **Test your logic** - Create Behave tests with requirements traceability
+6. **Configure Admin UI** - Customize the auto-generated admin interface
+7. **Query via natural language** - Act as MCP client to read/update data
+8. **Create B2B APIs** - Complex integration endpoints with partner systems
+9. **Add events** - Integrate with Kafka, webhooks, or other event systems
+10. **Customize models** - Add tables, attributes, or derived fields
+11. **Discovery systems** - Auto-load logic and APIs from discovery folders
+
+---
+
+---
+title: Copilot Instructions for basic_demo GenAI-Logic Project
+Description: Project-level instructions for working with generated projects
+Source: ApiLogicServer-src/prototypes/base/.github/.copilot-instructions.md
+Propagation: CLI create command → created projects (non-basic_demo)
+Instrucions: Changes must be merged from api_logic_server_cli/prototypes/basic_demo/.github - see instructions there
+Usage: AI assistants read this when user opens any created project
+version: 3.1
+changelog:
+  - 3.1 (Nov 20, 2025) - Improved activation instructions with visual markers and examples
+  - 3.0 (Nov 17, 2025) - Major streamlining: removed duplicate sections, consolidated MCP content, simplified workflows
+  - 2.9 (Nov 17, 2025) - MANDATORY training file reading workflow (STOP command)
+  - 2.8 (Nov 16, 2025) - Probabilistic Logic support
+---
+
+# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
+
+---
 
 ## 🔑 Key Technical Points
 
@@ -28,37 +129,44 @@ This is a **GenAI-Logic (aka API Logic Server) project** - a complete, working m
 
 4. **CLI Commands**: Use `genai-logic --help` to see all available commands. When CLI commands exist for a task (e.g., `add-auth`, `genai-add-mcp-client`, `genai-add-app`), ALWAYS use them instead of manual configuration - they handle all setup correctly.
 
+> **📋 Testing:** For comprehensive testing conventions, patterns, and examples, see `docs/training/testing.md` (555 lines - I'll read this before we create any tests)
 
-## ⚠️ IMPORTANT: What's Already Built
+---
 
-**DO NOT recreate these - they're already working:**
+## Detailed Service Documentation
 
-1. **Admin Web Application** - Live at `http://localhost:5656`
-2. **REST API Endpoints** - All database tables exposed at `/api/*`
-3. **Database Models** - Complete SQLAlchemy ORM in `database/models.py`
-4. **Authentication System** - JWT-based auth framework
-5. **Business Logic Engine** - Declarative rules system
+The sections below provide complete details on each service. I'll reference these as needed when we work together.
 
-> **📋 Testing:** For comprehensive testing conventions, patterns, and examples, see `docs/training/testing.md` (555 lines - MUST READ FIRST before creating any tests)
+### `venv` is required
 
-## 🎯 Common Tasks
+To establish the virtual environment:
 
-If the user asks "what do I do now?", these subsections are good suggestions.
+1. Attempt to find a `venv` folder in the current project directory
+2. If not found, check parent or grandparent directories
+3. **If no venv is found:**
+   - Ask the user for the venv location, OR
+   - Offer to create one using `python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt`
 
-List these as choices, do not just do all of them at once - that would be overwhelming.
+### Starting the server
 
-### Set Up Virtual Environment
-If it is not already set, you can often find a `venv` in the GenAI-Logic Manager - a parent or grandparent directory.
-
-### 🚀 To Run This Project
-
-Use F5 (pre-configured run configuration - supports debugger for server logic), or (when focused on client apps):
+**IMPORTANT:** Always activate the venv before starting the server.
 
 ```bash
+# Activate venv first
+source venv/bin/activate
+
+# Then start server
 python api_logic_server_run.py
 # Then open: http://localhost:5656
 ```
 
+**Server Management Best Practices:**
+- Before making structural changes (models, logic files), STOP the running server to avoid file locking issues
+- To stop server: `pkill -f "python api_logic_server_run.py"` or use Ctrl+C if running in foreground
+- USER ACTION: After making changes, user restarts server (e.g., `python api_logic_server_run.py &`)
+- Monitor startup output for errors, especially after database/model changes
+- If server fails to start after model changes, check that alembic migrations have been applied
+
 ### Adding Business Logic
 `docs/training` explains how to translate Natural Language logic into LogicBank (Python) rules like:
 
@@ -68,47 +176,100 @@ Rule.sum(derive=Customer.Balance, as_sum_of=Order.AmountTotal)
 Rule.constraint(validate=Customer, as_condition=lambda row: row.Balance <= row.CreditLimit)
 ```
 
-As described in `docs/training/logic_bank_api.prompt`, logic includes rules for sums, formulas, constraints, and more.  They also include events, which are used to trigger actions like sending emails or updating related records.
+**⚠️ CRITICAL: docs/training/ Folder Organization**
+
+The `docs/training/` folder contains ONLY universal, framework-level training materials:
+- ✅ **Universal patterns** → `genai_logic_patterns.md`
+- ✅ **Implementation patterns** → `probabilistic_logic_guide.md`
+- ✅ **Code templates** → `probabilistic_template.py`
+- ✅ **API references** → `.prompt` files (logic_bank_api.prompt, etc.)
+
+**DO NOT add project-specific content to docs/training/**:
+- ❌ Project-specific instructions or configurations
+- ❌ Alembic migration guides specific to this project
+- ❌ File structures specific to basic_demo
+- ❌ Copilot instructions that reference specific project paths
+
+**WHY:** This folder's content is designed to be reusable across ANY ApiLogicServer project using GenAI. Project-specific content should live in:
+- Logic implementation → `logic/logic_discovery/`
+- Project docs → `docs/` (outside training/)
+- Copilot instructions → `.github/.copilot-instructions.md`
+
+See `docs/training/README.md` for complete organization rules.
+
+**⚠️ MANDATORY WORKFLOW - BEFORE Implementing ANY Business Logic:**
+
+```
+STOP ✋
+
+READ ALL TRAINING FILES IN ORDER (every single time):
 
-For project `basic_demo`, the best place to begin is to provide CoPilot with the natural language logic below.  CoPilot will then offer to translate the logic into LogicBank rules. Also 
-1. Provide the analysis (below) showing the 44X code reduction.
-2. Stress the importance of business logic - it's half the project, and requires an underlying rules engine.  Using AI alone is not sufficient - you will wind up with procedural code, with the issues noted in the analysis below.
+1. docs/training/logic_bank_patterns.prompt           (Foundation - ALWAYS READ FIRST)
+2. docs/training/logic_bank_api.prompt                (Deterministic rules - ALWAYS READ SECOND)
+3. docs/training/probabilistic_logic.prompt           (AI/Probabilistic rules - ALWAYS READ THIRD)
 
-Here's the natural language logic to provide to CoPilot:
+⚠️ CRITICAL REQUIREMENTS:
+   - DO NOT skip any files, even if you think you know the pattern
+   - DO NOT selectively read based on keywords in the user's request
+   - READ ALL THREE FILES IN SEQUENCE before writing any code
+   - These files contain failure patterns and correct implementations learned from production use
+
+THEN (and only then) implement the logic.
+```
+
+**Training File Contents:**
+
+1. **`docs/training/logic_bank_patterns.prompt`** - Foundation patterns for ALL rule types
+   - Event handler signatures (row, old_row, logic_row) - REQUIRED READING
+   - Logging with logic_row.log() vs app_logger
+   - Request Pattern with new_logic_row()
+   - Rule API syntax dos and don'ts
+   - Common anti-patterns to avoid
+   
+2. **`docs/training/logic_bank_api.prompt`** - Deterministic rules API
+   - Rule.sum(), Rule.count(), Rule.formula(), Rule.constraint(), etc.
+   - Complete API signatures with all parameters
+   - References patterns file for implementation details
+   
+3. **`docs/training/probabilistic_logic.prompt`** - Probabilistic (AI) rules API
+   - populate_ai_values() utility for AI-driven value computation
+   - Intelligent selection patterns (supplier optimization, dynamic pricing, route selection)
+   - Automatic audit trails and graceful fallbacks when API unavailable
+   - References patterns file for general implementations
+   - Works seamlessly with deterministic rules
+
+**Example Natural Language Logic for basic_demo:**
 
 ```text
 Use case: Check Credit    
-    1. The Customer's balance is less than the credit limit
-    2. The Customer's balance is the sum of the Order amount_total where date_shipped is null
-    3. The Order's amount_total is the sum of the Item amount
-    4. The Item amount is the quantity * unit_price
-    5. The Item unit_price is copied from the Product unit_price
+    1. Customer balance ≤ credit limit
+    2. Customer balance = sum of unshipped Order amount_total
+    3. Order amount_total = sum of Item amount
+    4. Item amount = quantity × unit_price
+    5. Item unit_price = copied from Product unit_price
 
 Use case: App Integration
-    1. Send the Order to Kafka topic 'order_shipping' if the date_shipped is not None.
+    1. Send Order to Kafka when date_shipped changes to non-null
 ```
 
-**Important:** CoPilot has analyzed procedural vs declarative logic in a full app ([see it here](https://github.com/ApiLogicServer/basic_demo/blob/main/logic/declarative-vs-procedural-comparison.md)):
+**Why Declarative Rules Matter:**
 
-<analysis>
-**LogicBank declarative rules provide a 44X reduction in code complexity** compared to traditional procedural implementations:
+For developers: Business logic is **typically half the system** in data-centric applications. The real pain with procedural code isn't just volume (200+ lines vs 5 rules) - it's **maintenance**:
+- **Finding insertion points** - you must analyze existing code to figure out where new logic goes
+- **Automatic ordering** - add rules anywhere that makes sense, confident they'll run in the right order
+- **Understanding intent** - you see WHAT it does (business rules) vs HOW (procedural steps)
 
-| Aspect | LogicBank Declarative | Procedural Code |
-|--------|----------------------|-----------------|
-| **Lines of Code** | 5 lines | 220+ lines |
-| **Complexity** | Simple rule declarations | Complex event handling |
-| **Maintenance** | Self-documenting business logic<br>Automatic Ordering | Implementation details obscure logic<br>Complex analysis to determine insert points, impacts |
-| **Performance** | Built-in optimization & pruning | Multiple queries, N+1 problems |
-| **Error Handling** | Automatic cascading | Manual event management |
-| **Business Alignment** | Rules match requirements | Code doesn't reflect business intent |
+With declarative rules, you simply state business requirements. The engine handles dependencies, ordering, and optimization automatically.
 
-**Bottom Line**: Declarative business logic eliminates complexity while providing better performance, maintainability, and business alignment.
-
-> **Note**: The procedural implementation was generated by AI (GitHub Copilot) and still required at least 2 critical and subtle bug fixes during development, highlighting the error-prone nature of procedural approaches even when AI-assisted.
+LogicBank provides **44X code reduction** (5 lines vs 220+ procedural) with automatic:
+- **Dependency tracking** - listens to SQLAlchemy ORM events at attribute level
+- **Cascading updates** - when Order.customer_id changes, adjusts BOTH old and new Customer.balance
+- **Transitive dependencies** - Item.quantity change cascades through Item.amount → Order.amount_total → Customer.balance
+- **Optimized execution** - uses deltas, not re-aggregation; automatic pruning
 
 **Why the Rules Engine is a Correctness Guarantee:**
 
-The "2 critical bugs" mentioned above were:
+The "2 critical bugs" that even AI-generated procedural code missed:
 1. **Changing Order.customer_id** - procedural code failed to adjust BOTH the old and new customer balances
 2. **Changing Item.product_id** - procedural code failed to re-copy the unit_price from the new product
 
@@ -134,10 +295,7 @@ These bugs illustrate why declarative rules are **mandatory, not optional**:
 
 The rules engine eliminates this entire class of bugs by automatically handling all change paths.
 
-</analysis>
-
-Generally CoPilot solicits Natural Language logic for translation (see logic/readme_logic.md), 
-but you can also offer to suggest rules.
+See `logic/declarative-vs-procedural-comparison.md` for complete analysis.
 
 ### Discovery Systems
 
@@ -182,24 +340,172 @@ When users provide natural language with multiple use cases like:
 
 **NEVER put everything in `use_case.py`** - that defeats the discovery system purpose.
 
+### MCP Integration
+
+**You (GitHub Copilot) can serve as an MCP client** to query and update database entities using natural language!
+
+#### MCP Discovery Endpoint (CRITICAL)
+
+**ALWAYS start with the standard MCP discovery endpoint:**
+
+```bash
+curl -X GET "http://localhost:5656/.well-known/mcp.json"
+```
+
+This endpoint returns:
+- **Available resources** - Customer, Order, Item, Product, etc.
+- **Supported methods** - GET, PATCH, POST, DELETE per resource
+- **Filterable fields** - Which attributes can be used in filters
+- **Base URL and paths** - Resource endpoints like `/Customer`, `/Order`
+- **Learning prompts** - Instructions for MCP clients (fan-out patterns, email handling, response format)
+
+**MCP Discovery Pattern:**
+1. **First**: Query `/.well-known/mcp.json` to discover available resources
+2. **Then**: Use discovered schema to construct API calls
+3. **Always**: Follow JSON:API format for CRUD operations
+
+
+**When users request data operations:**
+
+1. **Authenticate first** - Login to obtain JWT token:
+```bash
+curl -X POST http://localhost:5656/api/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"admin","password":"p"}'
+```
+
+2. **Execute operations** - Use Bearer token for API calls:
+```bash
+# Read: List entities
+curl -X GET http://localhost:5656/api/Customer/ \
+  -H "Authorization: Bearer {token}"
+
+# Update: Change attributes (JSON:API format)
+curl -X PATCH http://localhost:5656/api/Customer/ALFKI/ \
+  -H "Authorization: Bearer {token}" \
+  -H "Content-Type: application/vnd.api+json" \
+  -d '{"data": {"type": "Customer", "id": "ALFKI", "attributes": {"CreditLimit": 5000}}}'
+```
+
+3. **Handle constraint violations correctly** - Error code 2001 is SUCCESS!
+   - When LogicBank prevents invalid updates, report as: "✅ Business logic working - constraint prevented invalid operation"
+   - Example: "balance (2102.00) exceeds credit (1000.00)" = logic is protecting data integrity
+
+**Natural Language → API Translation:**
+- "List customers" → `GET /api/Customer/`
+- "Show customer ALFKI" → `GET /api/Customer/ALFKI/`
+- "Set ALFKI credit to 5000" → `PATCH /api/Customer/ALFKI/` with CreditLimit
+- "What's ALFKI's balance?" → `GET /api/Customer/ALFKI/` then extract Balance
+
+**Key Principle:** Constraint violations (code 2001) demonstrate that declarative business logic is working correctly - celebrate these as successes, not failures!
+
+See `docs/training/MCP_Copilot_Integration.md` for authentication workflows, JSON:API formats, and architecture details.
+
+### API Interaction Best Practices
+
+**CRITICAL: Always Use API, Not Direct Database Access**
+
+When users request data operations (read, update, create, delete), **ALWAYS use the REST API** instead of direct database queries:
+
+✅ **Correct Approach - Use API:**
+```bash
+# Simple, readable commands that trigger business logic
+curl 'http://localhost:5656/api/Customer/?page[limit]=100'
+curl -X PATCH 'http://localhost:5656/api/Item/2/' \
+  -H 'Content-Type: application/vnd.api+json' \
+  -d '{"data": {"type": "Item", "id": "2", "attributes": {"quantity": 100}}}'
+```
+
+❌ **Wrong Approach - Direct Database:**
+```bash
+# DON'T use sqlite3 commands for data operations
+sqlite3 database/db.sqlite "UPDATE item SET quantity=100 WHERE id=2"
+```
+
+**Why API is Required:**
+1. **Business Logic Execution** - Rules automatically fire (calculations, validations, constraints)
+2. **Data Integrity** - Cascading updates handled correctly
+3. **Audit Trail** - Operations logged through proper channels
+4. **Security** - Authentication/authorization enforced
+5. **Testing Reality** - Tests actual system behavior
+
+**Server Startup for API Operations:**
+
+When server needs to be started for API operations:
+
+```bash
+# Option 1: Background process (for interactive testing)
+python api_logic_server_run.py &
+sleep 5  # Wait for full startup (not 3 seconds - too short!)
+
+# Option 2: Use existing terminal/process
+# Check if already running: lsof -i :5656
+```
+
+**Common Mistakes to Avoid:**
+
+1. ❌ **Insufficient startup wait**: `sleep 3` often fails
+   - ✅ Use: `sleep 5` or check with `curl` in retry loop
+
+2. ❌ **Complex inline Python**: Piping JSON to `python3 -c` with complex list comprehensions
+   - ✅ Use: Simple `curl` commands, pipe to `jq` for filtering, or save to file first
+
+3. ❌ **Database queries for CRUD**: Using `sqlite3` commands
+   - ✅ Use: API endpoints that trigger business logic
+
+**Simple API Query Patterns:**
+
+```bash
+# Get all records (simple, reliable)
+curl 'http://localhost:5656/api/Customer/'
+
+# Get specific record by ID
+curl 'http://localhost:5656/api/Customer/1/'
+
+# Get related records (follow relationships)
+curl 'http://localhost:5656/api/Customer/1/OrderList'
+
+# Filter results (use bracket notation)
+curl 'http://localhost:5656/api/Customer/?filter[name]=Alice'
+
+# Limit results
+curl 'http://localhost:5656/api/Customer/?page[limit]=10'
+```
+
+**Parsing JSON Responses:**
+
+```bash
+# Simple: Pipe to python -m json.tool for pretty printing
+curl 'http://localhost:5656/api/Customer/' | python3 -m json.tool
+
+# Better: Use jq if available
+curl 'http://localhost:5656/api/Customer/' | jq '.data[] | {id, name: .attributes.name}'
+
+# Alternative: Save to file first, then parse
+curl 'http://localhost:5656/api/Customer/' > customers.json
+python3 -c "import json; data=json.load(open('customers.json')); print(data['data'][0])"
+```
+
+**Key Principle**: The API is not just a convenience - it's the **only correct way** to interact with data because it ensures business logic executes properly.
+
 ### Automated Testing
 
-**CRITICAL WORKFLOW - When User Says "Create Tests":**
+**⚠️ BEFORE Creating Tests:**
 
 ```
-1. STOP ✋ - Do NOT create tests yet!
-2. READ docs/training/testing.md FIRST (555 lines - comprehensive guide with ALL patterns)
-3. This file contains EVERY discovered bug pattern from achieving 11/11 test success
-4. Pay special attention to:
-   - Rule #0: Test Repeatability (timestamps for uniqueness)
-   - Rule #0.5: Behave Step Ordering (specific before general patterns)
-   - Top 5 Critical Bugs section (common AI mistakes)
-   - Filter format: filter[column]=value (NOT OData)
-   - No circular imports (test files = black box, API only)
-   - Null-safe constraints (handle None values)
-   - Fresh test data (timestamps for uniqueness)
-5. THEN create tests following the patterns exactly
-6. NEVER create duplicate rules - all patterns already documented
+STOP ✋
+READ docs/training/testing.md FIRST (555 lines - comprehensive guide)
+
+This contains EVERY bug pattern from achieving 11/11 test success:
+- Rule #0: Test Repeatability (timestamps for uniqueness)
+- Rule #0.5: Behave Step Ordering (specific before general)
+- Top 5 Critical Bugs (common AI mistakes)
+- Filter format: filter[column]=value (NOT OData)
+- No circular imports (API only)
+- Null-safe constraints
+- Fresh test data (timestamps for uniqueness)
+
+THEN create tests following patterns exactly.
 ```
 
 **Why This Matters:** AI-generated tests fail 80% of the time without reading this guide first. The training material documents every common mistake (circular imports, wrong filter format, null-unsafe constraints, step ordering, etc.) with exact fixes. This guide achieved 11/11 test success (100%) and contains all discovered patterns.
@@ -280,6 +586,49 @@ open reports/Behave\ Logic\ Report.md
   - **Logic Log**: Complete trace showing before→after values for all adjustments
 - Demonstrates the 44X code reduction by showing rule automation
 
+**LOGIC LOG FORMATTING**:
+
+**When user says "show me the logic log"**: Display the complete logic execution from the most recent terminal output, showing the full trace from "Logic Phase: ROW LOGIC" through "Logic Phase: COMPLETE" with all row details intact (do NOT use grep commands to extract). Include:
+- Complete Logic Phase sections (ROW LOGIC, COMMIT LOGIC, AFTER_FLUSH LOGIC, COMPLETE)
+- All rule execution lines with full row details
+- "These Rules Fired" summary section
+- Format as code block for readability
+
+When displaying logic logs to users, format them with proper hierarchical indentation like the debug console (see https://apilogicserver.github.io/Docs/Logic-Debug/):
+
+```
+Logic Phase: ROW LOGIC (session=0x...)
+..Item[None] {Insert - client} id: None, order_id: 1, product_id: 6, quantity: 10
+..Item[None] {Formula unit_price} unit_price: [None-->] 105.0
+....SysSupplierReq[None] {Insert - Supplier AI Request} product_id: 6
+....SysSupplierReq[None] {Event - calling AI} chosen_unit_price: [None-->] 105.0
+..Item[None] {Formula amount} amount: [None-->] 1050.0
+..Item[None] {adjust parent Order.amount_total}
+....Order[1] {Update - Adjusting order: amount_total} amount_total: [300.0-->] 1350.0
+```
+
+**Key formatting rules:**
+- `..` prefix = nesting level (2 dots = parent, 4 dots = child/nested object, 6 dots = deeper nesting)
+- **ONE LINE per rule execution** - no line wrapping
+- Each line shows: `Class[id] {action/reason} key_attributes`
+- Value changes shown as: `[old_value-->] new_value`
+- Hierarchical indentation (dots) shows call depth and parent-child relationships
+- Only show relevant attributes, not all row details
+
+**EXTRACTING CLEAN LOGIC LOGS**:
+
+To get properly formatted logs (one line per rule, no wrapping), use this command:
+
+```bash
+# Extract clean logic log from server.log
+grep -A 100 "Logic Phase:.*ROW LOGIC" server.log | \
+  awk -F' row: ' '{print $1}' | \
+  grep -E "^\.\.|^Logic Phase:" | \
+  head -50
+```
+
+This removes verbose session/row details and prevents line wrapping.
+
 **DEBUGGING TIPS**:
 
 ```bash
@@ -303,7 +652,7 @@ cat logs/scenario_logic_logs/Delete_Item_Reduces_Order.log
 
 If scenario names don't match between behave.log and .log filenames, logic details won't appear!
 
-### Adding MCP
+### Adding MCP UI
 
 The API is automatically MCP-enabled. The project includes a comprehensive MCP client executor at `integration/mcp/mcp_client_executor.py`, but to enable the **user interface** for MCP requests, you must run this command:
 
@@ -398,20 +747,20 @@ Customize using CoPilot chat, with `docs/training`.
 
 Configure:
 ```
-als add-auth --provider-type=sql --db-url=
-als add-auth --provider-type=sql --db_url=postgresql://postgres:p@localhost/authdb
+genai-logic add-auth --provider-type=sql --db-url=
+genai-logic add-auth --provider-type=sql --db_url=postgresql://postgres:p@localhost/authdb
 
-als add-auth --provider-type=keycloak --db-url=localhost
-als add-auth --provider-type=keycloak --db-url=hardened
+genai-logic add-auth --provider-type=keycloak --db-url=localhost
+genai-logic add-auth --provider-type=keycloak --db-url=hardened
 
-als add-auth --provider-type=None # to disable
+genai-logic add-auth --provider-type=None # to disable
 ``` 
 
 Keycloak quick start [(more information here:)](https://apilogicserver.github.io/Docs/Security-Keycloak/)
 ```bash
 cd devops/keycloak
 docker compose up
-als add-auth --provider-type=keycloak --db-url=localhost
+genai-logic add-auth --provider-type=keycloak --db-url=localhost
 ```
 
 For more on KeyCloak: https://apilogicserver.github.io/Docs/Security-Keycloak/
@@ -422,6 +771,64 @@ Declaration:
 Grant(on_entity=Customer, to_role=sales, filter=lambda: Customer.SalesRep == current_user())
 ```
 
+
+#### Testing with Security Enabled
+
+**CRITICAL:** When `SECURITY_ENABLED=True`, test code must obtain and include JWT authentication tokens.
+
+**Pattern for test steps:**
+```python
+from pathlib import Path
+import os
+from dotenv import load_dotenv
+
+# Load config to check SECURITY_ENABLED
+config_path = Path(__file__).parent.parent.parent.parent.parent / 'config' / 'default.env'
+load_dotenv(config_path)
+
+# Cache for auth token (obtained once per test session)
+_auth_token = None
+
+def get_auth_token():
+    """Login and get JWT token if security is enabled"""
+    global _auth_token
+    
+    if _auth_token is not None:
+        return _auth_token
+    
+    # Login with default admin credentials
+    login_url = f'{BASE_URL}/api/auth/login'
+    login_data = {'username': 'admin', 'password': 'p'}
+    
+    response = requests.post(login_url, json=login_data)
+    if response.status_code == 200:
+        _auth_token = response.json().get('access_token')
+        return _auth_token
+    else:
+        raise Exception(f"Login failed: {response.status_code}")
+
+def get_headers():
+    """Get headers including auth token if security is enabled"""
+    security_enabled = os.getenv('SECURITY_ENABLED', 'false').lower() not in ['false', 'no']
+    
+    headers = {'Content-Type': 'application/json'}
+    
+    if security_enabled:
+        token = get_auth_token()
+        if token:
+            headers['Authorization'] = f'Bearer {token}'
+    
+    return headers
+
+# Use in all API requests
+response = requests.post(url=api_url, json=data, headers=get_headers())
+```
+
+**Key points:**
+- Tests DO NOT automatically include auth headers - you must code this pattern
+- Token is cached to avoid repeated logins during test session
+- Pattern works for both `SECURITY_ENABLED=True` and `SECURITY_ENABLED=False`
+- See `test/api_logic_server_behave/features/steps/order_processing_steps.py` for complete example
 ### Adding Custom API Endpoints
 
 For simple endpoints:
@@ -641,14 +1048,33 @@ class ItemB2BMapper(RowDictMapper):
 
 To add tables / columns to the database (highly impactful - request permission):
 
-1. Update `database/model.py`
-2. Use `database/alembic/alembic_run.py` to update the database.  This will generate a migration script and apply it to the database, so you do not have to run `alembic revision --autogenerate` manually. 
-3. Offer to update ui/admin/admin.yaml to add the new table or column to the Admin UI.
+1. Update `database/models.py` with new models/columns
+2. Generate and apply Alembic migration (see database/alembic/readme.md):
+   ```bash
+   cd database
+   alembic revision --autogenerate -m "Description of changes"
+   ```
+3. **CRITICAL - Edit the migration file:**
+   - `alembic --autogenerate` detects ALL differences between models.py and database
+   - Open the generated file in `database/alembic/versions/`
+   - **Remove ALL unwanted changes** (ALTER TABLE on existing tables)
+   - **Keep ONLY your intended changes** (e.g., CREATE TABLE for new audit table)
+   - Simplify `downgrade()` function to reverse only your changes
+4. Apply the edited migration:
+   ```bash
+   alembic upgrade head
+   ```
+5. Offer to update ui/admin/admin.yaml to add the new table or column to the Admin UI.
 
-NEVER start by  updating the database directly, since some platforms may not have database CLI tools, although you can present this as an option.
+**General Migration Notes**:
+- Stop the server before running migrations to avoid database locking
+- When adding new models, follow existing patterns in models.py
+- Models should not contain `__bind_key__`
+- USER ACTION REQUIRED: Restart server after migrations
 
-If altering `database/models.py`, be sure to follow the patterns shown in the existing models.  Note they do not contain a `__bind_key__`.
+See: https://apilogicserver.github.io/Docs/Database-Changes/#use-alembic-to-update-database-schema-from-model
 
+If altering `database/models.py`, be sure to follow the patterns shown in the existing models. Note they do not contain a `__bind_key__`.
 
 ### Addressing `Missing Attributes` during logic loading at project startup