docs: add Claude AI assistant rules and configuration

Add comprehensive rule documentation for AI-assisted development covering
authentication surfaces, outbound-call safety invariants, and other project
conventions to guide Claude's understanding of critical system behaviors.

docs/configuration.md

@@ -4,6 +4,25 @@ All configuration is via environment variables, loaded through Pydantic Settings
 
 ## Environment Variables
 
+### Auth (Casdoor SSO + owner)
+
+The gateway is **owner-only**: the browser signs in via Casdoor (JWT), MCP/CLI
+clients use owner-minted PATs, and only `OWNER_NAME` may use any surface. With
+`CASDOOR_ENABLED=false` the gateway runs in dev-owner mode — permitted **only** on
+a loopback `HOST`. Startup refuses SSO-enabled-with-missing-config and
+SSO-disabled-off-loopback.
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `CASDOOR_ENABLED` | Enable Casdoor SSO | `false` | No |
+| `CASDOOR_ENDPOINT` | Casdoor base URL | `https://id.ouranos.helu.ca` | If SSO on |
+| `CASDOOR_CLIENT_ID` | Casdoor application client ID | — | If SSO on |
+| `CASDOOR_CLIENT_SECRET` | Casdoor application client secret | — | If SSO on |
+| `CASDOOR_ORG_NAME` | Casdoor organization | `heluca` | No |
+| `CASDOOR_APP_NAME` | Casdoor application name | — | No |
+| `OWNER_NAME` | Casdoor username of the single operator | — | If SSO on |
+| `PUBLIC_BASE_URL` | Public base URL for OAuth discovery (else derived) | — | No |
+
 ### SIP Trunk
 
 | Variable | Description | Default | Required |

docs/mcp-server.md

@@ -3,8 +3,11 @@
 The MCP (Model Context Protocol) server lets any MCP-compatible AI assistant
 control the Hold Slayer gateway. Built with [FastMCP](https://github.com/jlowin/fastmcp),
 it is mounted on the FastAPI app at **`/mcp/`** (trailing slash) over
-**streamable HTTP** and authenticates with the same static bearer token as the
-REST API and WebSocket.
+**streamable HTTP** and authenticates with an owner-minted Personal Access Token
+(`hs_pat_…`) — the same owner-only auth as the REST API and WebSocket. Auth is
+enforced by an ASGI guard (`_owner_only_mcp` in `main.py`) that resolves the
+bearer to the owner; a Casdoor JWT also works, but MCP clients can't refresh one,
+so a PAT is the intended credential.
 
 ## Overview
 
@@ -158,7 +161,7 @@ Claude Code:
 
 ```bash
 claude mcp add hold-slayer --transport http http://localhost:8000/mcp/ \
-  --header "Authorization: Bearer $API_TOKEN"
+  --header "Authorization: Bearer hs_pat_..."
 ```
 
 Generic MCP client configuration:
@@ -168,7 +171,7 @@ Generic MCP client configuration:
   "mcpServers": {
     "hold-slayer": {
       "url": "http://localhost:8000/mcp/",
-      "headers": {"Authorization": "Bearer <API_TOKEN>"}
+      "headers": {"Authorization": "Bearer hs_pat_..."}
     }
   }
 }