From 77b05e17f78d6fe2fe8cd0445c698406b47d78d9 Mon Sep 17 00:00:00 2001
From: kjh2064 <kjh2064@gmail.com>
Date: Sun, 2 Aug 2026 23:08:16 +0900
Subject: [PATCH] docs: Fix Host startup guidance - DEVELOPMENT mode required
 for DevelopmentHeaderAuthenticationHandler

---
 CLAUDE.md | 53 +++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 43 insertions(+), 10 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 50ab8d04..44415a91 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -45,21 +45,54 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ⏳ Step 3: Host restart required (to apply changes)
 ⏳ Step 4: Retry Gate 3-4 with auth headers
 
-**Next Action:** User must restart Host after code change
+**Next Action: Host Startup (DEVELOPMENT MODE - Critical!)**
+
+⚠️ **IMPORTANT: Host must run in DEVELOPMENT mode for authentication to work**
+
 ```bash
-# Terminal (after killing current Host process)
+# Terminal 1: SSH Tunnel (keep open)
+ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7
+
+# Terminal 2: Start Host in DEVELOPMENT MODE (NOT Release)
 cd D:\JobRoomz\KArtSell.Aegis
-$env:KRX_API_KEY = "local-dev-test-key"
-$env:OPENDART_API_KEY = "local-dev-test-key"
-$env:KIS_API_KEY = "local-dev-test-key"
-dotnet run --project src/KArtSell.Host -c Release
+
+# Set actual API keys from Gitea Secrets (not test keys!)
+$env:KRX_API_KEY = "<actual-krx-api-key>"
+$env:OPENDART_API_KEY = "<actual-opendart-api-key>"
+$env:KIS_API_KEY = "<actual-kis-api-key>"
+$env:ASPNETCORE_ENVIRONMENT = "Development"
+
+# Run in DEBUG mode (Development environment)
+dotnet run --project src/KArtSell.Host
+
+# Expected output:
+# Now listening on: http://127.0.0.1:5002
+# Application started. Press Ctrl+C to shut down.
 ```
 
-**Then test with Auth headers:**
+**Why DEVELOPMENT mode?**
+- **Release mode (-c Release):** Uses `FailClosedAuthenticationHandler` → all requests denied (403/404)
+- **Debug mode (default):** Uses `DevelopmentHeaderAuthenticationHandler` → accepts `X-KArtSell-User` / `X-KArtSell-Role` headers
+
+**Gate 3 Request (after Host ready):**
 ```powershell
-$headers = @{"X-KArtSell-User"="admin"; "X-KArtSell-Role"="Admin"}
-$body = @{"modelId"="00000000-0000-0000-0000-000000000001"; ...} | ConvertTo-Json
-Invoke-WebRequest -Uri "http://127.0.0.1:5002/api/shadow-runs" -Method POST -Headers $headers -Body $body
+$headers = @{
+    "X-KArtSell-User" = "gate3-rehearsal"
+    "X-KArtSell-Role" = "researcher"
+    "Content-Type" = "application/json"
+}
+
+$body = @{
+    modelId = "00000000-0000-0000-0000-000000000001"
+    windowStartDate = "2024-01-02"
+    windowEndDate = "2024-08-31"
+} | ConvertTo-Json
+
+Invoke-WebRequest -Uri "http://127.0.0.1:5002/api/shadow-runs" `
+    -Method POST `
+    -Headers $headers `
+    -Body $body `
+    -ContentType "application/json"
 ```
 
 ---