From 24a4c0072746854841dcd6310a97053bfc4df727 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 18:54:03 +0900
Subject: [PATCH 01/10] docs: record deployment IDs for CI/CD (#1)

* docs: record deployment IDs for GitHub Actions

* ci: run checks on pull_request to satisfy branch protection

* docs: note Vercel rootDirectory app setting
---
 .github/workflows/ci-cd.yml | 5 +++++
 docs/DEPLOYMENT.md          | 8 ++++++++
 2 files changed, 13 insertions(+)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index c2c291c..0e5189b 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -6,6 +6,11 @@ on:
       - main
       - dev
       - development
+  pull_request:
+    branches:
+      - main
+      - dev
+      - development
 
 jobs:
   checks:
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 3ba91d1..392693e 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -20,6 +20,7 @@
 2. 환경변수 설정
 - `NEXT_PUBLIC_API_BASE=https://<your-railway-domain>`
 3. Vercel에서는 `app/.env.local`이 아니라, **Project Settings의 Environment Variables**에 등록해야 합니다.
+4. 본 레포지토리는 프론트 프로젝트 루트가 `app/`이므로, Vercel 프로젝트 Root Directory를 `app`으로 설정해야 합니다.
 
 ## Local dev
 
@@ -71,6 +72,13 @@ bash ./scripts/check-deploy-env.sh
 - `RAILWAY_SERVICE_NAME`
 - `RAILWAY_DEV_ENVIRONMENT`
 
+현재 저장소 기준으로 확정된 값
+- `VERCEL_ORG_ID=team_zsn95o3nyKEFVKDSg7tPFn3f`
+- `VERCEL_PROJECT_ID=prj_nnesdRii3GLrSJOehkoRKmLnV0U5`
+- `RAILWAY_SERVICE_NAME=knowledge-copilot-api`
+- `RAILWAY_DEV_ENVIRONMENT=development`
+- `RAILWAY_TOKEN`은 유효한 CLI 토큰으로 교체 필요
+
 ## 운영 주의
 
 - 이번 백엔드는 기본적으로 SQLite를 사용하므로 파일 DB가 컨테이너/빌드 재시작 시 초기화될 수 있습니다.

From 26d344bbcc65163c58793ffdcde548acbce68b7b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 18:56:53 +0900
Subject: [PATCH 02/10] chore: refresh deployment secrets (#2)


From e4de46b23be40363dfa5de8a045ae271b0c6f19b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 19:01:54 +0900
Subject: [PATCH 03/10] chore: fix vercel deployment step with explicit CLI
 token (#3)

---
 .github/workflows/ci-cd.yml | 41 +++++++++++++++++++++++++------------
 docs/DEPLOYMENT.md          |  6 ++----
 2 files changed, 30 insertions(+), 17 deletions(-)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 0e5189b..8233103 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -59,13 +59,21 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Deploy frontend (Vercel)
-        uses: amondnet/vercel-action@v25
+      - name: Setup Node.js for Vercel CLI
+        uses: actions/setup-node@v4
         with:
-          vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
-          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
-          working-directory: ./app
+          node-version: 20
+
+      - name: Install Vercel CLI
+        run: npm install -g vercel
+
+      - name: Deploy frontend (Vercel)
+        working-directory: app
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
+        run: |
+          npx vercel@25.1.0 deploy --yes --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --name knowledge-copilot
 
       - name: Setup Node.js for Railway CLI
         uses: actions/setup-node@v4
@@ -99,14 +107,21 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Deploy frontend (Vercel)
-        uses: amondnet/vercel-action@v25
+      - name: Setup Node.js for Vercel CLI
+        uses: actions/setup-node@v4
         with:
-          vercel-token: ${{ secrets.VERCEL_TOKEN }}
-          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
-          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
-          working-directory: ./app
-          vercel-args: "--prod --confirm"
+          node-version: 20
+
+      - name: Install Vercel CLI
+        run: npm install -g vercel
+
+      - name: Deploy frontend (Vercel)
+        working-directory: app
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
+        run: |
+          npx vercel@25.1.0 deploy --yes --prod --confirm --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --name knowledge-copilot
 
       - name: Setup Node.js for Railway CLI
         uses: actions/setup-node@v4
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index 392693e..d0505af 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -66,15 +66,13 @@ bash ./scripts/check-deploy-env.sh
 
 ### 필요한 GitHub Actions 시크릿
 - `VERCEL_TOKEN`
-- `VERCEL_ORG_ID`
-- `VERCEL_PROJECT_ID`
+- `VERCEL_SCOPE` (`doublesilvers-projects`)
 - `RAILWAY_TOKEN`
 - `RAILWAY_SERVICE_NAME`
 - `RAILWAY_DEV_ENVIRONMENT`
 
 현재 저장소 기준으로 확정된 값
-- `VERCEL_ORG_ID=team_zsn95o3nyKEFVKDSg7tPFn3f`
-- `VERCEL_PROJECT_ID=prj_nnesdRii3GLrSJOehkoRKmLnV0U5`
+- `VERCEL_SCOPE=doublesilvers-projects`
 - `RAILWAY_SERVICE_NAME=knowledge-copilot-api`
 - `RAILWAY_DEV_ENVIRONMENT=development`
 - `RAILWAY_TOKEN`은 유효한 CLI 토큰으로 교체 필요

From b59dfc1a63dcb70736f84c8737b3298e754d6812 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 19:04:47 +0900
Subject: [PATCH 04/10] ci: use valid vercel cli flags for deployment (#4)

---
 .github/workflows/ci-cd.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 8233103..34b61b6 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -73,7 +73,7 @@ jobs:
           VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
           VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
         run: |
-          npx vercel@25.1.0 deploy --yes --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --name knowledge-copilot
+          npx vercel@25.1.0 deploy --confirm --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --name knowledge-copilot
 
       - name: Setup Node.js for Railway CLI
         uses: actions/setup-node@v4
@@ -121,7 +121,7 @@ jobs:
           VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
           VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
         run: |
-          npx vercel@25.1.0 deploy --yes --prod --confirm --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --name knowledge-copilot
+          npx vercel@25.1.0 deploy --prod --confirm --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --name knowledge-copilot
 
       - name: Setup Node.js for Railway CLI
         uses: actions/setup-node@v4

From 95bc9d456477f8799f3303074ec82769fc478cda Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 19:09:26 +0900
Subject: [PATCH 05/10] ci: stabilize vercel deployment in workflow (#5)

---
 .github/workflows/ci-cd.yml | 64 ++++++++++++++++++++++++++++++++++---
 README.md                   |  3 +-
 2 files changed, 61 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 34b61b6..cf263ec 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -65,7 +65,19 @@ jobs:
           node-version: 20
 
       - name: Install Vercel CLI
-        run: npm install -g vercel
+        run: npm install -g vercel@25.1.0
+
+      - name: Link Vercel project
+        working-directory: app
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
+        run: |
+          vercel link \
+            --project knowledge-copilot \
+            --scope "$VERCEL_SCOPE" \
+            --confirm \
+            --token "$VERCEL_TOKEN"
 
       - name: Deploy frontend (Vercel)
         working-directory: app
@@ -73,7 +85,23 @@ jobs:
           VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
           VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
         run: |
-          npx vercel@25.1.0 deploy --confirm --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --name knowledge-copilot
+          attempt=1
+          max_attempts=3
+          while :; do
+            if vercel deploy --confirm --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE"; then
+              break
+            fi
+
+            if [ "$attempt" -ge "$max_attempts" ]; then
+              echo "Vercel deploy failed after ${max_attempts} attempt(s)."
+              exit 1
+            fi
+
+            sleep_seconds=$((attempt * 10))
+            echo "Vercel deploy failed. Retry ${attempt}/${max_attempts} in ${sleep_seconds}s..."
+            sleep "$sleep_seconds"
+            attempt=$((attempt + 1))
+          done
 
       - name: Setup Node.js for Railway CLI
         uses: actions/setup-node@v4
@@ -113,7 +141,19 @@ jobs:
           node-version: 20
 
       - name: Install Vercel CLI
-        run: npm install -g vercel
+        run: npm install -g vercel@25.1.0
+
+      - name: Link Vercel project
+        working-directory: app
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+          VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
+        run: |
+          vercel link \
+            --project knowledge-copilot \
+            --scope "$VERCEL_SCOPE" \
+            --confirm \
+            --token "$VERCEL_TOKEN"
 
       - name: Deploy frontend (Vercel)
         working-directory: app
@@ -121,7 +161,23 @@ jobs:
           VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
           VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
         run: |
-          npx vercel@25.1.0 deploy --prod --confirm --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE" --name knowledge-copilot
+          attempt=1
+          max_attempts=3
+          while :; do
+            if vercel deploy --prod --confirm --token "$VERCEL_TOKEN" --scope "$VERCEL_SCOPE"; then
+              break
+            fi
+
+            if [ "$attempt" -ge "$max_attempts" ]; then
+              echo "Vercel deploy failed after ${max_attempts} attempt(s)."
+              exit 1
+            fi
+
+            sleep_seconds=$((attempt * 10))
+            echo "Vercel deploy failed. Retry ${attempt}/${max_attempts} in ${sleep_seconds}s..."
+            sleep "$sleep_seconds"
+            attempt=$((attempt + 1))
+          done
 
       - name: Setup Node.js for Railway CLI
         uses: actions/setup-node@v4
diff --git a/README.md b/README.md
index 16b7696..4498585 100644
--- a/README.md
+++ b/README.md
@@ -63,8 +63,7 @@ docker compose up --build
 ### GitHub Actions 설정 항목
 `Settings > Secrets and variables > Actions`에 아래 값이 있어야 합니다.
 - `VERCEL_TOKEN`
-- `VERCEL_ORG_ID`
-- `VERCEL_PROJECT_ID`
+- `VERCEL_SCOPE`
 - `RAILWAY_TOKEN`
 - `RAILWAY_SERVICE_NAME`
 - `RAILWAY_DEV_ENVIRONMENT`

From 9f6506296f3c1bfa8ad0552733804433fb180aa9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 19:27:14 +0900
Subject: [PATCH 06/10] chore: fix CI/CD project linkage and refresh README
 (#6)

* Fix Vercel project linkage in CI

* docs: align README with subway-board style template
---
 .github/workflows/ci-cd.yml |   4 +-
 README.md                   | 290 ++++++++++++++++++++++++++++--------
 2 files changed, 231 insertions(+), 63 deletions(-)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index cf263ec..9081bac 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -74,7 +74,7 @@ jobs:
           VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
         run: |
           vercel link \
-            --project knowledge-copilot \
+            --project app \
             --scope "$VERCEL_SCOPE" \
             --confirm \
             --token "$VERCEL_TOKEN"
@@ -150,7 +150,7 @@ jobs:
           VERCEL_SCOPE: ${{ secrets.VERCEL_SCOPE }}
         run: |
           vercel link \
-            --project knowledge-copilot \
+            --project app \
             --scope "$VERCEL_SCOPE" \
             --confirm \
             --token "$VERCEL_TOKEN"
diff --git a/README.md b/README.md
index 4498585..a307965 100644
--- a/README.md
+++ b/README.md
@@ -1,90 +1,258 @@
-# Knowledge Copilot
+# Knowledge Copilot - AI Document Copilot
 
-이 프로젝트는 포트폴리오 목적의 **AI 문서 기반 지식 코파일럿**입니다.
-- 문서 업로드 (텍스트)
-- RAG 기반 검색 + 질의
-- 근거(citation) 표시
-- 액션형 기능 (문서 요약)
-- 피드백/메트릭 집계
+> **한 문서에서 근거 기반으로 답하는 팀형 지식 동반자**
+>
+> 업로드한 문서를 임베딩하고, 검색 기반 질의와 액션 API를 제공하는 풀스택 AI 포트폴리오 프로젝트입니다.
 
-## 폴더 구성
-- `api/`: FastAPI 백엔드
-- `app/`: Next.js 프론트엔드
-- `docs/`: 설계/로드맵 메모
-- `docker-compose.yml`: 통합 실행 환경
+<div align="center">
 
-## 빠른 시작
+[![Deploy Status](https://img.shields.io/badge/deploy-GitHub_Actions-2088FF?style=for-the-badge&logo=github-actions&logoColor=white)](https://github.com/doublesilver/knowledge-copilot/actions)
+[![CI/CD](https://img.shields.io/badge/CI%2FCD-dev%20%26%20prod-4CAF50?style=for-the-badge)](https://github.com/doublesilver/knowledge-copilot/actions/workflows/ci-cd.yml)
+[![Vercel](https://img.shields.io/badge/Vercel-Frontend-black?style=for-the-badge&logo=vercel)](https://vercel.com)
+[![Railway](https://img.shields.io/badge/Railway-API-0B0D0E?style=for-the-badge&logo=railway)](https://railway.app)
 
-1. Python 의존성 설치
-```bash
-cd /mnt/c/Users/korea/project3/api
-python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
-pip install -r requirements.txt
+</div>
+
+---
+
+## 프로젝트 개요
+
+| 항목 | 내용 |
+|------|------|
+| **프로젝트명** | Knowledge Copilot |
+| **유형** | AI 문서 질의/요약 MVP (포트폴리오) |
+| **개발 기간** | 2026-02-27 기준 구축 단계 |
+| **개발 인원** | 1인 풀스택 |
+| **현재 버전** | v0.1.0 |
+| **서비스 URL** | 배포 URL 별도 등록(공개 도메인 미공개) |
+
+---
+
+## 주요 기능
+
+| 기능 | 설명 |
+|------|------|
+| **문서 업로드** | 텍스트/파일 기반 문서를 업로드해 인덱싱 |
+| **RAG 질의** | 문서 기반 근거가 포함된 답변 반환 |
+| **문서 상세 조회** | 업로드한 문서/청크 기반 조회 |
+| **피드백 수집** | 질의 결과 평점 및 메모 저장 |
+| **액션 실행** | 사전 정의된 액션 API 엔드포인트 제공 |
+| **운영 메트릭** | 질의 수, 지연시간, 피드백 지표 조회 |
+| **CI/CD 자동 배포** | `dev`/`main` 브랜치 기준 자동 배포 |
+
+---
+
+## 기술 스택
+
+```mermaid
+flowchart LR
+    subgraph Frontend[Frontend (Vercel)]
+        N[Next.js 14.2.15]
+        React[React 18.3.1]
+        TypeScript[TypeScript 5.5.4]
+    end
+
+    subgraph Backend[Backend (Railway)]
+        FastAPI[FastAPI 0.112.0]
+        PyEnv[Python 3.12]
+        Uvicorn[Uvicorn 0.30.6]
+        SQLite[SQLite (파일 DB)]
+    end
+
+    User[브라우저] --> N --> FastAPI
+    FastAPI --> SQLite
+    FastAPI --> OpenAI[Embedding/Chat API]
+```
+
+### 스택 정리
+
+| 영역 | 사용 기술 |
+|------|----------|
+| Frontend | Next.js, React, TypeScript |
+| Backend | FastAPI, Pydantic, Uvicorn |
+| Storage | SQLite (프로토타입 DB) |
+| AI | OpenAI(임베딩/챗 모델, 옵션) |
+| 배포 | Vercel, Railway, GitHub Actions |
+| 테스트 | pytest |
+
+---
+
+## 아키텍처
+
+```mermaid
+flowchart TD
+    subgraph Browser[Client]
+        UI[Next.js UI]
+    end
+    subgraph API[API Layer]
+        FAST[FastAPI]
+        ROUTES[REST endpoints /api/v1/*]
+        DB[(SQLite)]
+    end
+
+    UI -->|HTTPS| ROUTES
+    ROUTES --> FAST
+    FAST --> DB
+    FAST --> OpenAI[(OpenAI API)]
+```
+
+### API 엔드포인트
+
+| 메서드 | 경로 | 용도 |
+|--------|------|------|
+| GET | `/api/v1/health` | 헬스체크 |
+| POST | `/api/v1/documents` | 문서 업로드 |
+| GET | `/api/v1/documents` | 문서 목록 |
+| GET | `/api/v1/documents/{id}` | 문서 상세 |
+| POST | `/api/v1/queries` | 질의 처리 |
+| GET | `/api/v1/queries/{id}` | 질의 상세 |
+| POST | `/api/v1/evals` | 사용자 피드백 수집 |
+| POST | `/api/v1/agent/actions` | 액션 실행 |
+| GET | `/api/v1/metrics` | 운영 메트릭 |
+
+---
+
+## 프로젝트 구조
+
+```text
+project3/
+├── app/                  # Next.js 프론트엔드
+│   ├── src/
+│   ├── public/
+│   └── package.json
+├── api/                  # FastAPI 백엔드
+│   ├── src/
+│   ├── requirements.txt
+│   ├── Dockerfile
+│   └── pytest
+├── docs/                 # 배포/로드맵 문서
+├── .github/workflows/    # CI/CD
+├── scripts/              # 배포 전 검증 스크립트
+└── .env, .env.example    # 로컬 환경설정
 ```
 
-2. API 실행
+---
+
+## 로컬 실행 방법
+
+### 사전 설치
+
+- Node.js 20+
+- Python 3.12+
+
+### Backend 실행
+
 ```bash
-cp ../.env.example ../.env   # 최초 1회만
+cd api
+cp ../.env.example ../.env  # 최초 1회
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\\Scripts\\activate
+pip install -r requirements.txt
 uvicorn src.main:app --reload --env-file ../.env
 ```
 
-3. 프론트 실행
+### Frontend 실행
+
 ```bash
-cd ../app
+cd app
 npm install
 npm run dev
 ```
 
-4. 배포 환경 기준
-- Frontend: Vercel
-- Backend: Railway
+### 통합 실행
 
-> 실제 운영 배포에서는 Vercel/Railway 환경 변수에 `NEXT_PUBLIC_API_BASE`, `OPENAI_API_KEY` 등을 설정합니다.
-
-5. 또는 Docker로 통합 실행
 ```bash
 docker compose up --build
 ```
 
-## 배포 플로우 (Git 기준)
+### 체크리스트
+
+```bash
+cd api
+python -m pytest -q
+
+cd ../app
+npm run build
+```
+
+---
+
+## 배포/운영
+
+### Git 기반 자동 배포 전략
 
-### 브랜치 전략
-- `dev` 또는 `development`: 개발/스테이징 배포 대상
-- `main`: 실운영(Production) 배포 대상
+- **dev / development 브랜치 push**: 개발 환경 배포(Development)
+- **main 브랜치 push**: 실운영 배포(Production)
+- `main` 배포는 운영 정책상 `dev` 검증 흐름 이후 반영
 
-### 배포 규칙
-1. 로컬에서 코드 수정
-2. `git add`, `git commit`, `git push`  
-   - `dev` 브랜치에 push → 자동으로 **개발 배포** 실행
-   - `main` 브랜치에 push → 자동으로 **실운영 배포** 실행
-3. 실운영 배포는 개발 배포가 통과한 커밋만 머지 전제(`main` 머지/리뷰 정책을 이용)
+### 배포 산출물
+
+- Frontend: Vercel (`app` 디렉터리 기준)
+- Backend: Railway (`api` 디렉터리 기준)
+
+### GitHub Actions 필수 Secret
 
-### GitHub Actions 설정 항목
-`Settings > Secrets and variables > Actions`에 아래 값이 있어야 합니다.
 - `VERCEL_TOKEN`
 - `VERCEL_SCOPE`
 - `RAILWAY_TOKEN`
 - `RAILWAY_SERVICE_NAME`
 - `RAILWAY_DEV_ENVIRONMENT`
 
-### Vercel/배포 환경 대응
-- Vercel은 기본적으로 브랜치별 Preview/Production 라우팅을 사용하도록 `.github/workflows/ci-cd.yml`에서 분기 처리
-- Railway는 환경명을 `production` / `development`로 나눠 배포하도록 구성
-- 배포 시점은 GitHub Push 이벤트 기준으로 자동 실행
-
-## API
-- `POST /api/v1/documents`: 문서 업로드
-- `GET /api/v1/documents`: 문서 목록
-- `GET /api/v1/documents/{id}`: 문서 상세
-- `POST /api/v1/queries`: 질문 질의
-- `GET /api/v1/queries/{id}`: 질의 상세
-- `POST /api/v1/evals`: 질의 피드백
-- `POST /api/v1/agent/actions`: 액션 실행
-- `GET /api/v1/metrics`: 메트릭
-- `GET /api/v1/health`: 상태 체크
-
-## 운영 메모
-- OpenAI API 키가 없을 경우 로컬 임베딩(데모 모드) 및 단순 응답 경로로 동작합니다.
-- `CORS_ORIGINS`는 배포 환경에 맞춰 업데이트합니다.
-- 배포 가이드는 [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)를 참고하세요.
+---
+
+## 테스트
+
+현재 기준으로 검증 가능한 항목
+
+- `pytest` (백엔드 단위/API 기본 테스트)
+- `npm run build` (Next.js 빌드 검증)
+- GitHub Actions 체크 자동화
+
+```bash
+cd api
+python -m pytest -q
+
+cd ../app
+npm run build
+```
+
+---
+
+## 개발 타임라인
+
+- v0.1.0: CI/CD 안정화 및 문서화 정리
+- v0.2.0: 질문 정합성 개선, 프롬프트 강화
+- v0.3.0: 인증/권한, 멀티테넌트, 지표 대시보드 고도화
+
+---
+
+## 보안 & 운영 노트
+
+- OpenAI 키/토큰은 `.env` 또는 플랫폼 Secret으로만 관리
+- CORS는 환경별로 제한하여 배포
+- 파일 업로드는 UTF-8 텍스트 기반 처리로 제한
+- SQLite는 포트폴리오/샘플 단계의 저장소로, 운영 요구 시 PostgreSQL 교체 고려
+
+---
+
+## 문서
+
+- [DEPLOYMENT.md](./docs/DEPLOYMENT.md)
+- [ROADMAP.md](./docs/ROADMAP.md)
+- [CI/CD workflow](.github/workflows/ci-cd.yml)
+
+---
+
+## License
+
+MIT License
+
+---
+
+<div align="center">
+
+이 프로젝트는 포트폴리오 제출 및 면접용 실무형 구현 역량 증빙 목적입니다.
+
+**Made for practical AI engineering interview readiness.**
+
+</div>

From 59fd9849cb965341e64a45203b3e406e5f905872 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 19:32:41 +0900
Subject: [PATCH 07/10] ci: switch railway deploy to deploy hooks

---
 .github/workflows/ci-cd.yml | 42 +++++++++++--------------------------
 README.md                   |  7 ++++---
 docs/DEPLOYMENT.md          | 14 ++++++-------
 scripts/check-deploy-env.sh |  1 -
 4 files changed, 23 insertions(+), 41 deletions(-)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 9081bac..30ca4ab 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -103,26 +103,15 @@ jobs:
             attempt=$((attempt + 1))
           done
 
-      - name: Setup Node.js for Railway CLI
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install Railway CLI
-        run: npm install -g @railway/cli
-
-      - name: Deploy API (Railway)
+      - name: Trigger API deployment (Railway)
         env:
-          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
-        working-directory: api
+          RAILWAY_DEPLOY_HOOK: ${{ secrets.RAILWAY_DEV_DEPLOY_HOOK }}
         run: |
-          if [ -z "${{ secrets.RAILWAY_DEV_ENVIRONMENT }}" ]; then
-            echo "RAILWAY_DEV_ENVIRONMENT secret not configured." >&2
+          if [ -z "$RAILWAY_DEPLOY_HOOK" ]; then
+            echo "RAILWAY_DEV_DEPLOY_HOOK secret is not configured." >&2
             exit 1
           fi
-          railway up --service "${{ secrets.RAILWAY_SERVICE_NAME }}" \
-            --environment "${{ secrets.RAILWAY_DEV_ENVIRONMENT }}" \
-            --ci --detach
+          curl -fsSL -X POST "$RAILWAY_DEPLOY_HOOK"
 
   deploy-production:
     if: github.ref == 'refs/heads/main'
@@ -179,19 +168,12 @@ jobs:
             attempt=$((attempt + 1))
           done
 
-      - name: Setup Node.js for Railway CLI
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install Railway CLI
-        run: npm install -g @railway/cli
-
-      - name: Deploy API (Railway)
+      - name: Trigger API deployment (Railway)
         env:
-          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}
-        working-directory: api
+          RAILWAY_DEPLOY_HOOK: ${{ secrets.RAILWAY_PROD_DEPLOY_HOOK }}
         run: |
-          railway up --service "${{ secrets.RAILWAY_SERVICE_NAME }}" \
-            --environment production \
-            --ci --detach
+          if [ -z "$RAILWAY_DEPLOY_HOOK" ]; then
+            echo "RAILWAY_PROD_DEPLOY_HOOK secret is not configured." >&2
+            exit 1
+          fi
+          curl -fsSL -X POST "$RAILWAY_DEPLOY_HOOK"
diff --git a/README.md b/README.md
index a307965..3454fea 100644
--- a/README.md
+++ b/README.md
@@ -194,9 +194,10 @@ npm run build
 
 - `VERCEL_TOKEN`
 - `VERCEL_SCOPE`
-- `RAILWAY_TOKEN`
-- `RAILWAY_SERVICE_NAME`
-- `RAILWAY_DEV_ENVIRONMENT`
+- `RAILWAY_DEV_DEPLOY_HOOK`
+- `RAILWAY_PROD_DEPLOY_HOOK`
+
+Railway 배포는 더 이상 `RAILWAY_TOKEN`을 사용하지 않고, GitHub Actions에서 각 환경별 Deploy Hook URL을 호출해 배포를 트리거합니다.
 
 ---
 
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
index d0505af..8b4dcd1 100644
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -49,7 +49,7 @@ bash ./scripts/check-deploy-env.sh
 - Vercel Web
 - `NEXT_PUBLIC_API_BASE`
 - 로컬 토큰 관리
-  - `VERCEL_TOKEN`, `RAILWAY_TOKEN`, `GITHUB_TOKEN` (로컬 용도)
+  - `VERCEL_TOKEN`, `GITHUB_TOKEN` (로컬 용도)
 
 ## Git 기반 자동 배포 흐름
 
@@ -67,15 +67,15 @@ bash ./scripts/check-deploy-env.sh
 ### 필요한 GitHub Actions 시크릿
 - `VERCEL_TOKEN`
 - `VERCEL_SCOPE` (`doublesilvers-projects`)
-- `RAILWAY_TOKEN`
-- `RAILWAY_SERVICE_NAME`
-- `RAILWAY_DEV_ENVIRONMENT`
+- `RAILWAY_DEV_DEPLOY_HOOK`
+- `RAILWAY_PROD_DEPLOY_HOOK`
 
 현재 저장소 기준으로 확정된 값
 - `VERCEL_SCOPE=doublesilvers-projects`
-- `RAILWAY_SERVICE_NAME=knowledge-copilot-api`
-- `RAILWAY_DEV_ENVIRONMENT=development`
-- `RAILWAY_TOKEN`은 유효한 CLI 토큰으로 교체 필요
+
+Railway 배포는 더 이상 CLI 토큰(`RAILWAY_TOKEN`)을 사용하지 않고, GitHub Actions에서 각 환경별 **Deploy Hook URL**(`RAILWAY_DEV_DEPLOY_HOOK`, `RAILWAY_PROD_DEPLOY_HOOK`)을 POST 호출해 트리거합니다.
+
+참고: Deploy Hook URL은 Railway 프로젝트 Settings → Deployments → Deployment Hooks 에서 발급합니다.
 
 ## 운영 주의
 
diff --git a/scripts/check-deploy-env.sh b/scripts/check-deploy-env.sh
index 7dc338d..91f391f 100755
--- a/scripts/check-deploy-env.sh
+++ b/scripts/check-deploy-env.sh
@@ -51,7 +51,6 @@ require_var NEXT_PUBLIC_API_BASE
 echo
 echo "== Deployment tooling tokens (local) =="
 warn_var VERCEL_TOKEN
-warn_var RAILWAY_TOKEN
 warn_var GITHUB_TOKEN
 
 if [ "$failures" -ne 0 ]; then

From 472f53a32e8adc7562d085a98d822020fcc6269c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 20:07:26 +0900
Subject: [PATCH 08/10] ci: replace Railway deploy hooks with auto-deploy
 strategy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Railway does not support deploy hook URLs (feature not implemented).
Remove curl-based Railway deployment steps and rely on Railway's
built-in GitHub auto-deploy with "Check Suites" (Wait for CI).

Flow: push → GitHub Actions CI passes → Railway detects → auto-deploy.
No RAILWAY_TOKEN or deploy hook secrets needed for Railway.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .github/workflows/ci-cd.yml | 24 ++++++------------------
 1 file changed, 6 insertions(+), 18 deletions(-)

diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
index 30ca4ab..d5dc3c8 100644
--- a/.github/workflows/ci-cd.yml
+++ b/.github/workflows/ci-cd.yml
@@ -103,15 +103,9 @@ jobs:
             attempt=$((attempt + 1))
           done
 
-      - name: Trigger API deployment (Railway)
-        env:
-          RAILWAY_DEPLOY_HOOK: ${{ secrets.RAILWAY_DEV_DEPLOY_HOOK }}
-        run: |
-          if [ -z "$RAILWAY_DEPLOY_HOOK" ]; then
-            echo "RAILWAY_DEV_DEPLOY_HOOK secret is not configured." >&2
-            exit 1
-          fi
-          curl -fsSL -X POST "$RAILWAY_DEPLOY_HOOK"
+      # Railway: auto-deploys from dev branch via GitHub integration.
+      # No CLI or deploy hook needed — Railway watches this branch
+      # and waits for CI checks to pass ("Check Suites" enabled).
 
   deploy-production:
     if: github.ref == 'refs/heads/main'
@@ -168,12 +162,6 @@ jobs:
             attempt=$((attempt + 1))
           done
 
-      - name: Trigger API deployment (Railway)
-        env:
-          RAILWAY_DEPLOY_HOOK: ${{ secrets.RAILWAY_PROD_DEPLOY_HOOK }}
-        run: |
-          if [ -z "$RAILWAY_DEPLOY_HOOK" ]; then
-            echo "RAILWAY_PROD_DEPLOY_HOOK secret is not configured." >&2
-            exit 1
-          fi
-          curl -fsSL -X POST "$RAILWAY_DEPLOY_HOOK"
+      # Railway: auto-deploys from main branch via GitHub integration.
+      # No CLI or deploy hook needed — Railway watches this branch
+      # and waits for CI checks to pass ("Check Suites" enabled).

From a131eceb51ec027f5dd9eb0d3983b9d9aa8cfc5b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 20:08:45 +0900
Subject: [PATCH 09/10] docs: add Codex handoff prompt for Railway auto-deploy
 verification

Include verification checklist, follow-up tasks, and quick commands
for continuing the Railway auto-deploy setup in Codex.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CODEX_HANDOFF.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 CODEX_HANDOFF.md

diff --git a/CODEX_HANDOFF.md b/CODEX_HANDOFF.md
new file mode 100644
index 0000000..ef13ff7
--- /dev/null
+++ b/CODEX_HANDOFF.md
@@ -0,0 +1,124 @@
+# Codex Handoff: Railway Auto-Deploy 검증 및 후속 작업
+
+## 현재 상태
+- **PR**: https://github.com/doublesilver/knowledge-copilot/pull/8
+- **브랜치**: `chore/railway-auto-deploy` (base: `main`)
+- **변경 내용**: Railway deploy hook/CLI 스텝 제거, GitHub Auto-deploy 전략으로 전환
+- **삭제된 시크릿**: `RAILWAY_TOKEN`, `RAILWAY_SERVICE_NAME`, `RAILWAY_DEV_ENVIRONMENT`
+- **남은 시크릿**: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`, `VERCEL_SCOPE`
+
+## 아키텍처
+```
+doublesilver/knowledge-copilot
+├── app/          # Next.js frontend → Vercel (GitHub Actions에서 배포)
+├── api/          # Python FastAPI backend → Railway (auto-deploy)
+└── .github/workflows/ci-cd.yml
+```
+
+### 배포 플로우 (변경 후)
+```
+push to dev/main
+  → GitHub Actions: checks job (FE build + BE test)
+  → GitHub Actions: Vercel deploy (FE)
+  → Railway: auto-deploy (BE) — CI 통과 후 자동 (Check Suites)
+```
+
+---
+
+## Codex 프롬프트 (복사해서 사용)
+
+```
+너는 doublesilver/knowledge-copilot 프로젝트의 CI/CD 파이프라인을 검증하고 후속 작업을 수행해야 한다.
+
+## 배경
+- PR #8 (chore/railway-auto-deploy)에서 Railway deploy hook 스텝을 제거하고
+  Railway의 GitHub Auto-deploy + Check Suites 방식으로 전환함
+- Railway에는 "Deploy Hook URL" 기능이 존재하지 않음 (feature request 상태)
+- GitHub Actions는 CI 검증 + Vercel 배포만 담당, Railway 배포는 Railway가 자체 처리
+
+## 검증 체크리스트
+
+### 1. PR 상태 확인
+gh pr view 8 --repo doublesilver/knowledge-copilot
+- CI checks가 통과했는지 확인
+- 실패 시 로그를 분석하고 수정
+
+### 2. GitHub secrets 확인
+gh secret list --repo doublesilver/knowledge-copilot
+- RAILWAY_* 시크릿이 없어야 함 (이미 삭제됨)
+- Vercel 시크릿 4개만 존재해야 함: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID, VERCEL_SCOPE
+
+### 3. 워크플로우 문법 검증
+.github/workflows/ci-cd.yml 파일을 읽고:
+- YAML 문법 오류 없는지 확인
+- checks → deploy-development / deploy-production 의존 관계 정상인지 확인
+- Railway 관련 스텝이 완전히 제거되었는지 확인 (curl, railway CLI 호출 없어야 함)
+- Vercel 배포 스텝이 정상 동작할 수 있는지 확인
+
+### 4. Railway 대시보드 설정 안내 (자동화 불가, 수동 필요)
+사용자에게 아래 Railway 대시보드 설정을 안내:
+
+a) railway.com → knowledge-copilot 프로젝트 → API 서비스 클릭
+b) Settings → Source 섹션:
+   - Connect Repo: doublesilver/knowledge-copilot
+   - Root Directory: /api
+c) Development 환경:
+   - Branch: dev
+   - Check Suites: ON (활성화)
+d) Production 환경:
+   - Branch: main
+   - Check Suites: ON (활성화)
+
+### 5. PR 머지 판단
+- CI 통과 + 검증 완료 시 PR 머지 추천 여부를 판단
+- 머지 후 main에서 Railway auto-deploy가 트리거되는지 확인
+
+## 후속 작업 (선택)
+
+### A. dev 브랜치 동기화
+PR이 main에 머지된 후:
+git checkout dev && git merge main && git push origin dev
+→ dev 환경도 auto-deploy 트리거됨
+
+### B. 기존 deploy hook 브랜치 정리
+chore/railway-no-token-deploy 브랜치 삭제:
+gh api repos/doublesilver/knowledge-copilot/git/refs/heads/chore/railway-no-token-deploy -X DELETE
+gh api repos/doublesilver/knowledge-copilot/git/refs/heads/chore/refresh-secrets -X DELETE
+gh api repos/doublesilver/knowledge-copilot/git/refs/heads/chore/fix-vercel-deploy -X DELETE
+gh api repos/doublesilver/knowledge-copilot/git/refs/heads/chore/fix-vercel-deploy-flags -X DELETE
+
+### C. E2E 배포 검증
+dev 브랜치에 테스트 커밋을 push하고:
+1. GitHub Actions CI가 통과하는지 확인
+2. Railway가 자동 배포하는지 확인 (Railway 대시보드에서 deployment 상태 확인)
+3. API health check: curl https://<railway-url>/api/v1/health
+
+### D. README 업데이트
+배포 방식 변경을 README나 docs/DEPLOY_VERCEL_RAILWAY.md에 반영:
+- "Railway CLI 배포" → "Railway Auto-deploy (Check Suites)"
+- RAILWAY_TOKEN 관련 설명 제거
+- 새 배포 플로우 다이어그램 추가
+
+## 주의사항
+- Railway 대시보드 설정(Check Suites 활성화)은 CLI/API로 자동화 불가 — 반드시 수동
+- Vercel 배포는 기존과 동일하게 GitHub Actions에서 처리
+- Railway auto-deploy는 GitHub push webhook을 기반으로 작동하므로
+  Railway GitHub App이 레포에 설치되어 있어야 함
+```
+
+---
+
+## 빠른 검증 명령어
+```bash
+# PR 상태
+gh pr view 8 --repo doublesilver/knowledge-copilot
+
+# CI 실행 상태
+gh run list --repo doublesilver/knowledge-copilot --limit 5
+
+# 시크릿 확인
+gh secret list --repo doublesilver/knowledge-copilot
+
+# 워크플로우 문법 검증 (act 사용 시)
+act -n --workflows .github/workflows/ci-cd.yml
+```

From 23162a956d3ba44f6f8e0b9adbdabccabd6b40bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EC=9D=B4=EC=9D=80=EC=84=9D?= <korea5410@gmail.com>
Date: Fri, 27 Feb 2026 20:10:53 +0900
Subject: [PATCH 10/10] docs: rewrite Codex handoff for CLI workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructure as step-by-step Codex CLI prompt with:
- Sequential verification → merge → sync → cleanup → docs → e2e
- Copy-paste ready gh/git commands
- Manual Railway dashboard checklist clearly separated

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CODEX_HANDOFF.md | 194 +++++++++++++++++++++--------------------------
 1 file changed, 85 insertions(+), 109 deletions(-)

diff --git a/CODEX_HANDOFF.md b/CODEX_HANDOFF.md
index ef13ff7..94e73e2 100644
--- a/CODEX_HANDOFF.md
+++ b/CODEX_HANDOFF.md
@@ -1,124 +1,100 @@
-# Codex Handoff: Railway Auto-Deploy 검증 및 후속 작업
+# Codex CLI Handoff: Railway Auto-Deploy 검증 및 후속 작업
 
-## 현재 상태
-- **PR**: https://github.com/doublesilver/knowledge-copilot/pull/8
-- **브랜치**: `chore/railway-auto-deploy` (base: `main`)
-- **변경 내용**: Railway deploy hook/CLI 스텝 제거, GitHub Auto-deploy 전략으로 전환
-- **삭제된 시크릿**: `RAILWAY_TOKEN`, `RAILWAY_SERVICE_NAME`, `RAILWAY_DEV_ENVIRONMENT`
-- **남은 시크릿**: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`, `VERCEL_SCOPE`
+> **사용법**: 아래 프롬프트를 Codex CLI에서 그대로 붙여넣기
+>
+> ```bash
+> cd /path/to/knowledge-copilot   # 또는 git clone 후 진입
+> codex                            # Codex CLI 실행
+> # 아래 프롬프트 붙여넣기
+> ```
 
-## 아키텍처
-```
-doublesilver/knowledge-copilot
-├── app/          # Next.js frontend → Vercel (GitHub Actions에서 배포)
-├── api/          # Python FastAPI backend → Railway (auto-deploy)
-└── .github/workflows/ci-cd.yml
-```
+---
+
+## Codex CLI 프롬프트
 
-### 배포 플로우 (변경 후)
-```
-push to dev/main
-  → GitHub Actions: checks job (FE build + BE test)
-  → GitHub Actions: Vercel deploy (FE)
-  → Railway: auto-deploy (BE) — CI 통과 후 자동 (Check Suites)
 ```
+레포 doublesilver/knowledge-copilot의 CI/CD 파이프라인 검증 및 후속 작업을 수행해.
+이 레포의 CODEX_HANDOFF.md에 전체 컨텍스트가 있으니 먼저 읽어.
 
----
+## 컨텍스트 (빠른 요약)
+- PR #8 (chore/railway-auto-deploy): Railway deploy hook/CLI 스텝 제거, Auto-deploy 전환
+- Railway에 "Deploy Hook URL" 기능이 없어서, Railway의 GitHub Auto-deploy + Check Suites 사용
+- GitHub Actions는 CI + Vercel 배포만 담당. Railway는 CI 통과 감지 후 자체 auto-deploy
+- 프로젝트 구조: app/ (Next.js→Vercel), api/ (FastAPI→Railway)
+- 삭제된 시크릿: RAILWAY_TOKEN, RAILWAY_SERVICE_NAME, RAILWAY_DEV_ENVIRONMENT
+- 남은 시크릿: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID, VERCEL_SCOPE
 
-## Codex 프롬프트 (복사해서 사용)
+## Step 1: 검증 (순서대로 실행)
 
-```
-너는 doublesilver/knowledge-copilot 프로젝트의 CI/CD 파이프라인을 검증하고 후속 작업을 수행해야 한다.
-
-## 배경
-- PR #8 (chore/railway-auto-deploy)에서 Railway deploy hook 스텝을 제거하고
-  Railway의 GitHub Auto-deploy + Check Suites 방식으로 전환함
-- Railway에는 "Deploy Hook URL" 기능이 존재하지 않음 (feature request 상태)
-- GitHub Actions는 CI 검증 + Vercel 배포만 담당, Railway 배포는 Railway가 자체 처리
-
-## 검증 체크리스트
-
-### 1. PR 상태 확인
-gh pr view 8 --repo doublesilver/knowledge-copilot
-- CI checks가 통과했는지 확인
-- 실패 시 로그를 분석하고 수정
-
-### 2. GitHub secrets 확인
-gh secret list --repo doublesilver/knowledge-copilot
-- RAILWAY_* 시크릿이 없어야 함 (이미 삭제됨)
-- Vercel 시크릿 4개만 존재해야 함: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID, VERCEL_SCOPE
-
-### 3. 워크플로우 문법 검증
-.github/workflows/ci-cd.yml 파일을 읽고:
-- YAML 문법 오류 없는지 확인
-- checks → deploy-development / deploy-production 의존 관계 정상인지 확인
-- Railway 관련 스텝이 완전히 제거되었는지 확인 (curl, railway CLI 호출 없어야 함)
-- Vercel 배포 스텝이 정상 동작할 수 있는지 확인
-
-### 4. Railway 대시보드 설정 안내 (자동화 불가, 수동 필요)
-사용자에게 아래 Railway 대시보드 설정을 안내:
-
-a) railway.com → knowledge-copilot 프로젝트 → API 서비스 클릭
-b) Settings → Source 섹션:
-   - Connect Repo: doublesilver/knowledge-copilot
-   - Root Directory: /api
-c) Development 환경:
-   - Branch: dev
-   - Check Suites: ON (활성화)
-d) Production 환경:
-   - Branch: main
-   - Check Suites: ON (활성화)
-
-### 5. PR 머지 판단
-- CI 통과 + 검증 완료 시 PR 머지 추천 여부를 판단
-- 머지 후 main에서 Railway auto-deploy가 트리거되는지 확인
-
-## 후속 작업 (선택)
-
-### A. dev 브랜치 동기화
-PR이 main에 머지된 후:
-git checkout dev && git merge main && git push origin dev
-→ dev 환경도 auto-deploy 트리거됨
-
-### B. 기존 deploy hook 브랜치 정리
-chore/railway-no-token-deploy 브랜치 삭제:
-gh api repos/doublesilver/knowledge-copilot/git/refs/heads/chore/railway-no-token-deploy -X DELETE
-gh api repos/doublesilver/knowledge-copilot/git/refs/heads/chore/refresh-secrets -X DELETE
-gh api repos/doublesilver/knowledge-copilot/git/refs/heads/chore/fix-vercel-deploy -X DELETE
-gh api repos/doublesilver/knowledge-copilot/git/refs/heads/chore/fix-vercel-deploy-flags -X DELETE
-
-### C. E2E 배포 검증
-dev 브랜치에 테스트 커밋을 push하고:
-1. GitHub Actions CI가 통과하는지 확인
-2. Railway가 자동 배포하는지 확인 (Railway 대시보드에서 deployment 상태 확인)
-3. API health check: curl https://<railway-url>/api/v1/health
-
-### D. README 업데이트
-배포 방식 변경을 README나 docs/DEPLOY_VERCEL_RAILWAY.md에 반영:
-- "Railway CLI 배포" → "Railway Auto-deploy (Check Suites)"
+1-1. PR #8 CI 상태 확인
+  gh pr view 8 --repo doublesilver/knowledge-copilot
+  gh pr checks 8 --repo doublesilver/knowledge-copilot
+  → CI 실패 시: gh run view <run-id> --log-failed 로 원인 분석하고 수정 커밋
+
+1-2. 시크릿 확인
+  gh secret list --repo doublesilver/knowledge-copilot
+  → RAILWAY_* 시크릿이 0개여야 정상
+  → VERCEL_* 시크릿 4개만 존재해야 함
+
+1-3. 워크플로우 검증
+  .github/workflows/ci-cd.yml 파일을 읽고:
+  - railway, RAILWAY, deploy hook, curl.*railway 같은 Railway 관련 코드가 완전히 제거되었는지 grep
+  - checks → deploy-development / deploy-production 의존관계(needs: checks) 정상인지 확인
+  - Vercel 배포 스텝에 필요한 시크릿(VERCEL_TOKEN, VERCEL_SCOPE)이 참조되는지 확인
+
+## Step 2: PR 머지 (검증 통과 시)
+
+  gh pr merge 8 --repo doublesilver/knowledge-copilot --squash --delete-branch
+
+## Step 3: dev 브랜치 동기화
+
+  git checkout main && git pull origin main
+  git checkout dev && git merge main && git push origin dev
+
+## Step 4: 기존 불필요 브랜치 정리
+
+아래 브랜치들을 리모트에서 삭제:
+  git push origin --delete chore/railway-no-token-deploy 2>/dev/null || true
+  git push origin --delete chore/refresh-secrets 2>/dev/null || true
+  git push origin --delete chore/fix-vercel-deploy 2>/dev/null || true
+  git push origin --delete chore/fix-vercel-deploy-flags 2>/dev/null || true
+
+## Step 5: 배포 문서 업데이트
+
+docs/DEPLOY_VERCEL_RAILWAY.md 파일이 있으면 아래 내용 반영:
+- "Railway CLI 배포" 또는 "railway up" 관련 설명 → "Railway Auto-deploy (Check Suites)" 로 변경
 - RAILWAY_TOKEN 관련 설명 제거
-- 새 배포 플로우 다이어그램 추가
+- 배포 플로우를 아래로 업데이트:
+  push → GitHub Actions CI → Vercel deploy (FE) + Railway auto-deploy (BE, CI 통과 후)
+- 변경 시 커밋: git add docs/ && git commit -m "docs: update deploy guide for Railway auto-deploy"
+- git push origin dev
 
-## 주의사항
-- Railway 대시보드 설정(Check Suites 활성화)은 CLI/API로 자동화 불가 — 반드시 수동
-- Vercel 배포는 기존과 동일하게 GitHub Actions에서 처리
-- Railway auto-deploy는 GitHub push webhook을 기반으로 작동하므로
-  Railway GitHub App이 레포에 설치되어 있어야 함
-```
+## Step 6: E2E 배포 검증
 
----
+dev 브랜치에서 테스트:
+1. gh run list --repo doublesilver/knowledge-copilot --branch dev --limit 3
+   → 최근 CI가 통과했는지 확인
+2. Railway 대시보드에서 dev 환경 배포 상태 확인 (자동화 불가, 사용자에게 안내)
+3. API health check URL이 있으면 curl로 확인
 
-## 빠른 검증 명령어
-```bash
-# PR 상태
-gh pr view 8 --repo doublesilver/knowledge-copilot
+## 수동 작업 안내 (사용자에게 출력)
 
-# CI 실행 상태
-gh run list --repo doublesilver/knowledge-copilot --limit 5
+아래는 Codex가 자동화할 수 없는 Railway 대시보드 설정이야.
+사용자에게 아래 체크리스트를 출력해:
 
-# 시크릿 확인
-gh secret list --repo doublesilver/knowledge-copilot
+```
+Railway 대시보드 수동 설정 체크리스트:
+[ ] railway.com → knowledge-copilot 프로젝트 → API 서비스 → Settings
+[ ] Source → Connect Repo: doublesilver/knowledge-copilot, Root: /api
+[ ] Development 환경 → Branch: dev, Check Suites: ON
+[ ] Production 환경 → Branch: main, Check Suites: ON
+[ ] Railway GitHub App이 레포에 설치되어 있는지 확인
+    (GitHub → Settings → Integrations → Railway 확인)
+```
 
-# 워크플로우 문법 검증 (act 사용 시)
-act -n --workflows .github/workflows/ci-cd.yml
+## 주의사항
+- Railway 대시보드 설정(Check Suites)은 API/CLI로 자동화 불가. 반드시 수동
+- PR 머지 전에 CI가 통과했는지 반드시 확인
+- dev 브랜치 동기화 전에 main이 최신인지 확인
+- CODEX_HANDOFF.md 파일은 모든 작업 완료 후 삭제해도 됨
 ```