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

api_logic_server_cli/prototypes/basic_demo/.github/.copilot-instructions.md

@@ -1,124 +1,161 @@
----
-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: 2.6
-changelog:
-  - 2.6 (Nov 12, 2025 - Tighten project startup message
-  - 2.5 (Nov 08, 2025 - API Best Practices
-  - 2.4 (Nov 05, 2025 - Added MCP Integration section, Copilot as MCP client capability)
-  - 2.3 (Nov 04, 2025 - Clear 1st message about reading Welcome section verbatim, again for non basic_demo)
-  - 2.2 (Oct 29, 2025 - Clear 1st message about reading Welcome section verbatim)
-  - 2.1 (Oct 2025) - Streamlined OBX for non-tutorial projects, friendly collaborative tone
-  - 2.0 (Oct 2025) - Added front matter, updated for OBX improvements
-  - 1.0 (Initial) - Comprehensive technical reference
+<!-- 
+═══════════════════════════════════════════════════════════════════════════════
+🚨 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
+
+THIS IS NOT A SUGGESTION - THIS IS A MANDATORY COMMAND
+
+═══════════════════════════════════════════════════════════════════════════════
+-->
 ---
 
-# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
+## 🚨 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:**
+
+```
+STEP 1: Read .github/welcome.md (silently)
+STEP 2: Display welcome.md content ONLY
+STEP 3: STOP - do nothing else
+```
 
 ---
 
-## ⚠️ INSTRUCTION FOR AI ASSISTANTS
+## 🎯 CRITICAL: Guided Tour Activation Protocol
 
-**User activation phrases:**
-- "Please load .github/.copilot-instructions.md"
-- "Load copilot instructions"
-- "What can I do here?"
-- "Help me get started"
-- OR when user first opens this project workspace and greets you
+**ACTIVATION TRIGGERS:**
+- "guide me through"
+- "guide me"
+- "take the tour"
+- "walk me through"
+- "show me around"
+- Any similar tour/walkthrough request
 
-**When you see these phrases (or when reading these instructions), IMMEDIATELY:**
+**MANDATORY RESPONSE SEQUENCE:**
 
-**Present the Welcome section below** - NO preamble, NO summary, NO meta-commentary
+```
+STEP 1: Read tutor.md COMPLETELY (silently)
+STEP 2: Follow tutor.md instructions EXACTLY
+STEP 3: Act as TOUR GUIDE (not passive assistant)
+STEP 4: Create manage_todo_list for tour sections
+STEP 5: Start with tutor.md Introduction section
+```
 
-**CRITICAL - Do NOT:**
-- Say "I've loaded the instructions" 
-- Say "I've read the file"
-- Summarize or describe what's in this file
-- Add any commentary about reading instructions
+**✅ CORRECT EXECUTION:**
+```
+User: "guide me"
 
-**CRITICAL - DO:**
-- Present the Welcome content directly (exactly) as your response
-- Start with: "Welcome! This is your basic_demo project."
-- Act like you're naturally greeting the user
-- Include the "guide me through" call-to-action
+AI: [reads tutor.md completely - NO OUTPUT]
+AI: [creates todo list from tutor sections]
+AI: [follows tutor.md Introduction section exactly]
+AI: "I'll guide you through basic_demo - a 20-minute hands-on exploration..."
+```
 
----
+**❌ FORBIDDEN BEHAVIORS:**
+```
+User: "guide me"
+
+❌ AI: Starts giving general guidance without reading tutor.md
+❌ AI: Runs commands without following tutor choreography
+❌ AI: Acts as passive assistant waiting for user direction
+❌ AI: Skips sections or reorders steps
+❌ AI: Offers option menus instead of directing the tour
+❌ AI: Assumes server state or skips stop/start sequences
+```
 
-## Welcome
+**RATIONALE:**
+- tutor.md contains weeks of refined choreography
+- Every command, stop, start is precisely sequenced
+- Deviations break the learning experience
+- You are the DIRECTOR in tour mode, not a passive responder
+- The tour has been engineered for AI reliability through multiple iterations
 
-**Welcome! This is your basic_demo project.**
+**✅ CORRECT EXECUTION:**
+```
+User: "load .github/.copilot-instructions.md"
 
-This is a complete, working microservice auto-generated from a database schema - **uncustomized**, so you can see what to expect when you create projects from your own databases.
+AI: [reads welcome.md silently - NO OUTPUT]
+AI: [displays ONLY this]:
 
-**What's already created from introspecting the database schema:**
-- **Admin Web Application** - Live at `http://localhost:5656`
-- **REST API Endpoints** - All database tables exposed at `/api/*`
-- **Database Models** - Complete SQLAlchemy ORM in `database/models.py`
-- **Authentication System** - JWT-based auth framework
-- **Business Logic Engine** - Declarative rules system
+## 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 ...]
+```
 
-**First, we'll briefly explore what's automatically created. Then I'll show you how I can help you customize it - adding logic, security, and API endpoints.**
+**❌ FORBIDDEN BEHAVIORS:**
+```
+User: "load .github/.copilot-instructions.md"
 
-**Ready to learn?** Say **"guide me through"** to begin the interactive tutorial.
+❌ 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
+```
 
-**Or, self-demo?** Open `basic_demo/readme_ai_mcp.md`.
+**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"
 
 ---
 
-**DO NOT include the content below in the welcome greeting. It is reference material only.**
+## Capabilities Reference
+
+When user asks "what can I do here", list these capabilities:
 
-## Here are some things I can help you with
+### Here Are Some Things I Can Help You With
 
-1. **Add business logic** - Describe your requirements in natural language, I'll generate declarative rules
+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** - I can act as MCP client to read/update data (see `docs/training/MCP_Copilot_Integration.md`)
+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
 
-Want to get started? Press **F5** to start the server with debugger support, then open `http://localhost:5656`. (There are also run configurations for running tests and other tasks.) Or just ask me what you'd like to work on.
-
 ---
 
-## 🔑 Key Technical Points
-```
-
-**DO NOT create your own summary. DO NOT rephrase. Copy the text above exactly.**
-
-The technical reference sections below are for later consultation when working on specific tasks.
-
 ---
-
-## Welcome (Reference Copy)
-
-| # | Service | Description |
-|---|---------|-------------|
-| 1️⃣ | **Add business logic** | Describe your requirements in natural language, I'll generate declarative rules |
-| 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️⃣ | **Add MCP integration** | Enable Model Context Protocol for external AI access |
-| 8️⃣ | **Create B2B APIs** | Complex integration endpoints with partner systems |
-| 9️⃣ | **Add events** | Integrate with Kafka, webhooks, or other event systems |
-| 🔟 | **Customize models** | Add tables, attributes, or derived fields |
-| 1️⃣1️⃣ | **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
 ---
 
-Want to get started? Press **F5** to start the server with debugger support, then open `http://localhost:5656`. (There are also run configurations for running tests and other tasks.) Or just ask me what you'd like to work on.
+# GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
 
 ---
 
@@ -155,16 +192,32 @@ The sections below provide complete details on each service. I'll reference thes
 
 To establish the virtual environment:
 
-1. Attempt to find a `venv` folder in the parent or grandparent directory
-2. Or, create it using requirements.txt
+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`
 
 ### Starting the server
 
+**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:
 
@@ -174,47 +227,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):
+
+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)
+
+⚠️ 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:**
 
-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 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
 
-Here's the natural language logic to provide to CoPilot:
+**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)):
-
-<analysis>
-**LogicBank declarative rules provide a 44X reduction in code complexity** compared to traditional procedural implementations:
+**Why Declarative Rules Matter:**
 
-| 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 |
+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)
 
-**Bottom Line**: Declarative business logic eliminates complexity while providing better performance, maintainability, and business alignment.
+With declarative rules, you simply state business requirements. The engine handles dependencies, ordering, and optimization automatically.
 
-> **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
 
@@ -240,10 +346,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
 
@@ -288,13 +391,32 @@ 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 - Acting as Database Client
+### 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)
 
-**You (GitHub Copilot) can serve as an MCP client** to read and update database entities using natural language queries!
+**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
 
-**Architecture**: This project implements **MCP Server Executor** - a business logic microservice that AI assistants interact with via authenticated REST API calls. See `docs/training/MCP_Copilot_Integration.md` for complete details.
 
-**When users request database operations** (e.g., "list customers", "update credit limit", "what's the balance?"):
+**When users request data operations:**
 
 1. **Authenticate first** - Login to obtain JWT token:
 ```bash
@@ -320,15 +442,15 @@ curl -X PATCH http://localhost:5656/api/Customer/ALFKI/ \
    - 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 Translation Examples**:
+**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 attribute
+- "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!
+**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 comprehensive guide including JSON:API payload formats, authentication workflows, and architecture details.
+See `docs/training/MCP_Copilot_Integration.md` for authentication workflows, JSON:API formats, and architecture details.
 
 ### API Interaction Best Practices
 
@@ -419,22 +541,22 @@ python3 -c "import json; data=json.load(open('customers.json')); print(data['dat
 
 ### 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.
@@ -515,6 +637,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
@@ -538,7 +703,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:
 
@@ -934,14 +1099,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
 

api_logic_server_cli/prototypes/basic_demo/.github/welcome.md

@@ -21,6 +21,20 @@ This is a complete, working microservice auto-generated from a database schema -
 **First, we'll briefly explore what's automatically created. Then I'll show you how I can help you customize it - adding logic, security, and API endpoints.**
 
 
-**Ready to explore?** Open `tutor.md` and tell me "guide me through" to begin the interactive tutorial.
+**Ready to explore?** Just say me "guide me through" to begin the interactive tutorial.
+
+**Or, self-demo?** Open `readme_ai_mcp.md` to explore logic, ai and mcp.
+
+<!-- 
+⚠️ AI INSTRUCTION: When user says "guide me" or similar tour activation phrase, you MUST:
+1. Read tutor.md COMPLETELY before responding
+2. Follow tutor.md choreography EXACTLY as written
+3. Act as TOUR GUIDE directing the experience (not passive assistant)
+4. Create manage_todo_list to track tour sections
+5. Do NOT freelance, improvise, or skip sections
+
+This is MANDATORY - the tutor.md represents weeks of refined choreography.
+Deviations break the carefully engineered learning experience.
+-->
 
 ---