docs(routing): add routing rules documentation to API.md and UserGuide.md

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

docs/API.md

@@ -1960,6 +1960,160 @@ Pass no `pipeline_id` query parameter (or omit it) to clear the assignment.
 ```
 
 
+## Routing Rules
+
+Routing rules let you conditionally assign documents to different pipelines
+based on file properties such as type, size, filename, or AI-extracted
+metadata.  Rules are evaluated in **position order** (lowest first); the first
+rule that matches wins.  If no rule matches, the system falls back to the
+owner's (or global) default pipeline.
+
+### Supported operators and fields
+
+```bash
+GET /api/routing-rules/operators
+```
+
+Returns the catalogue of valid operators and built-in fields so UIs can
+populate dropdowns without hard-coding values.
+
+**Response (200):**
+```json
+{
+  "operators": ["contains", "equals", "gt", "gte", "lt", "lte", "not_contains", "not_equals", "regex"],
+  "builtin_fields": ["category", "document_type", "file_type", "filename", "size"],
+  "metadata_prefix": "metadata."
+}
+```
+
+> **Tip:** For AI metadata fields use the `metadata.` prefix, e.g.
+> `metadata.sender`, `metadata.amount`.
+
+### List routing rules
+
+```bash
+GET /api/routing-rules
+```
+
+Returns the current user's rules **plus** any system-wide rules
+(`owner_id = null`), ordered by position.
+
+**Response (200):**
+```json
+[
+  {
+    "id": 1,
+    "owner_id": "alice",
+    "name": "Route invoices",
+    "position": 0,
+    "field": "document_type",
+    "operator": "equals",
+    "value": "Invoice",
+    "target_pipeline_id": 3,
+    "is_active": true,
+    "created_at": "2026-03-09T12:00:00+00:00",
+    "updated_at": "2026-03-09T12:00:00+00:00"
+  }
+]
+```
+
+### Create routing rule
+
+```bash
+POST /api/routing-rules
+Content-Type: application/json
+
+{
+  "name": "Route invoices",
+  "field": "document_type",
+  "operator": "equals",
+  "value": "Invoice",
+  "target_pipeline_id": 3
+}
+```
+
+Optional fields: `position` (auto-assigned if omitted), `is_active` (default `true`).
+
+**Response (201 Created):** The created rule object.
+
+### Get routing rule
+
+```bash
+GET /api/routing-rules/{rule_id}
+```
+
+**Response (200):** A single rule object.
+
+### Update routing rule
+
+```bash
+PUT /api/routing-rules/{rule_id}
+Content-Type: application/json
+
+{ "name": "Renamed rule", "operator": "contains", "is_active": false }
+```
+
+Only the supplied fields are updated.
+
+**Response (200):** The updated rule object.
+
+### Delete routing rule
+
+```bash
+DELETE /api/routing-rules/{rule_id}
+```
+
+Returns **204 No Content**.
+
+### Reorder routing rules
+
+```bash
+PUT /api/routing-rules/reorder
+Content-Type: application/json
+
+{ "rule_ids": [3, 1, 2] }
+```
+
+Provide the complete ordered list of your rule IDs.  Positions are reassigned
+0, 1, 2, … in the given order.
+
+### Evaluate rules (dry run)
+
+```bash
+POST /api/routing-rules/evaluate
+Content-Type: application/json
+
+{
+  "file_type": "application/pdf",
+  "filename": "invoice_2024.pdf",
+  "size": 204800,
+  "document_type": "Invoice",
+  "metadata": { "sender": "Acme Corp" }
+}
+```
+
+Tests which rule (if any) would match the given properties **without**
+actually routing a document.
+
+**Response (200) – match found:**
+```json
+{
+  "matched": true,
+  "rule": { "id": 1, "name": "Route invoices", "..." : "..." },
+  "target_pipeline": { "id": 3, "name": "Invoice Pipeline", "is_active": true }
+}
+```
+
+**Response (200) – no match:**
+```json
+{
+  "matched": false,
+  "rule": null,
+  "target_pipeline": null
+}
+```
+
+
 ## API Tokens
 
 Personal API tokens allow programmatic access to the DocuElevate API without

docs/UserGuide.md

@@ -626,6 +626,53 @@ Pass no `pipeline_id` to clear the assignment and fall back to the system defaul
 
 Admins can create **system pipelines** that appear in every user's pipeline list. These can be set as the global default so all users benefit from a consistent processing baseline. Navigate to **Pipelines** and check the **System pipeline** box when creating a new one (admin only).
 
+### Conditional routing rules
+
+Routing rules automatically assign incoming documents to the right pipeline
+based on their properties — no manual pipeline selection required.
+
+**How it works:**
+
+1. Define one or more routing rules via the API
+   (`POST /api/routing-rules`).
+2. Each rule specifies a **field** to inspect, an **operator** (condition),
+   a **value** to compare against, and a **target pipeline**.
+3. When a document is processed, rules are evaluated **in position order**
+   (lowest first).  The first matching rule wins and the document is routed
+   to that pipeline.
+4. If no rule matches, the document is processed by the default pipeline.
+
+**Available fields:**
+
+| Field | Description |
+|-------|-------------|
+| `file_type` | MIME type, e.g. `application/pdf` |
+| `filename` | Original filename |
+| `size` | File size in bytes |
+| `document_type` | AI-classified type (Invoice, Contract, …) |
+| `category` | Alias for `document_type` |
+| `metadata.<key>` | Any key from the AI-extracted metadata JSON |
+
+**Available operators:**
+
+| Operator | Description |
+|----------|-------------|
+| `equals` / `not_equals` | Exact match (case-insensitive) |
+| `contains` / `not_contains` | Substring match (case-insensitive) |
+| `regex` | Full Python regex match (case-insensitive) |
+| `gt` / `lt` / `gte` / `lte` | Numeric comparison (greater/less than) |
+
+**Example:** Route all invoices over 1 MB to a dedicated pipeline:
+
+```
+Rule 1: field=document_type, operator=equals, value=Invoice, target_pipeline=3
+Rule 2: field=size,          operator=gt,     value=1048576, target_pipeline=5
+```
+
+You can test your rules without actually routing a document using the
+**evaluate** endpoint (`POST /api/routing-rules/evaluate`).  For the full
+API reference, see [API Documentation](API.md#routing-rules).
+
 ## API Access
 
 For programmatic access, DocuElevate provides a comprehensive REST API: