From 6abc0551c5057c3ad648d1a1501a46dbb02b73ac Mon Sep 17 00:00:00 2001
From: kjh2064 <kjh2064@gmail.com>
Date: Sat, 15 Aug 2026 10:51:40 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20v16.0=20=E2=80=94=20develop?=
 =?UTF-8?q?ment=20configuration=20harness?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add explicit development environment configuration to AGENTS.md:
- Database connection (appsettings.Development.json sourcing)
- Backend startup (dotnet run with Debug mode)
- Frontend dev server (pnpm dev on port 5174)
- SSH tunnel requirement (PostgreSQL access)
- Authentication headers (DevelopmentHeader mode)
- Rules to prevent config mistakes (no invented credentials, no user prompts)

Enforces: Read config files directly, never make up settings, never ask user.
Database: kartselldb:5432 (NOT kartsell), password kartsell4321@!
Auth: DevelopmentHeader (X-KArtSell-User, X-KArtSell-Role headers)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 AGENTS.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 29d0ecde..2e6e932b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -147,6 +147,79 @@ curl -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
 - **PR Labels:** Auto-label based on affected module (e.g., `ModelOperations`, `SignalEngine`)
 - **Milestones:** Link PRs to quarterly sprints for burndown tracking
 - **Comments:** Post verification results (build, test, security scan) directly on PR
+
+## v16.0 Development Environment Configuration
+
+### Database & Backend Setup
+
+**DO NOT make up or ask for database credentials.**
+
+Read `src/KArtSell.Host/appsettings.Development.json` directly. Current values:
+```json
+{
+  "ConnectionStrings": {
+    "Postgres": "Host=127.0.0.1;Port=5432;Database=kartselldb;Username=kartsell;Password=kartsell4321@!"
+  },
+  "Authentication": {
+    "Mode": "DevelopmentHeader"
+  }
+}
+```
+
+**Connection Parameters:**
+- Host: `127.0.0.1` (localhost)
+- Port: `5432`
+- Database: `kartselldb` (NOT `kartsell`)
+- Username: `kartsell`
+- Password: `kartsell4321@!`
+
+**SSH Tunnel (Required before starting backend):**
+```powershell
+ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7
+```
+
+**Start Backend (use config file, no env var injection):**
+```powershell
+cd D:\JobRoomz\KArtSell.Aegis
+dotnet run --project src/KArtSell.Host --configuration Debug --no-build
+```
+
+### Frontend Development Server
+
+**Port:** 5174 (fallback: 5173 if available)
+
+**Start Frontend (from project root):**
+```bash
+cd frontend
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+**URL:** http://localhost:5174
+
+### Authentication for Testing
+
+Development mode uses `DevelopmentHeaderAuthenticationHandler`. Test requests with:
+```powershell
+$headers = @{
+    "X-KArtSell-User" = "kjh2064"
+    "X-KArtSell-Role" = "Admin"
+    "Content-Type" = "application/json"
+}
+
+Invoke-WebRequest -Uri "http://127.0.0.1:5002/api/shadow-runs" `
+    -Method POST `
+    -Headers $headers `
+    -Body $body
+```
+
+### Rules for Development Configuration
+
+1. **Never invent credentials.** Read config files first.
+2. **Never ask the user for settings.** Read `appsettings.Development.json` directly.
+3. **Database name is `kartselldb`.** Not `kartsell`.
+4. **SSH tunnel is mandatory.** PostgreSQL is not accessible without it.
+5. **Authentication mode is `DevelopmentHeader`.** Use headers, not OIDC tokens.
 - **Releases:** Tag with semver + architecture contract version (e.g., `v16.0.1-contract-v3.0`)
 - **Issue Linking:** Reference debt IDs, ADRs, decision logs in commits (e.g., `TECH-001: Fix CA1822`)