ApiLogicServer 15.3.2__py3-none-any.whl → 15.4.0__py3-none-any.whl

api_logic_server_cli/prototypes/base/logic/readme_logic.md

@@ -1,12 +1,12 @@
 This describes how to use Logic; for more information, [see here](https://apilogicserver.github.io/Docs/Logic-Why).
 
-> What is Logic: Multi-table Derivation and Constraint Rules, Extensible with Python 
-<br>Rules are:
-<br>1. **Declared** in your IDE - 40X more concise
-<br>2. **Activated** on server start
-<br>3. **Executed** - *automatically* -  on updates (using SQLAlchemy events)
-<br>4. **Debugged** in your IDE, and with the console log
-<br>For more on rules, [click here](https://apilogicserver.github.io/Docs/Logic-Why/).
+> What is Logic: Multi-table Derivation and Constraint Rules, Extensible with Python
+> <br>Rules are:
+> <br>1. **Declared** in your IDE - 40X more concise
+> <br>2. **Activated** on server start
+> <br>3. **Executed** - *automatically* -  on updates (using SQLAlchemy events)
+> <br>4. **Debugged** in your IDE, and with the console log
+> <br>For more on rules, [click here](https://apilogicserver.github.io/Docs/Logic-Why/).
 
 &nbsp;
 
@@ -27,11 +27,13 @@ Use case: App Integration
 ```
 
 Basic process:
+
 1. Create a file such as `logic/logic_discovery/check_credit.py` (e.g., copy from `use_case.py`).
-2. Paste the prompt above into CoPilot - use `docs/training` to generate logic
+2. Paste the prompt above into CoPilot - it uses `docs/training` to generate logic
 3. Paste the generated logic into `logic/logic_discovery/check_credit.py`
 
 From the Natural Language, Copilot will create Python rules (you can also create these directly using code completion):
+
 ```python
     if os.environ.get("WG_PROJECT"):
         # Inside WG: Load rules from docs/expprt/export.json
@@ -67,7 +69,7 @@ From the Natural Language, Copilot will create Python rules (you can also create
 
 ## Natural Language vs. IDE
 
-If you are using WebGenAI, you can specify rules in Natural Language. You can also augment them in the IDE using code completion.  There are some important usage guidelines.  
+If you are using WebGenAI, you can specify rules in Natural Language. You can also augment them in the IDE using code completion.  There are some important usage guidelines.
 
 > You should generally not alter any files in the `wg_rules` directory.  For more information, see [WebGenAI](https://apilogicserver.github.io/Docs/WebGenAI/), and [WebGenAI Logic](https://apilogicserver.github.io/Docs/WebGenAI-CLI.md#natural-language-logic).
 
@@ -79,7 +81,7 @@ You can declare logic in `declare_logic.py`,
 but that can lead to a lot of rules in 1 file.
 
 A *best practice* is to create logic files in `logic/logic_discovery`,
-named after the use case (e.g., `check_credit.py`).  
+named after the use case (e.g., `check_credit.py`).
 
 The easiest way to to copy/paste `use_case.py` to a new file, then
 add your logic either by Natural Language (use your Coding Assistant, such as CoPilot),
@@ -87,8 +89,10 @@ or your IDE's code completion.
 
 <br>
 
-## Examples      
+## Examples
+
 Examples from tutorial project:
+
 * Examples drawn from [tutorial project](https://github.com/ApiLogicServer/demo/blob/main/logic/declare_logic.py)
 * Use Shift + "." to view in project mode
 
@@ -105,11 +109,13 @@ This declares the Customer.Balance as the sum of the unshipped Order.AmountTotal
             as_sum_of=models.Order.AmountTotal,
             where=lambda row: row.ShippedDate is None)
 ```
+
 It means the rule engine **watches** for these changes:
+
 * Order inserted/deleted, or
 * AmountTotal or ShippedDate or CustomerID changes
 
-Iff changes are detected, the engine **reacts** by *adjusting* the Customer.Balance.  SQLs are [optimized](#declarative-logic-important-notes).
+Iff changes are detected, the engine **reacts** by *adjusting* the Customer.Balance.  SQLs are [optimized - see Important Notes, below](#declarative-logic-important-notes).
 
 This would **chain** to check the Customers' Constraint rule, described below.
 
@@ -120,6 +126,7 @@ This would **chain** to check the Customers' Constraint rule, described below.
 Constraints are multi-field conditions which must be true for transactions to succeed (else an exception is raised).  You can express the condition as a lambda or a function:
 
 **As a lambda:**
+
 ```python
     Rule.constraint(validate=models.Customer,
         as_condition=lambda row: row.Balance <= row.CreditLimit,  # parent references are supported
@@ -127,6 +134,7 @@ Constraints are multi-field conditions which must be true for transactions to su
 ```
 
 **Or, as a function:**
+
 ```python
     def check_balance(row: models.Customer, old_row: models.Customer, logic_row: LogicRow):
         if logic_row.ins_upd_dlt != "dlt":  # see also: logic_row.old_row
@@ -144,12 +152,14 @@ Constraints are multi-field conditions which must be true for transactions to su
 ### 3. Row Events: Extensible with Python
 
 Events are procedural Python code, providing extensibility for declarative rules:
+
 ```python
     def congratulate_sales_rep(row: models.Order, old_row: models.Order, logic_row: LogicRow):
         pass  # event code here - sending email, messages, etc.
 
     Rule.commit_row_event(on_class=models.Order, calling=congratulate_sales_rep)
 ```
+
 Note there are multiple kinds of events, so you can control whether they run before or after rule execution.  For more information, [see here](https://apilogicserver.github.io/Docs/Logic-Type-Constraint).
 
 &nbsp;
@@ -159,9 +169,7 @@ Note there are multiple kinds of events, so you can control whether they run bef
 A key argument to functions is `logic_row`:
 
 * **Wraps row and old_row,** plus methods for insert, update and delete - rule enforcement
-
 * **Additional instance variables:** ins_upd_dlt, nest_level, session, etc.
-
 * **Helper Methods:** are_attributes_changed, set_same_named_attributes, get_parent_logic_row(role_name), get_derived_attributes, log, is_inserted, etc
 
 Here is an example:
@@ -194,13 +202,11 @@ logic_row.log("no manager for this order's salesrep")
 Logic *declarative*, which differs from conventional *procedural* logic:
 
 1. **Automatic Invocation:** you don't call the rules; they execute in response to updates (via SQLAlchemy events).
-
 2. **Automatic Ordering:** you don't order the rules; execution order is based on system-discovered depencencies.
-
 3. **Automatic Optimizations:** logic is optimized to reduce SQLs.
 
-    * Rule execution is *pruned* if dependent attributes are not altered
-    * SQL is optimized, e.g., `sum` rules operate by *adjustment*, not expensive SQL `select sum`
+   * Rule execution is *pruned* if dependent attributes are not altered
+   * SQL is optimized, e.g., `sum` rules operate by *adjustment*, not expensive SQL `select sum`
 
 These simplify maintenance / iteration: you can be sure new logic is always called, in the correct order.
 
@@ -226,14 +232,15 @@ Logging is performed using standard Python logging, with a logger named `logic_l
 
 In addition, the system logs all rules that fire, to aid in debugging.  Referring the the screen shot above:
 
-*   Each line represents a rule execution, showing row state (old/new values), and the _{reason}_ that caused the update (e.g., client, sum adjustment)
-*   Log indention shows multi-table chaining
+* Each line represents a rule execution, showing row state (old/new values), and the _{reason}_ that caused the update (e.g., client, sum adjustment)
+* Log indention shows multi-table chaining
 
 &nbsp;
 
 ## How Logic works
 
 *Activation* occurs in `api_logic_server_run.py`:
+
 ```python
     LogicBank.activate(session=session, activator=declare_logic, constraint_event=constraint_handler)
 ```
@@ -242,8 +249,14 @@ This installs the rule engine as a SQLAlchemy event listener (`before_flush`).
 
 Rules plug into SQLAlchemy events, and execute as follows:
 
-| Logic Phase | Why It Matters |
-|:-----------------------------|:---------------------|
-| **Watch** for changes at the attribute level | Performance - Automatic Attribute-level Pruning |
-| **React** by recomputing value | Ensures Reuse - Invocation is automatic<br>Derivations are optimized (e.g. *adjustment updates* - not aggregate queries) |
-| **Chain** to other referencing data | Simplifies Maintenance - ordering is automatic<br>Multi-table logic automation |
+
+| Logic Phase                                  | Why It Matters                                                                                                           |
+| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
+| **Watch** for changes at the attribute level | Performance - Automatic Attribute-level Pruning                                                                          |
+| **React** by recomputing value               | Ensures Reuse - Invocation is automatic<br>Derivations are optimized (e.g. *adjustment updates* - not aggregate queries) |
+| **Chain** to other referencing data          | Simplifies Maintenance - ordering is automatic<br>Multi-table logic automation                                           |
+
+This pattern is sometimes called Reactive Dependency Propagation.  Automatic dependency management accounts is why 5 *declarative* lines represent the same logic as 200 lines of *declarative* Python
+
+1. To view a AI procedural/declarative comparison, [click here](https://github.com/ApiLogicServer/ApiLogicServer-src/blob/main/api_logic_server_cli/prototypes/basic_demo/logic/procedural/declarative-vs-procedural-comparison.md)
+2. Rules typically automate over 95% of your logic, so the results can be significant.  Consider a 100 table system: 1,000 rules vs. 40,000 lines of code

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

@@ -1,21 +1,24 @@
 ---
-title: Copilot Instructions for basic_demo Project
-Description: Project-level instructions for AI assistants conducting guided tours
-Source: ApiLogicServer-src/prototypes/basic_demo/.github/.copilot-instructions.md
-Propagation: CLI create command → created projects
-Usage: AI assistants read this when user says "guide me through"
-version: 2.3
+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 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
 changelog:
-  - 2.4 10/28/2025 - Added "Ready to explore?" prompt to guide user to tutor.md
-  - 2.3 (Oct 2025) - Added positive instruction: respond WITH Welcome section content
-  - 2.2 (Oct 2025) - Removed meta-instruction; let structure speak for itself
-  - 2.1 (Oct 2025) - Streamlined OBX, emphasized uncustomized template, friendly collaborative tone
-  - 2.0 (Oct 2025) - Added provocation method, spreadsheet analogy, timing checkpoints
+  - 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
 ---
 
 # GitHub Copilot Instructions for GenAI-Logic (aka API Logic Server) Projects
 
-**INSTRUCTION**: When the user asks you to read 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.
+**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".
 
 ## Welcome
 
@@ -34,25 +37,100 @@ 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?** Say **"guide me through"** to begin the interactive tutorial.
 
-**Ready to explore?** Open `tutor.md` and tell me "guide me through" to begin the interactive tutorial.
+**Or, self-demo?** open `basic_demo/readme_ai_mcp.md` or `basic_demo/readme_vibe.md`.
 
 ---
 
-## Technical Reference (For AI Assistant - Do Not Present to User Unless Asked)
+**DO NOT include the content below in the welcome greeting. It is reference material only.**
 
-The sections below contain detailed technical information for when we're actively working on specific tasks. These are reference materials, not introductory content.
+## Here are some things I can help you with
+
+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. **Query via natural language** - I can act as MCP client to read/update data (see `docs/training/MCP_Copilot_Integration.md`)
+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 |
+
+---
+
+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
+
+**Critical Implementation Details:**
+
+1. **Discovery Systems**: 
+   - **Logic Discovery**: Business rules automatically loaded from `logic/logic_discovery/use_case.py` via `logic/logic_discovery/auto_discovery.py`
+   - **API Discovery**: Custom APIs automatically loaded from `api/api_discovery/[service_name].py` via `api/api_discovery/auto_discovery.py`
+   - Do NOT manually duplicate rule calls or API registrations
+
+2. **API Record ID Pattern**: When creating records via custom APIs, use `session.flush()` before accessing the ID to ensure it's generated:
+   ```python
+   session.add(sql_alchemy_row)
+   session.flush()  # Ensures ID is generated
+   record_id = sql_alchemy_row.id
+   return {"message": "Success", "record_id": record_id}
+   ```
+
+3. **Automatic Business Logic**: All APIs (standard and custom) automatically inherit LogicBank rules without additional code.
+
+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)
 
 ---
 
-I'll present these as choices - we'll tackle them one at a time.
+## Detailed Service Documentation
 
-### Set Up Virtual Environment
-If it's not already set, we can often find a `venv` in the GenAI-Logic Manager - a parent or grandparent directory.
+The sections below provide complete details on each service. I'll reference these as needed when we work together.
 
-### 🚀 To Run This Project
+### `venv` is required
 
-Use F5 (pre-configured run configuration - supports debugger for server logic), or (when focused on client apps):
+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
+
+### Starting the server
 
 ```bash
 python api_logic_server_run.py
@@ -182,6 +260,135 @@ 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
+
+**You (GitHub Copilot) can serve as an MCP client** to read and update database entities using natural language queries!
+
+**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?"):
+
+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 Translation Examples**:
+- "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
+
+**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.
+
+### 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":**
@@ -398,20 +605,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 +629,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:

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

@@ -0,0 +1,26 @@
+---
+use: welcome for basic_demo - please start the tour
+instuctions: copy api_logic_server_cli/prototypes/base/.github/.copilot-instructions.md, then paste as the Welcome section 
+---
+
+## Welcome
+
+**Welcome! This is your basic_demo project.**
+
+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.
+
+**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
+
+---
+
+**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.
+
+---

api_logic_server_cli/prototypes/basic_demo/customizations/logic/declare_logic.py

@@ -47,7 +47,12 @@ def declare_logic():
 
             Use case: App Integration
                 1. Send the Order to Kafka topic 'order_shipping' if the date_shipped is not None.
+    
     Also, using logic/logic_discovery is a Best Practice - see logic/readme_logic.md
+
+    The 5 *declarative* lines below represent the same logic as 200 lines of *declarative* Python
+        1. To view the AI procedural/declarative comparison, [click here](https://github.com/ApiLogicServer/ApiLogicServer-src/blob/main/api_logic_server_cli/prototypes/basic_demo/logic/procedural/declarative-vs-procedural-comparison.md)
+        2. Consider a 100 table system: 1,000 rules vs. 40,000 lines of code
     '''
     from database.models import Product, Order, Item, Customer, SysEmail