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

api_logic_server_cli/add_cust/add_cust.py

@@ -270,8 +270,12 @@ def add_cust(project: Project, models_py_path: Path, project_name: str):
             add_basic_demo_customizations(project=project)
             check_credit_path = project.project_directory_path.joinpath('logic/logic_discovery/check_credit.py')
             if check_credit_path.exists():
-                check_credit_path.unlink()
-                log.debug(f'.. .. ..Deleted logic_discovery/check_credit.py (from readme_ai_mcp)')
+                check_credit_path.rename(check_credit_path.with_suffix('.pyZ'))
+                log.debug(f'.. .. ..Renamed logic_discovery/check_credit.py to .pyZ (from readme_ai_mcp)')
+            supplier_selection_path = project.project_directory_path.joinpath('logic/logic_discovery/ai_requests/supplier_selection.py')
+            if supplier_selection_path.exists():
+                supplier_selection_path.rename(supplier_selection_path.with_suffix('.pyZ'))
+                log.debug(f'.. .. ..Renamed logic_discovery/ai_requests/supplier_selection.py to .pyZ (from readme_ai_mcp)')
         else:
             add_basic_demo_iteration(project=project)
 

api_logic_server_cli/api_logic_server.py

@@ -12,10 +12,11 @@ ApiLogicServer CLI: given a database url, create [and run] customizable ApiLogic
 Called from api_logic_server_cli.py, by instantiating the ProjectRun object.
 '''
 
-__version__ = "15.04.01"  # last public release: 15.04.00
+__version__ = "16.00.00"  # last public release: 15.04.01
 recent_changes = \
     f'\n\nRecent Changes:\n' +\
-    "\t11/01/2025 - 15.04.01: Allow for demo_ai_mcp then tutorial \n"\
+    "\t11/21/2025 - 16.00.00: Probabalistic logic - see basic_demo/readme_ai_mcp.md \n"\
+    "\t11/12/2025 - 15.04.03: Copilot rules on updates, tighter basic_demo startup, allow for demo_ai_mcp/then tutorial \n"\
     "\t11/08/2025 - 15.04.00: Nat lang Copilot data access, fix Manager/Copilot startup, finding venv in project \n"\
     "\t10/29/2025 - 15.03.00: Stable Tutor 3.3 (working, vibe transtion) \n"\
     "\t10/26/2025 - 15.02.07: Clarify order created for ship test, security fixes [105], tutor 2.1 \n"\

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

@@ -3,32 +3,57 @@ title: Copilot Instructions for GenAI-Logic Projects
 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 here to api_logic_server_cli/prototypes/basic_demo/.github - see instructions there
+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.5
+version: 3.0
 changelog:
-  - 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
+  - 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
 
-**INSTRUCTION**: When the user asks you to load these instructions, respond with the Welcome section content below as your greeting. Do not add preamble like "I've read the instructions" - just present the Welcome content directly. The Welcome section ends at the "---" marker before "🔑 Key Technical Points".
+---
+
+## ⚠️ INSTRUCTION FOR AI ASSISTANTS
+
+**Interaction Tone:** I (Copilot) speak as "I" when helping you. This creates a friendly, collaborative partnership where I assist with your development work.
+
+**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
+
+**When you see these phrases (or when reading these instructions), IMMEDIATELY:**
+
+**Present the Welcome section below** - NO preamble, NO summary, NO meta-commentary
+
+**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
+
+**CRITICAL - DO:**
+- Present the Welcome content directly (exactly) as your response
+- Start with: "Welcome! This is your GenAI-Logic project."
+- Act like you're naturally greeting the user
+- Include the "guide me through" call-to-action
+
+---
 
 ## Welcome
 
-**Welcome! I'm here to help with your GenAI-Logic project.**
+**Welcome! This is your GenAI-Logic project.**
 
 This is a complete, working microservice auto-generated from your database schema.
 
 **What's already built:**
 - **Admin Web Application** - Live at `http://localhost:5656`
-- **REST API Endpoints** - All database tables exposed at `/api/*`
+- **REST API Endpoints** - All database tables exposed at `/api/*` (discoverable by MCP clients)
 - **Database Models** - Complete SQLAlchemy ORM in `database/models.py`
 - **Authentication System** - JWT-based auth framework
 - **Business Logic Engine** - Declarative rules system
@@ -37,18 +62,20 @@ This is a complete, working microservice auto-generated from your database schem
 
 ## 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.
 
 ---
@@ -117,16 +144,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:
 
@@ -136,47 +179,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
 
@@ -202,10 +298,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
 
@@ -250,13 +343,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)
 
-**You (GitHub Copilot) can serve as an MCP client** to read and update database entities using natural language queries!
+**ALWAYS start with the standard MCP discovery endpoint:**
 
-**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.
+```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 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
@@ -282,15 +394,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
 
@@ -381,22 +493,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.
@@ -477,6 +589,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
@@ -500,7 +655,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:
 
@@ -896,14 +1051,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/base/docs/training/MCP_Copilot_Integration.md

@@ -40,6 +40,34 @@ GitHub Copilot can serve as an interactive MCP client by:
 3. **Executing** - Make authenticated HTTP calls
 4. **Reporting** - Present results or explain constraint violations
 
+## ⚠️ CRITICAL SAFETY RULES FOR COPILOT
+
+**When acting as MCP client, Copilot MUST follow these rules:**
+
+### Rule 1: NEVER Update Data Without Explicit Permission
+- ❌ **WRONG**: User asks "update quantity to 100" → fails constraint → Copilot changes credit limit to make it work
+- ✅ **CORRECT**: User asks "update quantity to 100" → fails constraint → Copilot reports the constraint violation and asks what to do
+
+### Rule 2: Constraint Violations Are SUCCESS, Not Problems to Bypass
+- When update returns error code 2001, this demonstrates business logic is **working correctly**
+- **DO NOT** try to "fix" constraints by modifying other data
+- **DO** report: "✅ Business logic prevented this operation because [reason]"
+
+### Rule 3: Only Perform the Requested Operation
+- If user asks to update Field A, **only update Field A**
+- Do not modify Field B, Field C, or related entities to "help" the operation succeed
+- Let business rules enforce constraints - that's their job!
+
+### Rule 4: Ask Permission for Side Effects
+- Before updating any data beyond what user explicitly requested, **ask first**
+- Example: "The credit limit constraint is blocking this. Would you like me to increase the credit limit to allow it?"
+
+### Rule 5: Read Operations Are Safe, Write Operations Require Care
+- GET requests are safe to execute
+- PATCH/POST/DELETE require user's explicit instruction for each field being modified
+
+**Why These Rules Matter**: When demonstrating to customers, accidentally modifying their data (even to "help") destroys trust and demonstrates poor AI safety practices.
+
 ## Copilot Usage Pattern
 
 ### Step 1: Authentication

api_logic_server_cli/prototypes/base/docs/training/OVERVIEW.md

@@ -0,0 +1,64 @@
+# Training Documentation Overview
+
+## Purpose
+
+This folder contains **generic, reusable training materials** for ApiLogicServer projects with GenAI integration.
+
+## Critical Principle
+
+**⚠️ ALL FILES IN THIS FOLDER MUST BE PROJECT-AGNOSTIC**
+
+- ✅ Generic patterns that apply to ANY ApiLogicServer project
+- ✅ Universal LogicBank API documentation
+- ✅ Framework-level integration patterns
+- ❌ **NEVER include project-specific details** (file names, use cases, workflows)
+- ❌ **NEVER reference project-specific files** (like readme_probabilistic.md)
+
+## Intended Use
+
+These training files are:
+1. **Read by AI assistants** (GitHub Copilot, ChatGPT) via `.github/.copilot-instructions.md`
+2. **Copied to new projects** when creating similar systems
+3. **Maintained centrally** and propagated across projects
+
+## File Organization
+
+- **`*.prompt`** - API documentation and pattern libraries for AI consumption
+- **`*_guide.md`** - Human-readable implementation guides
+- **`template_*.py`** - Working code examples (generic patterns only)
+- **`testing.md`** - Universal testing patterns and conventions
+- **`README.md`** - Navigation and file descriptions
+
+## Adding New Content
+
+When adding training materials:
+
+1. **Ask: "Does this apply to ALL projects?"**
+   - If YES → Add here
+   - If NO → Keep in project root (e.g., `readme_*.md`)
+
+2. **Use generic examples:**
+   - ✅ "Customer/Order/Item" domain
+   - ✅ "SysXxxReq" audit table pattern
+   - ❌ Specific product names, table names, or use cases
+
+3. **Remove project context:**
+   - No mentions of "PDL project"
+   - No references to project-specific scripts
+   - No project-specific file paths
+
+## Maintenance
+
+This folder should be **stable and rarely changed**. Updates typically come from:
+- LogicBank API changes
+- New universal patterns discovered
+- Framework architecture improvements
+
+**NOT from:**
+- Project-specific implementations
+- One-off use cases
+- Debugging specific projects
+
+---
+
+**Remember:** If you're describing how YOUR project works, it doesn't belong here.