docs: reconcile README and docs with actual codebase

README:
- Remove duplicated agent config, safety, security sections (covered by docs)
- Add ux_design_system.md and safety.py to project structure and doc links
- Convert doc links to descriptive table

agent-config-guide.md:
- Replace fictional agents/tools with real ones from agents.yaml
- Remove nonexistent 'admin' permission level (only read/write)
- Fix template names (e-commerce, saas, fintech)
- List all available built-in tools

openapi-import-guide.md:
- Fix /result -> /classifications endpoint
- Fix POST /approve to show no request body
- Remove nonexistent 'admin' access type
- Update response examples to match actual API

demo-script.md:
- Fix agent names (order_agent -> order_lookup)
- Replace fictional refund scenario with real lookup+cancel flow

ARCHITECTURE.md:
- Fix langgraph-supervisor version (v1.1 -> 0.0.12+)

docker-compose.yml:
- Expose postgres on port 5433 for local dev

docs/agent-config-guide.md

@@ -9,33 +9,38 @@ specialist with a specific role, permission level, and set of tools it can call.
 
 ```yaml
 agents:
-  - name: order_agent
-    description: "Handles order status, tracking, and cancellations."
-    permission: write
-    tools:
-      - get_order_status
-      - cancel_order
-    personality:
-      tone: friendly
-      greeting: "I can help with your order. What is your order number?"
-      escalation_message: "I'm escalating this to a human agent now."
-
-  - name: refund_agent
-    description: "Processes refund requests."
-    permission: write
-    tools:
-      - process_refund
-      - check_refund_eligibility
-    personality:
-      tone: empathetic
-      greeting: "I'm the refund specialist. How can I help?"
-      escalation_message: "I need to escalate this refund request."
-
-  - name: general_agent
-    description: "Answers general questions and FAQs."
+  - name: order_lookup
+    description: "Looks up order status and tracking information."
+    permission: read
+    tools:
+      - get_order_status
+      - get_tracking_info
+    personality:
+      tone: "friendly and informative"
+      greeting: "I can help you check your order status!"
+      escalation_message: "Let me connect you with our support team."
+
+  - name: order_actions
+    description: "Performs order modifications like cancellations."
+    permission: write
+    tools:
+      - cancel_order
+    personality:
+      tone: "careful and reassuring"
+      greeting: "I can help you with order changes."
+      escalation_message: "I'll connect you with a specialist."
+
+  - name: discount
+    description: "Applies discounts and generates coupon codes."
+    permission: write
+    tools:
+      - apply_discount
+      - generate_coupon
+
+  - name: fallback
+    description: "Handles general questions and unclear requests."
     permission: read
     tools:
-      - search_faq
       - fallback_respond
 ```
 
@@ -52,31 +57,38 @@ user messages to the right agent. Be specific.
 Controls the interrupt threshold:
 - `read` -- no interrupt required. Agent can act immediately.
 - `write` -- requires human approval via interrupt before executing tools.
-- `admin` -- requires human approval and is logged for audit.
 
 ### `tools` (required)
-List of tool names this agent can use. Tools are registered in the agent factory.
+List of tool names this agent can use. Tools are registered in `backend/app/agents/`.
 Each tool name must match a registered LangChain tool.
 
+Available built-in tools:
+- `get_order_status` -- look up order details
+- `get_tracking_info` -- get shipping/tracking info
+- `cancel_order` -- cancel an order (write)
+- `apply_discount` -- apply a discount code (write)
+- `generate_coupon` -- generate a new coupon (write)
+- `fallback_respond` -- generic fallback response
+
 ### `personality` (optional)
 Customizes agent behavior:
-- `tone` -- `friendly`, `formal`, `empathetic`, `technical`
-- `greeting` -- Opening message injected at session start.
-- `escalation_message` -- Message sent when the agent escalates.
+- `tone` -- free-text description of the agent's communication style
+- `greeting` -- opening message injected at session start
+- `escalation_message` -- message sent when the agent escalates
 
 ## Built-in Templates
 
 Use `TEMPLATE_NAME` environment variable to load a pre-built agent configuration:
 
-| Template | Description |
-|----------|-------------|
-| `ecommerce` | Orders, refunds, shipping, product questions |
-| `saas` | Account management, billing, technical support |
-| `generic` | General-purpose FAQ and escalation |
+| Template | Filename | Description |
+|----------|----------|-------------|
+| `e-commerce` | `templates/e-commerce.yaml` | Orders, shipping, discounts |
+| `saas` | `templates/saas.yaml` | Account management, billing, support |
+| `fintech` | `templates/fintech.yaml` | Financial services support |
 
 Example:
 ```bash
-TEMPLATE_NAME=ecommerce uvicorn app.main:app
+TEMPLATE_NAME=e-commerce uvicorn app.main:app
 ```
 
 ## Adding New Agents
@@ -98,7 +110,7 @@ matches the agent's description.
 
 ## Escalation
 
-Any agent can trigger escalation by calling the `escalate` tool. This:
+Any agent can trigger escalation. This:
 1. Sends a webhook notification (if `WEBHOOK_URL` is configured).
 2. Marks the conversation with `resolution_type = escalated`.
 3. Sends the agent's `escalation_message` to the user.