DOC: Fix factual errors and remove slop from LLM guidance files

- Remove nonexistent prompt file references (#setup-dev-env, #build-ddbc, etc.)
- Remove duplicated usage examples section from copilot-instructions.md
- Fix C++ style: Google -> LLVM (verified against .clang-format)
- Update pybind file tree to match actual directory contents (14 items)
- Add 3 missing GitHub workflows (lint-check, pr-code-coverage, forked-pr-coverage)
- Remove pip install black (already in requirements.txt)
- Remove Trust These Instructions section
- Remove platform-specific ODBC install section from llms.txt (bundled via pip)
- Fix undefined user_id variable in Quick Start example
- Fix except Exception -> except DatabaseError with proper import
- Remove unused Error import from error handling example
- Remove redundant code comments and trivial Access Columns by Index section
- Fix pyodbc comparison table for accuracy (pooling, Entra ID claims)
- Clarify OUTPUT params use DECLARE/EXEC/SELECT workaround (callproc() unsupported)
- Remove unverified performance claim from connection pooling
- Fix SUSE platform listing: x64 only per wiki, separate from ARM64 platforms

Author: dlevy-msft-sql

.github/copilot-instructions.md

@@ -12,92 +12,13 @@
 
 ## Development Workflows
 
-This repository includes detailed prompt files for common tasks. Reference these with `#`:
-
-| Task | Prompt | When to Use |
-|------|--------|-------------|
-| First-time setup | `#setup-dev-env` | New machine, fresh clone |
-| Build C++ extension | `#build-ddbc` | After modifying .cpp/.h files |
-| Run tests | `#run-tests` | Validating changes |
-| Create PR | `#create-pr` | Ready to submit changes |
-
 **Workflow order for new contributors:**
-1. `#setup-dev-env` → Set up venv and dependencies
-2. `#build-ddbc` → Build native extension
-3. Make your changes
-4. `#run-tests` → Validate
-5. `#create-pr` → Submit
-
-## Usage Examples (For Suggesting to Users)
-
-> **Security Note**: Examples use `TrustServerCertificate=yes` for local development with self-signed certificates. For production, remove this option to ensure proper TLS certificate validation.
-
-### Basic Connection and Query
-```python
-import mssql_python
-
-conn = mssql_python.connect(
-    "SERVER=localhost;DATABASE=mydb;Trusted_Connection=yes;Encrypt=yes;TrustServerCertificate=yes"
-)
-cursor = conn.cursor()
-cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
-rows = cursor.fetchall()
-cursor.close()
-conn.close()
-```
-
-### Context Manager (Recommended)
-```python
-with mssql_python.connect(connection_string) as conn:
-    with conn.cursor() as cursor:
-        cursor.execute("SELECT @@VERSION")
-        print(cursor.fetchone()[0])
-```
-
-### Azure SQL with Entra ID
-```python
-conn = mssql_python.connect(
-    "SERVER=myserver.database.windows.net;DATABASE=mydb;"
-    "Authentication=ActiveDirectoryInteractive;Encrypt=yes"
-)
-```
-
-### Parameterized Queries
-```python
-# Positional parameters
-cursor.execute("SELECT * FROM users WHERE email = ?", (email,))
-
-# Named parameters (pyformat)
-cursor.execute("SELECT * FROM users WHERE email = %(email)s", {"email": email})
-```
-
-### Insert with Commit
-```python
-cursor.execute("INSERT INTO users (name, email) VALUES (?, ?)", ("John", "john@example.com"))
-conn.commit()
-```
-
-### Batch Insert
-```python
-cursor.executemany("INSERT INTO users (name, email) VALUES (?, ?)", [
-    ("Alice", "alice@example.com"),
-    ("Bob", "bob@example.com"),
-])
-conn.commit()
-```
-
-### Transaction Handling
-```python
-from mssql_python import DatabaseError
-
-try:
-    cursor.execute("UPDATE accounts SET balance = balance - 100 WHERE id = ?", (from_id,))
-    cursor.execute("UPDATE accounts SET balance = balance + 100 WHERE id = ?", (to_id,))
-    conn.commit()
-except DatabaseError:
-    conn.rollback()
-    raise
-```
+1. Create and activate a virtual environment (`python -m venv .venv`)
+2. Install dependencies (`pip install -r requirements.txt`)
+3. Build the native extension (see Build System below)
+4. Make your changes
+5. Run tests (`python -m pytest -v`)
+6. Submit a PR
 
 ## Build System and Validation
 
@@ -155,7 +76,6 @@ python -m pytest tests/test_001_globals.py -v      # Basic functionality
 
 ```bash
 # Python formatting
-pip install black
 black --check --line-length=100 mssql_python/ tests/
 
 # C++ formatting
@@ -188,11 +108,18 @@ mssql_python/
 ├── helpers.py                     # Utility functions and settings
 ├── ddbc_bindings.py               # Platform-specific extension loader with architecture detection
 ├── mssql_python.pyi               # Type stubs for IDE support
+├── py.typed                       # PEP 561 type marker
 └── pybind/                        # Native extension source
     ├── ddbc_bindings.cpp          # Main C++ binding code
+    ├── ddbc_bindings.h            # Header for bindings
     ├── CMakeLists.txt             # Cross-platform build configuration
     ├── build.sh/.bat              # Platform-specific build scripts
-    └── configure_dylibs.sh        # macOS dylib configuration
+    ├── configure_dylibs.sh        # macOS dylib configuration
+    ├── logger_bridge.cpp/.hpp     # Python logging bridge
+    ├── unix_utils.cpp/.h          # Unix platform utilities
+    └── connection/                # Connection management
+        ├── connection.cpp/.h      # Connection implementation
+        └── connection_pool.cpp/.h # Connection pooling
 ```
 
 ### Platform-Specific Libraries
@@ -206,9 +133,9 @@ mssql_python/libs/
 
 ### Configuration Files
 
-- **`.clang-format`**: C++ formatting (Google style, 100 column limit)
-- **`.coveragerc`**: Coverage exclusions (main.py, setup.py, tests/)
-- **`requirements.txt`**: Development dependencies (pytest, pybind11, coverage)
+- **`.clang-format`**: C++ formatting (LLVM style, 100 column limit)
+- **`.coveragerc`**: Coverage configuration
+- **`requirements.txt`**: Development dependencies
 - **`setup.py`**: Package configuration with platform detection
 - **`pyproject.toml`**: Modern Python packaging configuration
 - **`.gitignore`**: Excludes build artifacts (*.so, *.pyd, build/, __pycache__)
@@ -218,6 +145,9 @@ mssql_python/libs/
 ### GitHub Workflows
 - **`devskim.yml`**: Security scanning (runs on PRs and main)
 - **`pr-format-check.yml`**: PR validation (title format, GitHub issue/ADO work item links)
+- **`lint-check.yml`**: Python (Black) and C++ (clang-format) linting
+- **`pr-code-coverage.yml`**: Code coverage reporting
+- **`forked-pr-coverage.yml`**: Coverage for forked PRs
 
 ### Azure DevOps Pipelines (`eng/pipelines/`)
 - **`pr-validation-pipeline.yml`**: Comprehensive testing across all platforms
@@ -253,7 +183,7 @@ The CI system tests:
 
 ## Architecture Detection and Loading
 
-The `ddbc_bindings.py` module implements sophisticated architecture detection:
+The `ddbc_bindings.py` module handles architecture detection:
 - **Windows**: Normalizes `win64/amd64/x64` → `x64`, `win32/x86` → `x86`, `arm64` → `arm64`
 - **macOS**: Runtime architecture detection, always loads from universal2 binary
 - **Linux**: Maps `x64/amd64` → `x86_64`, `arm64/aarch64` → `arm64`
@@ -298,17 +228,17 @@ Exception (base)
 - Follow RAII patterns for resource management
 - Use `py::gil_scoped_release` for blocking ODBC operations
 - Update `mssql_python.pyi` type stubs if changing Python API
-- Follow `.clang-format` style (Google style, 100 column limit)
+- Follow `.clang-format` style (LLVM style, 100 column limit)
 
 ## Debugging Quick Reference
 
 | Error | Cause | Solution |
 |-------|-------|----------|
-| `ImportError: ddbc_bindings` | Extension not built | Run `#build-ddbc` |
+| `ImportError: ddbc_bindings` | Extension not built | Build native extension (see Build System) |
 | Connection timeout | Missing env var | Set `DB_CONNECTION_STRING` |
 | `dylib not found` (macOS) | Library paths | Run `configure_dylibs.sh` |
 | `ODBC Driver not found` | Missing driver | Install Microsoft ODBC Driver 18 |
-| `ModuleNotFoundError` | Not in venv | Run `#setup-dev-env` |
+| `ModuleNotFoundError` | Not in venv | Activate virtual environment |
 
 ## Contributing Guidelines
 
@@ -323,11 +253,3 @@ Exception (base)
 3. **Test on target platform** before submitting PRs
 4. **Check CI pipeline results** for cross-platform compatibility
 
-## Trust These Instructions
-
-These instructions are comprehensive and tested. Only search for additional information if:
-- Build commands fail with unexpected errors
-- New platform support is being added
-- Dependencies or requirements have changed
-
-For any ambiguity, refer to the platform-specific README in `mssql_python/pybind/README.md` or the comprehensive CI pipeline configurations in `eng/pipelines/`.

llms.txt

@@ -1,7 +1,5 @@
 # mssql-python
 
-> Microsoft Python Driver for SQL Server and Azure SQL
-
 mssql-python is the official Microsoft Python driver for SQL Server and Azure SQL databases. It provides DB API 2.0 compliant database access with Direct Database Connectivity (DDBC) - no external ODBC driver manager required.
 
 ## Installation
@@ -15,59 +13,19 @@ Or using uv (recommended for faster installs):
 uv pip install mssql-python
 ```
 
-### Platform-Specific Dependencies
-
-**macOS** - Install the ODBC driver:
-```bash
-brew install msodbcsql18
-```
-
-**Debian/Ubuntu**:
-```bash
-curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
-curl https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
-sudo apt-get update
-sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18
-```
-
-**RHEL/CentOS/Fedora**:
-```bash
-curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
-curl https://packages.microsoft.com/config/rhel/$(rpm -E %rhel)/prod.repo | sudo tee /etc/yum.repos.d/mssql-release.repo
-sudo ACCEPT_EULA=Y yum install -y msodbcsql18
-```
-
-**Alpine Linux**:
-```bash
-apk add --no-cache curl gnupg
-curl -O https://download.microsoft.com/download/1/f/f/1fffeb70-cd3d-42d5-a7ee-b75c4ff5fb9e/msodbcsql18_18.4.1.1-1_amd64.apk
-apk add --allow-untrusted msodbcsql18_18.4.1.1-1_amd64.apk
-```
-
-**SUSE Linux**:
-```bash
-sudo zypper addrepo https://packages.microsoft.com/config/sles/15/prod.repo
-sudo ACCEPT_EULA=Y zypper install -y msodbcsql18
-```
-
 ## Quick Start
 
 > **Security Note**: The examples below use `TrustServerCertificate=yes` for local development with self-signed certificates. For production or remote connections, remove this option to ensure proper TLS certificate validation.
 
 ```python
 import mssql_python
 
-# Connect to SQL Server
 conn = mssql_python.connect(
     "SERVER=localhost;DATABASE=mydb;Trusted_Connection=yes;Encrypt=yes;TrustServerCertificate=yes"
 )
 cursor = conn.cursor()
-
-# Execute a query
-cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
+cursor.execute("SELECT * FROM users WHERE id = ?", (42,))
 rows = cursor.fetchall()
-
-# Always close when done
 cursor.close()
 conn.close()
 ```
@@ -116,7 +74,6 @@ conn = mssql_python.connect(
 ```python
 import mssql_python
 
-# Connection and cursor automatically close on exit
 with mssql_python.connect(connection_string) as conn:
     with conn.cursor() as cursor:
         cursor.execute("SELECT @@VERSION")
@@ -128,22 +85,16 @@ with mssql_python.connect(connection_string) as conn:
 
 ### Parameterized Queries (Prevent SQL Injection)
 ```python
-# Use ? placeholders for parameters
 cursor.execute("SELECT * FROM users WHERE email = ? AND active = ?", (email, True))
 
-# Or use named parameters with pyformat style
+# Named parameters (pyformat style)
 cursor.execute("SELECT * FROM users WHERE email = %(email)s", {"email": email})
 ```
 
 ### Fetch Results
 ```python
-# Fetch one row
 row = cursor.fetchone()
-
-# Fetch multiple rows
 rows = cursor.fetchmany(size=100)
-
-# Fetch all remaining rows
 all_rows = cursor.fetchall()
 ```
 
@@ -183,11 +134,13 @@ conn.commit()
 ## Transaction Management
 
 ```python
+from mssql_python import DatabaseError
+
 try:
     cursor.execute("INSERT INTO orders (customer_id, total) VALUES (?, ?)", (1, 99.99))
     cursor.execute("UPDATE inventory SET quantity = quantity - 1 WHERE product_id = ?", (42,))
     conn.commit()  # Commit both changes
-except Exception as e:
+except DatabaseError:
     conn.rollback()  # Rollback on error
     raise
 ```
@@ -200,15 +153,6 @@ conn.autocommit = True  # Each statement commits immediately
 
 ## Working with Results
 
-### Access Columns by Index
-```python
-cursor.execute("SELECT id, name, email FROM users")
-for row in cursor.fetchall():
-    user_id = row[0]
-    name = row[1]
-    email = row[2]
-```
-
 ### Get Column Metadata
 ```python
 cursor.execute("SELECT id, name, email FROM users")
@@ -223,7 +167,8 @@ for column in cursor.description:
 cursor.execute("EXEC GetUserById ?", (user_id,))
 result = cursor.fetchone()
 
-# Stored procedure with output
+# OUTPUT parameters: use DECLARE/EXEC/SELECT pattern
+# (callproc() is not supported; use execute() with anonymous code blocks)
 cursor.execute("""
     DECLARE @count INT;
     EXEC CountActiveUsers @count OUTPUT;
@@ -236,7 +181,6 @@ count = cursor.fetchone()[0]
 
 ```python
 from mssql_python import (
-    Error,
     DatabaseError,
     IntegrityError,
     ProgrammingError,
@@ -262,7 +206,7 @@ except DatabaseError as e:
 
 ## Connection Pooling
 
-Connection pooling is enabled by default for improved performance:
+Connection pooling is enabled by default:
 
 ```python
 # Pooling is automatic - connections are reused
@@ -276,10 +220,10 @@ conn2 = mssql_python.connect(connection_string)  # Reuses pooled connection
 
 | Feature | mssql-python | pyodbc |
 |---------|-------------|--------|
-| Driver Manager | Built-in (DDBC) | Requires ODBC |
-| Installation | `pip install` only | Requires ODBC setup |
-| Azure Entra ID | Native support | Requires extra config |
-| Connection Pooling | Built-in | Manual |
+| Driver | Ships bundled | Requires separate ODBC driver |
+| Installation | `pip install` only | pip install + ODBC driver setup |
+| Azure Entra ID | Native Python API | Via ODBC driver connection keywords |
+| Connection Pooling | Built-in | Via ODBC Driver Manager |
 | DB API 2.0 | ✅ Compliant | ✅ Compliant |
 
 ### Migration from pyodbc
@@ -297,7 +241,8 @@ conn = mssql_python.connect("SERVER=...;DATABASE=...")
 
 - Windows (x64, ARM64)
 - macOS (ARM64, x86_64)
-- Linux (x86_64, ARM64): Debian, Ubuntu, RHEL, SUSE, Alpine (musl)
+- Linux (x86_64, ARM64): Debian, Ubuntu, RHEL, Alpine (musl)
+- Linux (x86_64 only): SUSE
 
 ## Supported Python Versions