failproofai 1.0.1-beta.1 → 1.0.2-beta.0

package/.next/standalone/docs-old/ko/agenteye/api-keys.mdx

@@ -0,0 +1,280 @@
+---
+title: "API Keys"
+description: "API keys는 Failproof AI Observability 서버에 접근할 수 있는 대상을 제어하므로, 컬렉터는 읽기 또는 관리자 권한 없이도 이벤트를 전송할 수 있습니다."
+---
+
+
+API keys는 Failproof AI Observability 서버에 접근할 수 있는 대상을 제어하므로, 컬렉터는 읽기 또는 관리자 권한 없이도 이벤트를 전송할 수 있습니다. 각 키는 하나 이상의 권한을 가지며, 각 권한은 특정 서버 라우트를 제어합니다. 작업에 필요한 최소한의 권한만 부여하세요. 대부분의 배포 환경에서는 세 가지 종류의 키만 생성합니다.
+
+## 대부분의 배포 환경에서 필요한 3가지 키
+
+| 키 | 권한 | 사용자 |
+|---|---|---|
+| 컬렉터 키 | `events:add` | 각 에이전트 머신의 `agenteye-collector`로, 이벤트를 전송하는 데 사용합니다. |
+| 대시보드 읽기 키 | `events:read`, `keys:read` | 데이터를 변경하지 않고 조회만 하는 읽기 전용 운영자 또는 통합 시스템. |
+| 부트스트랩 관리자 키 | 모든 권한 | 인스턴스와 대시보드를 처음 구동하는 운영자. `ADMIN_KEY` 환경 변수로 시드됩니다. [부트스트랩 관리자 키](#bootstrap-admin-key)를 참조하세요. |
+
+여기서 시작하세요. 더 세분화된 커스텀 스코프 키가 필요한 경우에만 아래의 전체 권한 목록을 참조하세요. [권장 키 구성](#recommended-key-layout) 및 [키 생성](#creating-keys)도 참조하세요.
+
+---
+
+## 권한
+
+서버는 고정된 권한 목록을 적용하며, 각 권한은 특정 HTTP 라우트를 제어합니다. **관리자 키**는 모든 권한을 보유하며, 스코프 키는 생성 시 부여한 권한의 하위 집합을 보유합니다. 알 수 없는 권한 문자열은 키 생성 시 거부됩니다.
+
+> **참고:** 사람/대시보드 전용으로 유효하여 API key에는 부여할 수 없는 권한이 두 가지 있습니다: `orgs:admin`(인스턴스 관리, 운영자 전용)과 `keys:update`. 이 두 권한 중 하나를 부여하려는 `POST /keys` 또는 `PATCH /keys/:id` 요청은 HTTP 422로 거부됩니다. bearer 키가 키를 생성할 수 있지만 편집은 불가능한 이유에 대해서는 아래 `keys:update` 항목을 참조하세요.
+
+### 이벤트 수집 및 조회
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `events:add` | `POST /events` | 컬렉터로부터 이벤트 배치를 수집합니다. 컬렉터에 필요한 유일한 권한입니다. |
+| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | 이벤트 조회, 알려진 환경 목록 조회, 데이터에서 확인된 모델 식별자 목록 조회(Models 뷰 및 모델 필터에 사용), 히트맵/백분위 밴드를 지원하는 지연 시간 집계 계산, 세션을 JSONL로 내보내기. 공유 필터바 패싯 엔드포인트인 `GET /events/environments`와 `GET /events/agent_ids`는 `events:read` **또는** `evaluations:read` 중 하나로 접근 가능하므로, `evaluations:read`로 게이팅된 세션 페이지에서도 동일한 per-org 패싯을 재사용합니다. `GET /events/models`는 해당하지 않으며 `events:read`가 필요합니다. `evaluations:read`만 보유한 주체는 403을 받습니다. |
+
+### 세션 및 평가
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | 세션 목록 조회, 평가 결과 읽기, 대시보드에 사용되는 집계된 평가 상태, 평가 작업 워커 큐 상태. |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | 완료된 세션에 대해 재평가를 수동으로 큐에 추가합니다. |
+
+### 대시보드
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | 대시보드 목록 조회, 개별 로드, 타일 읽기. |
+| `dashboards:write` | `POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout` | 대시보드 생성 및 편집, 타일 추가/편집/삭제, 타일 그리드 순서 변경. |
+| `dashboards:delete` | `DELETE /dashboards/:id` | 전체 대시보드 삭제(타일 수준 삭제는 `dashboards:write` 아래에 있음). |
+
+### 저장된 쿼리 (SQL 컴포저)
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | 저장된 쿼리 목록 조회, 개별 로드, 컴포저가 대상으로 하는 읽기 전용 스키마 검사. |
+| `queries:write` | `POST /queries`, `PUT /queries/:id` | 저장된 쿼리 생성 및 편집. SQL은 여전히 `queries:run` 호출과 동일한 읽기 전용 역할 및 보호된 SQL 검사를 통해 라우팅됩니다. |
+| `queries:delete` | `DELETE /queries/:id` | 저장된 쿼리 삭제. |
+| `queries:run` | `POST /queries/run` | 컴포저에서 사용하는 읽기 전용 역할에 대해 저장된 또는 임시 SQL을 실행합니다. |
+
+### AI 어시스턴트
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `agent:use` | `GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages` | AI 어시스턴트와 대화하고 자신의 (비공개) 대화를 관리합니다. 어시스턴트 독을 보려면 **사용자**에게 필요합니다. 어시스턴트 자체 키는 `dashboard-assistant`이며 별도로 시드됩니다(아래 참조). |
+
+### API Keys
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `keys:create` | `POST /keys` | 새로운 스코프 API key를 생성합니다. 기존 키의 권한 편집은 허용하지 **않습니다**(그것은 `keys:update`). |
+| `keys:read` | `GET /keys` | 기존 키 목록을 조회합니다. 시크릿은 이 엔드포인트에서 반환되지 않습니다. |
+| `keys:update` | `PATCH /keys/:id` | 기존 키의 권한을 편집합니다. **사람/대시보드 전용** 권한으로 API key에 할당할 수 없습니다(bearer 키는 키를 생성할 수 있지만 편집은 불가능). |
+| `keys:disable` | `POST /keys/:id/disable` | 키를 취소합니다. 보호된 키(`admin`, `dashboard-assistant`)는 비활성화할 수 없으며, 환경 변수 변경 후 재시작으로 교체하세요. |
+| `keys:regenerate` | `POST /keys/:id/regenerate` | 키의 시크릿을 교체합니다. 보호된 키는 이 라우트를 통해 재생성할 수 없습니다. |
+
+### 대시보드 사용자
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `users:create` | `POST /users`, `GET /users/defaults` | 새 대시보드 사용자를 초대하고(이메일 + 일회용 패스코드(OTP) 로그인 발급), 초대 양식 시드에 사용되는 대시보드 구성 기본 권한 집합을 읽습니다. |
+| `users:read` | `GET /users`, `GET /users/:id` | 사용자 목록 조회 및 단일 사용자 레코드 로드. |
+| `users:update` | `PUT /users/:id` | 사용자의 권한을 편집합니다. 업데이트 시 영향받는 사용자에게 권한 변경 이메일이 발송되며, 다음 요청부터 적용됩니다. 재로그인은 불필요합니다. |
+| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | 사용자를 비활성화(세션 즉시 취소)하거나 이전에 비활성화된 사용자를 재활성화합니다. |
+
+이 권한들은 대시보드의 **Users** 페이지를 지원하며, 각 멤버의 부여된 스코프가 칩으로 표시됩니다:
+
+![Users 페이지: 각 대시보드 사용자의 이메일, 부여된 권한, 편집/비활성화 컨트롤이 포함된 카드](/agenteye/images/users.png)
+
+### 운영 설정
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | 대시보드 관리 운영 설정 및 메타데이터 보기, per-model 컨텍스트 윈도우 오버라이드 목록 조회, 모델의 유효 윈도우 확인. |
+| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | 운영 설정 편집 및 per-model 컨텍스트 윈도우 오버라이드 추가, 변경, 삭제. 변경사항은 서버 재시작 없이 새 이벤트에 적용됩니다. |
+
+![Settings 페이지: 허용 로그인 방법, 세션/OTP 유효기간 등 대시보드 관리 운영 설정을 재시작 없이 편집 가능](/agenteye/images/settings.png)
+
+### 알림 및 인시던트
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | 구성된 알림 정의 보기. |
+| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | 알림 정의 생성, 편집, 삭제, 테스트 발송. |
+| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | 인시던트 및 트리아지 기록 보기. |
+| `incidents:write` | `POST /alerts/:id/incidents` | 기존 알림에 대해 수동으로 인시던트를 개시합니다. |
+| `incidents:ack` | `POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe` | 인시던트 확인, 담당자 지정, 해결, 댓글 작성. |
+
+### 감사
+
+| 권한 | HTTP 라우트 | 허용 범위 |
+|---|---|---|
+| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | 감사 정의, 실행 기록, 결과 보기. |
+| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | 감사 생성, 편집, 삭제, 실행, 결과 트리아지(확인/음소거/해제/해결/재개/담당자 지정). |
+
+> **참고:** 키에 감사 기능을 부여하려면 `audits:*`를 명시적으로 부여하세요. Audits 출시 시 기존 권한 보유자가 어떻게 마이그레이션되었는지는 [업그레이드 및 하위 호환성 참고사항](#upgrade-and-backward-compatibility-notes)을 참조하세요.
+
+> 수신자 선택기 엔드포인트 `GET /alerts/recipients`(알림 편집자가 알림을 보낼 수 있는 멤버 이메일 목록)는 `alerts:read` **또는** `alerts:write` 중 하나를 보유한 사용자가 접근 가능하므로, 알림 편집자는 `users:read` 없이도 선택기를 사용할 수 있습니다.
+
+> 대시보드 뷰어는 `dashboards:read`(저장된 뷰 로드)와 `evaluations:read`(상태 메트릭이 평가 데이터에서 계산됨) **둘 다** 필요합니다. 사용자가 대시보드를 생성하거나 편집하려면 `dashboards:write`를, 삭제하려면 `dashboards:delete`를 부여하세요.
+
+> `/health`와 `/auth/*`(OTP 요청, OTP 검증, 세션 확인, 로그아웃)는 설계상 인증이 필요 없으며, 로그인 흐름 및 생존 확인용입니다. `GET /access-granters`는 유효한 키가 필요하지만 특정 권한은 불필요하므로, 로그인한 모든 사용자가 액세스 변경에 대해 문의할 관리자를 확인할 수 있습니다.
+
+---
+
+## 권한 집합
+
+권한 집합을 사용하면 매번 개별 토큰을 직접 선택하는 대신 명명된 역할을 적용할 수 있습니다. 새 대시보드 사용자나 API key마다 수십 개의 권한을 일일이 선택하는 대신 집합을 선택하면, 해당 집합에 할당된 모든 사람이 일관되고 검토 가능한 권한을 보유합니다. 커스텀 집합을 편집하면 이미 할당된 모든 사용자에게 새 권한이 재적용되므로, 역할 변경이 모든 멤버를 일일이 수정하는 대신 한 번의 편집으로 완료됩니다.
+
+모든 조직에는 세 가지 기본 집합이 시드됩니다:
+
+| 집합 | 권한 | 대상 |
+|---|---|---|
+| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | 모든 운영 영역에 대한 읽기 전용 접근. |
+| `standard` | `read-only`의 모든 권한 + `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | 읽기 전용 + 일상적인 온콜 작업: 쿼리 실행, 세션 재평가, 인시던트 확인, AI 어시스턴트 사용. |
+| `admin` | 모든 할당 가능한 권한 | 조직의 완전한 제어. |
+
+세 가지 기본 집합은 **변경 불가**합니다. `read-only`, `standard`, `admin`은 항상 동일한 의미를 가지므로 정책 및 온보딩에서 안전하게 참조할 수 있습니다. 운영자는 조직 특화 역할(예: "대시보드 작성자" 역할 또는 "컬렉터 전용" 역할)을 모델링하기 위해 추가적인 **커스텀 집합**을 생성할 수 있습니다.
+
+집합은 대시보드에 표시되며, API에서는 `GET /permission-sets`(목록, `users:read`로 게이팅)와 `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name`(커스텀 집합 생성, 편집, 삭제, `settings:write`로 게이팅)으로 관리됩니다. 기본 집합의 삭제 또는 편집은 거부됩니다.
+
+집합 멤버십은 두 가지 다른 기능을 지원합니다:
+
+- **`DEFAULT_USER_PERMISSIONS`**(관리자가 **+ 새 사용자**를 열 때 미리 선택된 권한)는 기본적으로 `standard` 집합으로 설정됩니다.
+- **`agenteye-orgctl`의 `--set` 플래그**(운영자 멤버 관리)는 명명된 집합에서 멤버를 시작하며, 이후 `--add` / `--remove`로 세부 조정할 수 있습니다.
+
+> **참고:** 집합에 키 할당 불가능한 권한이 포함된 경우(예: `keys:update`를 포함하는 커스텀 집합), 해당 집합에서 키를 시드할 때 할당 불가능한 토큰은 제외됩니다. 그렇지 않으면 서버가 HTTP 422로 키를 거부합니다. 대시보드 사용자에게는 이 제한이 적용되지 않습니다.
+
+---
+
+## 부트스트랩 관리자 키
+
+관리자 키는 운영자가 아무것도 없는 상태에서 액세스를 구축할 수 있게 해주는 단일 루트 자격 증명입니다. 이를 통해 다른 모든 스코프 키를 생성하고, 첫 번째 대시보드 사용자를 초대하고, 다른 키가 존재하기 전에 인스턴스를 구성할 수 있습니다. 이 키는 keys API를 통해 생성하지 않는 유일한 키이며, 서버가 처음 부팅 시 접근 가능하도록 환경에서 프로비저닝됩니다.
+
+서버의 `ADMIN_KEY` 환경 변수를 설정하세요. 모든 시작 시 서버는 이 값을 모든 권한을 가진 관리자 키로 upsert합니다.
+
+교체하려면: `ADMIN_KEY`를 새 시크릿으로 변경하고 서버를 재시작하세요.
+
+---
+
+## 조직 스코핑
+
+**조직 자체는 이 keys API가 아닌 운영자가 대역 외에서 생성하고 관리합니다.** 조직 및 멤버 생명주기(조직 생성/이름 변경/삭제/제거, 멤버 추가/업데이트/제거)는 **`agenteye-orgctl`** CLI로 수행하며, HTTP API나 대시보드 버튼이 없습니다. **변경되지 않는 것은: per-org API keys는 여전히 조직 멤버가 대시보드(또는 이 keys API를 통해) 발행합니다.**
+
+멀티 조직 배포에서 조직 멤버가 생성하는 모든 키(이 keys API 또는 대시보드 **Keys** 페이지를 통해)는 **하나의 조직**에 속하며 해당 조직의 데이터만 읽거나 쓸 수 있습니다. 조직은 키 생성 시 스탬프되어 모든 요청에서 적용됩니다. 두 가지 부트스트랩 키만 예외입니다: `admin` 키(`ADMIN_KEY`에서 시드)와 `dashboard-assistant` 키(`AGENT_API_KEY`에서 시드)는 **인스턴스 스코프**(조직 없음)입니다. 대시보드는 `admin` 키로 인증하여 로그인한 멤버를 대신해 per-org 요청을 프록시합니다. 단일 테넌트 배포는 이를 신경 쓸 필요가 없으며, 모든 키는 기본 제공 `default` 조직에 속합니다.
+
+---
+
+## 키 생성
+
+관리자 키(또는 `keys:create` 권한을 가진 키)를 사용하여 추가적인 스코프 키를 생성하세요.
+
+### 컬렉터 키 (수집 전용)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "prod-collector",
+    "key": "your-collector-secret",
+    "permissions": ["events:add"]
+  }'
+```
+
+### 대시보드 키 (읽기 전용)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "dashboard",
+    "key": "your-dashboard-secret",
+    "permissions": ["events:read", "keys:read"]
+  }'
+```
+
+HTTP API로 키를 생성할 때는 `key` 값을 직접 제공합니다. 강력한 시크릿을 선택하고 안전하게 보관하세요. (대시보드는 반대 방식으로 동작합니다: 강력한 시크릿을 생성하여 생성 시 한 번만 표시합니다. [대시보드의 키 관리](#key-management-in-the-dashboard)를 참조하세요.) 응답은 키가 생성되었음을 확인합니다:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "prod-collector",
+  "permissions": ["events:add"],
+  "created_at": "2026-04-01T12:00:00Z"
+}
+```
+
+---
+
+## 키 목록 조회
+
+```bash
+curl -s http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+키 시크릿은 목록 응답에서 반환되지 않으며, ID, 이름, 권한만 반환됩니다.
+
+---
+
+## 키 비활성화
+
+비활성화는 키 레코드를 삭제하지 않고 즉시 액세스를 취소합니다.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/disable \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+---
+
+## 키 재생성
+
+기존 키의 새 시크릿을 생성합니다. 이전 시크릿은 즉시 무효화됩니다.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/regenerate \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+응답에는 새 평문 시크릿이 포함되며, **한 번만 표시됩니다**.
+
+---
+
+## 대시보드의 키 관리
+
+대시보드의 **Keys** 페이지는 위의 모든 작업을 위한 UI를 제공합니다. 목록을 보려면 `keys:read` 권한이 있는 키가 필요하고, 생성/편집/비활성화/재생성 작업에는 각각 `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate`가 필요합니다. 키의 권한 편집(`keys:update`)은 키 생성(`keys:create`)과 별개이므로, 운영자에게 기존 키의 스코프 변경 없이 키 발행 권한만 부여하거나, 그 반대도 가능합니다. 관리자 키는 이 모든 것을 포함합니다.
+
+대시보드에서 키를 생성할 때 시크릿을 직접 입력하지 않습니다. 대시보드가 강력한 시크릿을 생성하여 생성 시 **한 번** 표시합니다. 즉시 복사하여 안전하게 보관하세요. 재생성과 마찬가지로 다시는 표시되지 않습니다. 키의 권한을 직접 선택하거나 권한 집합에서 시드할 수 있습니다(아래 참조).
+
+![API Keys 페이지: 각 키의 이름, 부여된 권한, 생성 시간이 표시된 카드, 재생성 및 비활성화 액션 포함; `admin` 같은 보호된 키는 표시됨](/agenteye/images/api-keys.png)
+
+---
+
+## 권장 키 구성
+
+| 키 | 권한 | 사용자 |
+|---|---|---|
+| `admin` (`ADMIN_KEY` 환경 변수로 부트스트랩) | 모든 권한 | 운영/설정, 및 대시보드(`ADMIN_KEY`로 인증, 권한 검사를 통해 사용자 요청 프록시) |
+| 호스트별 컬렉터 키 | `events:add` | 각 에이전트 머신의 컬렉터 |
+| `dashboard-assistant` (`AGENT_API_KEY` 환경 변수로 부트스트랩) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | AI 어시스턴트, 자동으로 시드됨, **보호됨**; API를 통해 편집 불가 |
+| 어시스턴트 텔레메트리 키 (선택사항) | `events:add` | 활성화된 경우 AI 어시스턴트 자체 계측 |
+
+> **참고:** 어시스턴트 키는 서버가 `AGENT_API_KEY` 환경 변수(에이전트가 `AGENTEYE_API_KEY`로 제공하는 동일한 시크릿)에서 **자동으로 시드**합니다. 수동 키 발행 단계나 관리자 키가 필요하지 않습니다. 권한은 소스 코드에 고정되어 잘못된 구성으로 스코프가 확장되지 않습니다: 이벤트/평가/대시보드 읽기, 대시보드 쓰기, 쿼리 읽기/쓰기/실행(AI에게 쿼리 작성 요청 흐름용). 모든 SQL은 여전히 사용자 작성 쿼리와 동일한 읽기 전용 역할 및 보호된 SQL 경로를 거치므로, 이는 *데이터 표면*이 아닌 *작성 표면*을 확장합니다. 파괴적 작업(`queries:delete`, `dashboards:delete`)은 의도적으로 어시스턴트 키에서 제외됩니다. `admin` 키와 마찬가지로 **보호됨**: keys API를 통해 비활성화하거나 재생성할 수 없으며, `AGENT_API_KEY`를 변경하고 재시작해야만 교체됩니다. 대시보드 *사용자*는 어시스턴트를 보고 사용하려면 추가로 `agent:use` 권한이 필요합니다. 자체 계측을 활성화하는 경우, 어시스턴트에게 별도의 `events:add` 전용 키를 부여하세요.
+
+---
+
+## 업그레이드 및 하위 호환성 참고사항
+
+기존 인스턴스를 업그레이드하는 경우에만 필요합니다. 신규 배포는 건너뛰어도 됩니다.
+
+> Audits 출시 시, 기존 권한 보유자는 알림과 동일한 역할 형태에 따라 확장되었습니다: `alerts:read`를 보유한 모든 사용자 및 권한 집합은 `audits:read`를 획득했고, `alerts:write` 보유자는 `audits:write`를 획득했습니다. 기존 API keys는 **확장되지 않았습니다**. 감사 기능이 필요한 키에는 `audits:*`를 명시적으로 부여하세요.
+
+> 레거시 `alerts:ack` 토큰의 저장된 권한 부여는 `incidents:ack`로 파싱되어, 온콜 담당자가 키 재발행 없이 액세스를 유지합니다. 이 토큰은 더 이상 대시보드 사용자 편집기에서 할당할 수 없으며, 대신 `incidents:ack`가 제공됩니다.
+
+---
+
+## 다음 단계
+
+- [Python SDK](/ko/agenteye/python-sdk): 에이전트 코드가 이벤트를 전송할 때 인증하는 방법.
+- [Security](/ko/agenteye/security): 로그인, 액세스 제어, per-organization 데이터 격리 작동 방식.

package/.next/standalone/docs-old/ko/agenteye/assistant.mdx

@@ -0,0 +1,63 @@
+---
+title: "AI 어시스턴트"
+description: "에이전트 데이터에 대해 일반 영어로 질문하고, 근거로 바로 연결되는 답변을 받으세요."
+---
+
+
+에이전트 데이터에 대해 평문으로 질문하고, 근거로 바로 연결되는 답변을 받으세요. SQL을 작성하거나 대시보드를 뒤질 필요 없이 — **Failproof AI Observability** 어시스턴트는 팀 누구든 에이전트에 대한 답변을 가장 빠르게 얻을 수 있는 방법입니다.
+
+![대시보드 내에서 평문 질문에 답하는 Failproof AI Observability 어시스턴트. 실시간 Agent Activity 테이블, 에이전트별 모델 사용 현황, 작성된 인사이트, 그리고 실행된 쿼리가 인라인으로 표시됨](/agenteye/images/assistant.png)
+*평문으로 질문하면 내 데이터를 기반으로 한 답변을 받을 수 있습니다. 여기서는 어떤 에이전트가 가장 바쁘고 어떤 모델을 사용하는지 분석하며, 모든 숫자를 검증할 수 있도록 실행된 쿼리도 함께 보여줍니다.*
+
+별도로 배울 것이 없습니다. 채팅을 열고, 알고 싶은 것을 입력하고, 돌아온 링크를 따라가세요:
+
+```
+You:  which sessions errored today?
+AI:   5 sessions errored today, newest first. Each one is linked:
+      • checkout-agent   14:02   tool timeout
+      • billing-agent    11:47   unhandled error
+      • ...and 3 more
+
+You:  summarize this session          (asked while viewing a run)
+AI:   This run took 12 steps across 3 tools and failed near the end when a
+      payment tool returned an error. It scored low on your "resolved" eval.
+      Links: the session, the failing event, and that evaluation.
+```
+
+## 바로 질문하고, 증거로 바로 이동
+
+추측을 멈추고 쿼리 작성도 멈추세요. "이번 주 프로덕션에서 품질 트렌드는 어떤가요?", "오늘 오류가 발생한 세션은 무엇인가요?", "이 세션을 요약해 주세요" 같은 질문을 하면, 쿼리를 직접 작성하고 결과를 읽는 대신 몇 초 안에 명확한 답변을 얻을 수 있습니다.
+
+모든 답변에는 근거가 함께 제공됩니다. 어시스턴트는 답변 도출에 사용한 정확한 세션, 저장된 쿼리, 대시보드로의 링크를 제공하므로, 그냥 믿는 대신 직접 클릭해서 확인할 수 있습니다. 또한 **페이지 인식** 기능이 있어, 특정 세션을 보고 있는 상태에서 "이 세션"에 대해 질문하면 어떤 실행을 의미하는지 이미 알고 있습니다. 기록 전환기에서 이전 대화를 다시 열고 이어서 진행할 수도 있습니다.
+
+## 좋은 답변을 저장된 쿼리나 대시보드로 변환
+
+보관할 만한 답변이 있다면, 어시스턴트에게 저장을 요청하세요. 저장된 쿼리를 위한 SQL을 초안으로 작성하거나, 해당 쿼리들로 대시보드를 구성한 후 **승인 / 거부** 카드를 보여줍니다. 승인을 클릭하기 전까지는 아무것도 저장되지 않으므로, "그냥 물어보기"의 속도와 최종 결정권이 항상 내 손에 있는 장점을 모두 누릴 수 있습니다.
+
+**Queries** 페이지에서는 한 단계 더 나아가 SQL 작성자 역할을 합니다. 원하는 쿼리를 설명하면("지난 7일간 에이전트별 오류율 보기") SQL이 편집기에 바로 스트리밍되고, **수락** 또는 **거부**할 수 있는 diff 뷰가 열립니다.
+
+![Observability Queries 페이지와 SQL 편집기](/agenteye/images/query-lab.png)
+*Queries 페이지: 어시스턴트가 초안 읽기 전용 쿼리를 스트리밍하면 수락하거나 거부할 수 있는 편집기입니다.*
+
+여기서 질문을 통해 SQL을 작성하는 기능은 편집기의 **실행** 버튼과 동일한 `queries:run` 권한을 사용합니다. 다른 곳에서의 채팅에는 `agent:use` 권한이 필요합니다.
+
+## 팀 전체에 안심하고 공개 가능
+
+어시스턴트가 어떤 것을 건드릴지 걱정하지 않고 전체 팀에 공개할 수 있습니다:
+
+- **이미 볼 수 있는 것만 읽습니다.** 답변은 본인의 읽기 권한 범위 내로 제한되므로 데이터 접근 범위가 확장되지 않습니다.
+- **모든 쓰기 작업은 승인을 기다립니다.** 저장된 쿼리와 대시보드는 명시적인 승인 클릭 이후에만 생성되며, 이 게이트를 끄는 설정은 없습니다.
+- **절대 삭제할 수 없습니다.** 삭제 도구가 노출되지 않으며 어시스턴트는 삭제 권한을 가지지 않습니다. 삭제는 대시보드에서 내 손으로만 가능합니다.
+- **내 조직 내에서만 작동합니다.** 어시스턴트는 현재 보고 있는 조직만 접근할 수 있습니다.
+- **내 질문은 내 것입니다.** 프롬프트와 답변은 내 Observability 데이터베이스에 저장되며, 제품 분석은 사용 메타데이터만 기록하고 프롬프트 내용은 기록하지 않습니다.
+
+## 찾는 방법
+
+어시스턴트는 조직(`/<org-slug>/...`) 하위 모든 페이지의 오른쪽 가장자리에 표시됩니다. 레일을 클릭하거나 `⌘J` / `Ctrl+J`를 눌러 전체 채팅 패널로 확장하고, 가장자리를 드래그하여 크기를 조절할 수 있으며, 설정한 너비는 새로고침 후에도 유지됩니다. 사용하려면 **`agent:use`** 권한이 필요하며, 없을 경우 레일이 비활성화됩니다. 배포 환경에서 아직 활성화되지 않은 경우(LLM 연결이 필요함), 작동하는 채팅 대신 비활성화된 레일이 표시됩니다.
+
+## 관련 항목
+
+- [CLI and agents](/ko/agenteye/cli-and-agents)
+- [Queries](/ko/agenteye/queries)
+- [Dashboards](/ko/agenteye/dashboards)
+- [Evaluation suite](/ko/agenteye/evaluation-suite)

package/.next/standalone/docs-old/ko/agenteye/audits.mdx

@@ -0,0 +1,54 @@
+---
+title: "감사(Audits): 자동 신뢰성 분석가"
+description: "Failproof AI Observability는 여러분이 규칙으로 정의하지 않은 장애를 찾아내고, 정확히 무엇을 수정해야 하는지 우선순위와 근거가 담긴 목록으로 제공합니다."
+---
+
+
+Failproof AI Observability는 여러분이 규칙으로 정의하지 않은 장애를 찾아내고, 정확히 무엇을 수정해야 하는지 우선순위와 근거가 담긴 목록으로 제공합니다. 마치 분석가가 매일 밤 로그를 살펴보고, 아침이 되면 짧은 요약 목록을 책상 위에 남겨두는 것과 같습니다.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Watch: Automatically find where your agent is failing (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*2분 투어: 예약 실행부터 즉시 실행할 수 있는 수정 방안까지.*
+
+![감사(Audits) 페이지: 각 세션에서 장애 패턴을 스캔하는 반복 작업 목록으로, 일정과 민감도가 표시됩니다](/agenteye/images/audits.png)
+*각 감사(audit)는 세션 데이터를 분석하여 우선순위와 근거가 담긴 권고사항을 작성하는 반복 작업입니다.*
+
+## 다음에 무엇을 수정할지 추측하지 마세요
+
+알림은 이미 감시하고 있다고 알고 있는 문제를 잡아냅니다. 감사(Audits)는 여러분이 미처 몰랐던 문제를 잡아냅니다. 설정한 일정에 따라 감사는 모든 에이전트 세션을 읽고 수정할 가치가 있는 패턴을 찾아내므로, 직접 로그를 스크롤하며 눈으로 발견하는 대신 결과를 바탕으로 행동하는 데 시간을 쓸 수 있습니다.
+
+단 한 번의 실행으로 실제 프로덕션에서 에이전트를 망가뜨리는 장애 유형들을 집중적으로 검사합니다:
+
+- **오류 클러스터**: 동일한 근본 원인 아래 반복되는 장애.
+- **기준선 대비 드리프트**: 정상으로 알려진 구간에서 조용히 벗어나는 동작.
+- **트랜스크립트의 목표 실패**: 기술적으로는 완료됐지만 실제 목적을 달성하지 못한 실행.
+- **도구 오남용**: 잘못된 도구 선택, 잘못된 인자, 또는 API 호출을 낭비하는 루프.
+- **품질 및 비용 트레이드오프**: 더 저렴하게 얻을 수 있는 결과에 과도한 비용을 지불하는 부분.
+- **커버리지 공백**: 어떤 평가(eval)나 알림도 감시하지 않는 동작.
+
+**민감도** 설정 하나(낮음, 보통, 높음)로 검사 강도를 조절할 수 있어, 노이즈가 많은 스테이징 에이전트와 엄격하게 관리되는 프로덕션 에이전트 각각을 원하는 신호에 맞게 튜닝할 수 있습니다.
+
+## 모든 권고사항에는 근거가 따라옵니다
+
+발견된 내용을 그냥 믿을 필요가 없습니다. 각 권고사항은 출처가 된 정확한 세션과 이를 발견한 SQL을 함께 제시하므로, 주장을 역으로 파헤칠 필요 없이 클릭 한 번으로 근거를 확인하고 문제를 검증할 수 있습니다.
+
+발견된 내용이 유출된 자격 증명에 관한 것이라면 한 걸음 더 나아가 일치된 개별 이벤트를 링크로 연결합니다. 하나를 클릭하면 긴 트랜스크립트의 맨 위가 아니라, 이미 선택된 상태로 해당 세션의 정확한 순간으로 이동합니다. 링크는 이벤트 이름을 표시하며, 발견된 내용에 감지된 시크릿을 절대 복사하지 않으므로 권고사항을 읽는 것이 자격 증명이 기록되는 또 다른 장소가 되지 않습니다. 세션이 보존 기간을 지나 이벤트가 더 이상 존재하지 않는 경우, 페이지는 잘못 클릭했는지 의아하게 만들지 않고 명확하게 알려줍니다.
+
+이것이 바로 감사를 정직하게 유지하는 방법이기도 합니다. 서버는 인용된 모든 세션이 실제로 존재하는지 확인하고 **근거가 유효하지 않은 권고사항은 폐기**하므로, 감사는 조사하되 절대 만들어내지 않습니다. 목록에 올라오는 것은 실제로 존재하고, 재현 가능하며, 가장 중요한 것이 맨 위에 오도록 중요도에 따라 순위가 매겨져 있습니다.
+
+## 수정 사항을 가드레일로 전환하기
+
+문제를 수정하는 것은 절반의 성과일 뿐입니다. 나머지 절반은 그것이 조용히 다시 나타나지 않도록 하는 것입니다. 모든 발견 사항에는 **재발 알림을 작성하는 원클릭 단축키**가 포함되어 있으며, 조정 가능한 합리적인 시작 트리거가 미리 채워져 있습니다. 발견 사항을 닫고 알림을 활성화하면, 다음에 그 패턴이 다시 나타날 때 미래의 감사에서 재발견하는 대신 알림을 받게 됩니다.
+
+## 찾는 위치
+
+감사(Audits)는 대시보드의 **`/<org-slug>/audits`** 에 있습니다(사이드바 → *analyze* → *audits*). 실행 결과 및 발견 사항 조회에는 **`audits:read`** 권한이 필요하고, 감사 생성·편집·분류에는 **`audits:write`** 권한이 필요합니다. 감사의 범위와 주기를 설정한 후, 다음 예약 실행을 기다리지 않고 즉시 결과를 원할 때는 **Run now**를 누르세요.
+
+## 관련 항목
+
+- [알림(Alerts)](/ko/agenteye/alerts): 이미 알고 있는 임계값이 초과되는 순간 즉시 알림을 받습니다.
+- [평가(Evaluations)](/ko/agenteye/evaluations): 모든 실행에 점수를 매겨 품질 저하가 자동으로 드러나도록 합니다.
+- [오류 추적(Error tracking)](/ko/agenteye/error-tracking): 에이전트가 발생시키는 오류를 그룹화하고 추적합니다.
+- [인시던트(Incidents)](/ko/agenteye/incidents): 감사에서 발견된 문제를 수정 완료까지 추적합니다.

package/.next/standalone/docs-old/ko/agenteye/cli-and-agents.mdx

@@ -0,0 +1,80 @@
+---
+title: "CLI"
+description: "Failproof AI Observability 배포 전체를 명령어 하나로 관리하세요."
+---
+
+
+Failproof AI Observability 배포 전체를 명령어 하나로 관리하세요. 터미널을 벗어나지 않고 프로덕션을 점검하고, API 키를 발급하고, 인시던트를 확인할 수 있습니다. 이를 CI에 스크립트로 작성하거나, 코딩 에이전트가 일상 언어로 대신 처리하도록 할 수도 있습니다.
+
+```bash
+pipx install agenteye
+agenteye login --email you@example.com      # 6자리 코드가 이메일로 전송됩니다
+agenteye --json sessions --since 24h         # 최근 하루 동안의 모든 에이전트 실행, 최신순 정렬
+```
+
+*`agenteye` CLI는 대시보드와 통신합니다. 이벤트를 서버로 전송하는 콜렉터와는 별개의 도구입니다.*
+
+## 배포 전체를 명령어 하나로
+
+간단한 질문에 답하려고 탭을 여러 개 열어둘 필요가 없습니다. `agenteye` CLI는 단일 바이너리로 데이터를 읽고 조직을 관리합니다. 대시보드를 클릭해야 했던 작업이 이제 한 줄 명령어로 해결됩니다. 다시 실행하거나, 별칭으로 등록하거나, 런북에 붙여 넣을 수 있습니다. 네 가지 기능을 제공합니다:
+
+- **데이터 조회:** `sessions`, `events`, `evals`, `errors`를 시간, 에이전트, 환경별로 필터링합니다.
+- **조직 관리:** `keys`, `users`, `settings`, `alerts`, `incidents`를 관리합니다.
+- **분석 실행:** 저장된 SQL과 이벤트 데이터에 대한 임시 `query` 실행기를 사용합니다.
+- **어시스턴트 질의:** `agent ask`로 대시보드에서 대화하는 것과 동일한 읽기 전용 분석가에게 질문합니다.
+
+`pipx`로 한 번 설치하고, 이메일로 전송된 6자리 코드로 로그인하면 준비 완료입니다. 세션은 약 하루 동안 유지되며, 만료되면 `agenteye login`을 다시 실행하세요. 브라우저를 열지 않고도 프로덕션 점검, 키 발급, 인시던트 트리아지 등을 처리할 수 있습니다:
+
+```bash
+agenteye errors --since 24h --aggregate      # 오류 유형별로 그룹화된 장애 현황
+agenteye incidents list --state firing       # 현재 발생 중인 인시던트
+agenteye keys create ci --add events:add     # 이벤트 푸시만 가능한 키 (비밀값은 한 번만 표시)
+```
+
+한 가지 알아둘 사항: `--json`과 같은 전역 옵션은 명령어 앞에 위치합니다. `agenteye --json sessions`가 올바른 형식이며, `agenteye sessions --json`은 올바르지 않습니다.
+
+## 스크립트 작성 및 CI 연동
+
+모든 명령어에 `--json`을 사용할 수 있으며, 이것이 모든 것을 바꿉니다. 정제된 JSON은 stdout으로 출력되고, 사람을 위한 상태 메시지와 경고는 stderr로 출력됩니다. 따라서 `--json`으로 캡처한 결과를 불필요한 줄 없이 바로 `jq`에 파이프할 수 있습니다. 이 덕분에 CLI는 프롬프트에서 직접 사용하는 경우와 출력을 파싱하는 코딩 에이전트 모두에게 동일하게 유용합니다:
+
+```bash
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+```
+
+무인 실행을 위해 설계되었습니다. 터미널이 연결되어 있지 않으면 확인 프롬프트가 자동으로 건너뛰어져 파이프라인이 중단되지 않습니다. 모든 명령어는 의미 있는 종료 코드를 반환합니다: `0` 성공, `4` 미로그인, `5` 권한 부족 (메시지에 해당 권한 명시, 예: `alerts:write`), `3` 대시보드 연결 불가. 스크립트에서 `4`를 감지하면 재인증을 수행하고, `5`를 감지하면 관리자에게 정확히 어떤 권한이 필요한지 알 수 있어 오류 원인을 모른 채 실패하는 상황을 방지합니다.
+
+## 코딩 에이전트가 일상 언어로 처리하도록
+
+더 나아가, 이 플래그들을 직접 기억할 필요조차 없습니다. **CLI 스킬**은 `agenteye-cli`라는 작은 Agent Skill 폴더로, Claude Code나 Codex 같은 코딩 에이전트가 일상 언어 요청으로 CLI를 사용할 수 있도록 가르쳐 줍니다. "오늘 뭔가 문제가 있나요?"라고 물으면 에이전트가 적절한 명령어를 선택해 실행하고 결과를 설명해 줍니다.
+
+Claude Code의 경우, `agenteye-cli` 폴더를 `~/.claude/skills/`에 넣으면 자동으로 인식됩니다. Failproof AI Observability가 해당 폴더를 제공하며, 이미 설치된 CLI를 활용하는 것이므로 추가 설치가 필요하지 않습니다. 단, 로그인은 직접 먼저 해야 합니다. 스킬은 이메일 코드 로그인을 대신 완료할 수 없습니다.
+
+에이전트는 사용자 권한으로 CLI를 실행하므로, 로그인이 허용하는 모든 작업(읽기와 쓰기 모두)이 가능합니다: 키 생성, 설정 변경, 인시던트 해결. CLI의 "정말 하시겠습니까?" 프롬프트는 에이전트에게는 표시되지 않으므로, 스킬은 변경 작업 전에 정확한 명령어를 명시하고 사용자의 승인을 기다리도록 작성되어 있습니다. 사용자가 직접 확인 단계가 됩니다.
+
+```text
+you    Why did session run-001 fail?
+
+agent  Running: agenteye --json events --session-id run-001 --all
+       The checkout-agent hit a TimeoutError on its third tool call.
+```
+
+읽기 작업은 즉시 실행되고, 쓰기 작업은 매번 사용자 확인을 기다립니다:
+
+```text
+you    Give CI a key that can only push events.
+
+agent  This creates an API key. I'll run:
+         agenteye keys create ci --add events:add
+       OK to proceed?
+
+you    yes
+
+agent  Done. Key "ci" created with events:add only. The secret is shown once, so store it now.
+```
+
+## 관련 문서
+
+- [CLI 레퍼런스](/ko/agenteye/cli): 모든 명령어, 플래그, JSON 구조.
+- [에이전트를 위한 CLI 레시피](/ko/agenteye/cli-recipes): 복사해서 쓸 수 있는 `jq` 패턴과 종료 코드 처리.
+- [CLI 에이전트 스킬](/ko/agenteye/cli-skill): `agenteye-cli` 스킬 설치 및 실행.
+- [AI 어시스턴트](/ko/agenteye/assistant): `agent ask`가 연결되는 대시보드 내 분석가.