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/openapi-import-guide.md

@@ -10,7 +10,8 @@ Import a URL, review the AI-classified endpoints, approve, and your agents are l
 1. **Import** -- Provide a URL to an OpenAPI 3.0 spec (JSON or YAML).
 2. **Parse** -- The system downloads and parses the spec.
 3. **Classify** -- An LLM classifies each endpoint's:
-   - `access_type`: `read`, `write`, or `admin`
+   - `access_type`: `read` or `write`
+   - `needs_interrupt`: whether human approval is required
    - `agent_group`: which specialist agent should handle this endpoint
 4. **Review** -- You inspect and edit the classifications in the UI.
 5. **Approve** -- Approved endpoints are registered as tools on the appropriate agents.
@@ -19,12 +20,12 @@ Import a URL, review the AI-classified endpoints, approve, and your agents are l
 
 1. Navigate to the **API Review** tab.
 2. Paste your OpenAPI spec URL into the import form.
-3. Click **Import**.
+3. Click **Scan Tools**.
 4. Wait for the job to complete (status: `pending` -> `processing` -> `done`).
-5. Review the endpoint table:
-   - Edit `access_type` if the AI misclassified sensitivity.
-   - Edit `agent_group` to reassign an endpoint to a different agent.
-6. Click **Approve & Save** when satisfied.
+5. Review the endpoint cards grouped by agent:
+   - Edit `access_type` (Read Only / Write) if the AI misclassified sensitivity.
+   - Edit the agent assignment to reassign an endpoint to a different agent.
+6. Click **Save Configuration** when satisfied.
 
 ## Using the REST API
 
@@ -39,11 +40,15 @@ Content-Type: application/json
 }
 ```
 
-Response:
+Response (202):
 ```json
 {
-  "success": true,
-  "data": { "job_id": "abc123", "status": "pending" }
+  "job_id": "abc123",
+  "status": "pending",
+  "spec_url": "https://api.example.com/openapi.yaml",
+  "total_endpoints": 0,
+  "classified_count": 0,
+  "error_message": null
 }
 ```
 
@@ -53,47 +58,52 @@ Response:
 GET /api/openapi/jobs/{job_id}
 ```
 
-### Get job results
+### Get classifications
 
 ```http
-GET /api/openapi/jobs/{job_id}/result
+GET /api/openapi/jobs/{job_id}/classifications
+```
+
+Response: array of classification objects with `index`, `access_type`,
+`needs_interrupt`, `agent_group`, `confidence`, `customer_params`, and `endpoint`.
+
+### Update a classification
+
+```http
+PUT /api/openapi/jobs/{job_id}/classifications/{index}
+Content-Type: application/json
+
+{
+  "access_type": "write",
+  "needs_interrupt": true,
+  "agent_group": "order_actions"
+}
 ```
 
 ### Approve job
 
 ```http
 POST /api/openapi/jobs/{job_id}/approve
-Content-Type: application/json
-
-{
-  "endpoints": [
-    {
-      "path": "/orders/{order_id}",
-      "method": "get",
-      "access_type": "read",
-      "agent_group": "order_agent"
-    }
-  ]
-}
 ```
 
+No request body. Changes the job status to `approved`.
+
 ## Access Type Classification
 
 | Access Type | Description | Interrupt Required |
 |-------------|-------------|-------------------|
 | `read` | GET operations, no side effects | No |
-| `write` | POST/PUT/PATCH that modify data | Yes |
-| `admin` | DELETE, bulk operations, sensitive writes | Yes |
+| `write` | POST/PUT/PATCH/DELETE that modify data | Yes (by default) |
+
+The `needs_interrupt` flag can be overridden per-endpoint during review.
 
 ## SSRF Protection
 
-All import requests are validated against an allowlist:
+All import requests are validated:
 - Private IP ranges are blocked (10.x, 172.16.x, 192.168.x, 127.x)
-- Localhost and metadata service URLs are blocked
+- Localhost and cloud metadata service URLs are blocked
 - Only `http://` and `https://` schemes are permitted
 
-To allow internal URLs (e.g., in development), set `SSRF_ALLOWLIST_HOSTS` in your environment.
-
 ## Supported Spec Formats
 
 - OpenAPI 3.0.x (JSON or YAML)