ltcai 0.1.9 → 0.1.16

package/docs/CHANGELOG.md

@@ -0,0 +1,307 @@
+# Changelog
+
+## [0.1.16] - 2026-05-22
+
+### First-user admin bootstrap
+
+- 서버를 처음 설치하고 가입하는 첫 번째 사용자가 자동으로 **admin** 권한 획득
+- 이후 가입자는 기존과 동일하게 `user` 역할
+- `/register` 응답에 `role` 필드 추가 — 클라이언트가 첫 가입 여부 확인 가능
+
+### Release
+- 배포 버전을 `0.1.16`으로 상향
+
+## [0.1.15] - 2026-05-22
+
+### Security hardening
+
+- `LTCAI --tunnel` 실행 시 `LATTICEAI_REQUIRE_AUTH=true` 자동 강제 — 터널로 공개된 서버에 로그인 없이 접근 불가
+- `/register` IP당 시간당 5회 rate limit
+- `/login` IP당 5분당 10회 rate limit (brute force 방지)
+- Cloudflare 터널 통과 시 `CF-Connecting-IP` 헤더로 실제 클라이언트 IP 추출
+- `LATTICEAI_OPEN_REGISTRATION=false` 설정 시 회원가입 완전 차단 (관리자 직접 추가만 허용)
+
+### Release
+- 배포 버전을 `0.1.15`로 상향
+
+## [0.1.14] - 2026-05-22
+
+### `--tunnel` flag — 누구나 자기 PC를 서버로
+
+- `LTCAI --tunnel` 한 줄로 Cloudflare 무료 터널 자동 개설
+- cloudflared 바이너리가 없으면 GitHub에서 자동 다운로드 (`~/.latticeai/bin/`)
+- macOS arm64/amd64, Linux arm64/amd64, Windows amd64 지원
+- 터널 URL을 배너에 출력 + `LATTICEAI_TELEGRAM_BOT_TOKEN` / `LATTICEAI_TELEGRAM_CHAT_ID` 설정 시 Telegram 자동 알림
+- `--tunnel` 지정 시 host 자동으로 `0.0.0.0`, CORS 네트워크 허용으로 전환
+
+### Release
+- 배포 버전을 `0.1.14`로 상향
+- 대상 채널: `npm`, `PyPI`, `VS Code Marketplace`, `Open VSX`
+
+## [0.1.13] - 2026-05-22
+
+### Code quality & efficiency
+
+- `HF_MODELS_ROOT` / `hf_model_dir` 중복 정의 제거 — `llm_router.py` 단일 소스로 통합, `server.py`에서 import
+- `_looks_like_hf_model_dir` 가중치 파일 체크를 `.safetensors` / `.bin`으로 일치 — `.gguf`를 MLX 경로에서 잘못 허용하던 버그 수정
+- `vllm_executable()` `shutil.which` 이중 호출 → 변수 캐시
+- `ensure_lmstudio_model()` `_find_lmstudio_model_key` 이중 호출 → `found_key` 변수로 캐시
+- `engine_support_status` 3단계 중첩 조건 → `is_apple_silicon` 플래그로 평탄화
+- `ensure_llamacpp_server` 동일 프로세스 이중 `terminate()` 블록 → 단일 블록 (vllm 패턴과 통일)
+- `ensure_vllm_server` 37줄 중첩 삼항 커맨드 빌더 → `if/elif/else` + `_host_args` 공통화
+- `except: pass` → `except Exception: pass` (KeyboardInterrupt 노출)
+- `knowledge_graph.py` 엣지 순회 루프 두 번 (`degree_map` + `topic_metrics`) → 단일 루프로 병합
+
+### Performance & correctness
+
+- `get_lmstudio_models()` TTL 캐시(10초) 추가 — `/health`, `/engines`, `/models` 매 요청마다 LM Studio HTTP 프로브하던 문제 해결, 서버 미응답 시 마지막 캐시 반환
+- `/health`, `/engines`, `/models` 엔드포인트에서 `engine_status()` 호출을 `asyncio.to_thread()`로 오프로드 — LM Studio 최대 45초, ollama subprocess 블로킹이 이벤트 루프를 점유하던 문제 해결
+- 앱 종료 시 `LOCAL_SERVER_PROCESSES` (vLLM, llama.cpp) 자식 프로세스 정리 — GPU 메모리 고아 프로세스 누수 수정
+
+### Release
+- 배포 버전을 `0.1.13`으로 상향
+- 대상 채널: `npm`, `PyPI`, `VS Code Marketplace`, `Open VSX`
+
+## [0.1.12] - 2026-05-22
+
+### Local engine install / load flow
+- `vLLM` 설치 경로를 macOS용 `Python 3.12 + vllm-metal` 흐름으로 교체
+- `LM Studio` 번들 `lms` CLI와 native API를 사용해 서버 시작, 모델 다운로드, 모델 로드를 자동화
+- `llama.cpp`는 선택한 GGUF를 alias와 함께 OpenAI 호환 서버로 직접 로드하도록 정리
+- 모델 패널의 `설치` / `다운로드 후 자동 로드` 흐름이 실제 `prepare_and_load_model()` 경로로 수렴되도록 정리
+
+### Verified
+- 최소 테스트 모델 기준 실사용 검증 완료
+- `vLLM`: `Qwen/Qwen2.5-0.5B-Instruct-AWQ`
+- `LM Studio`: `https://huggingface.co/lmstudio-community/Qwen2.5-0.5B-Instruct-GGUF`
+- `llama.cpp`: `lmstudio-community/Qwen2.5-0.5B-Instruct-GGUF`
+
+### Release
+- 배포 버전을 `0.1.12`로 상향
+- 대상 채널: `npm`, `PyPI`, `VS Code Marketplace`, `Open VSX`
+
+## [0.1.11] - 2026-05-21
+
+### Agent state machine (renamed + cleaned up)
+- 8개의 명시적 상태: `IDLE → PLANNING → WAITING_APPROVAL → EXECUTING → VERIFYING → (DONE | ROLLBACK → FAILED)`
+- `RETRY` 상태 제거 — 재시도 카운터는 `AgentRunContext.retry_count`에 보관, `VERIFYING`이 `EXECUTING`으로 직접 전환
+- 종료 상태를 `DONE` / `FAILED`로 분리 — 응답에 `final_state` 필드 추가, `status`는 `"ok"` 또는 `"failed"`
+
+### Tool Permission Layer
+- `ToolPermission` 추가 — `{ tool, risk, requires_approval, network }` 4-필드 컴팩트 뷰
+- 기존 7-차원 `TOOL_GOVERNANCE`에서 자동 파생 (단일 진실 공급원)
+- `GET /tools/permissions` 엔드포인트 추가
+- `/mcp/tools` 응답의 각 툴에 `permission` 필드 노출
+
+### Cleanup
+- 중국어 응답 지원 제거 — `detect_language`는 이제 `ko` 또는 `en`만 반환
+- `_LANG_HINT`에서 `"zh"` 키 삭제, EXECUTOR_PROMPT의 "Chinese" 언급 제거
+
+### Repo
+- `CHANGELOG.md` → `docs/CHANGELOG.md` 이동 (루트 가독성 개선)
+- 자동 릴리스 워크플로(`release.yml`) 제거 — 수동 배포 유지
+
+---
+
+## [0.1.10] - 2026-05-21
+
+### Agent intelligence (pro-developer workflow)
+- **`AGENT_SYSTEM_PROMPT` 완전 재작성** — Claude Code 스타일 시니어 개발자 워크플로
+  - Discover → Plan → Implement → Verify 4단계 강제
+  - JSON 응답에 `thoughts` 필드 추가, transcript에 함께 기록되어 다음 스텝의 컨텍스트로 전달
+  - 코드 읽기 전 수정 금지, 검증 없이 "완료" 주장 금지, 작은 diff 원칙
+  - 새 도구 카탈로그 + 안티패턴(반복 액션·환각 import·placeholder URL) 명시
+- **`max_steps` 상향** — 기본값 6 → 25, 캡 10 → 50 (`AgentRequest.max_steps`)
+
+### New tools
+- **`edit_file`** — 정밀 diff 편집. `old_string`이 파일에 유일하게 존재해야만 성공(또는 `replace_all=true`). 환각 import / 잘못된 위치 수정 방지. 결과에 `first_edit_line` 포함
+- **`grep`** — 정규식 검색, 전체 텍스트 파일 대상, `glob` 필터, `context_lines`, binary dir(`node_modules`, `.git`, `venv`, `dist` 등) 자동 제외. 기존 `search_files`는 호환 유지
+- **`todo_write` / `todo_read`** — 워크스페이스별 영구 TODO 리스트(`agent_workspace/.lattice/todos.json`). 멀티스텝 작업의 상태 유지. status ∈ `pending | in_progress | completed`. 다중 in_progress 경고
+- **`read_file` 업그레이드** — `numbered`(라인 번호 뷰), `total_lines`, `start_line`/`end_line`, optional `offset`/`limit` 추가. 기존 `content` 반환 호환 유지
+- 위 모든 도구에 `/tools/*` REST 엔드포인트 추가, `_TOOL_RISK` 등록, `/mcp/tools` 카탈로그 노출
+
+### Loop safety
+- `_FILE_CREATE_ACTIONS`에 `edit_file` 포함 — 같은 args로 연속 호출 시 자동 중단
+- 반복 중단 메시지를 "다음 단계로 진행하세요"로 명확화
+
+### Tests
+- `tests/unit/test_tools.py`에 23개 신규 테스트 — edit_file (유일/모호/`replace_all`/identical), grep (regex·glob·case·context·binary dir), todo round-trip + 검증, read_file numbered/offset/limit, 샌드박스 이탈 차단 (`52 passed`)
+
+### Security (보안 기본값 통일)
+- **기본 바인딩 `0.0.0.0` → `127.0.0.1` 롤백** — v0.1.8에서 PWA 편의를 위해 0.0.0.0으로 변경했으나 개인 AI 서버의 기본값은 로컬 전용이어야 안전함. 네트워크 노출이 필요한 경우 `LATTICEAI_HOST=0.0.0.0` 명시적 설정.
+- SECURITY.md, CONTRIBUTING.md, GitHub Actions CI/Release 워크플로 추가
+- docs/ 문서 추가: architecture, security-model, public-deploy, mcp-tools, privacy
+
+---
+
+## [0.1.9] - 2026-05-21
+
+### Security
+- **세션 TTL 7일 → 24시간 + sliding refresh** — 활동 시 만료시간 자동 연장, 15분 단위 디스크 쓰기 throttle
+- **평문 비밀번호 마이그레이션 audit 로깅** — `password_migrated_from_plaintext` 이벤트로 남은 평문 사용자 추적
+- **파일 업로드 magic-number 검증** — `_bytes_match_extension()`: PDF/DOCX/XLSX/PPTX/PNG/JPEG/ZIP 시그니처 확인, 확장자 위조 방지
+- **Rate limiting** — `/chat` 30 burst/분당 30, `/agent` 10 burst/분당 6, `/upload` 20 burst/분당 12. 토큰 버킷 per-user. `LATTICEAI_RATE_LIMIT=0`으로 비활성화 가능
+
+### Reliability
+- **PyMuPDF 파일 핸들 누수 수정** — `/tools/pdf_pages` try/finally로 doc.close() 보장, `len(doc)` 호출 위치 버그 수정
+- **ollama serve 좀비 방지** — 실행 전 already_up 체크, `start_new_session=True`로 detach
+- **knowledge_graph.py 손상된 metadata_json 안전 처리** — `_safe_loads()` 헬퍼로 corrupt row 통과 (5곳 적용)
+- **백그라운드 asyncio 태스크 예외 로깅** — `_spawn()` 헬퍼 (`add_done_callback`) — startup 태스크 silent fail 방지
+- **silent except → logging.warning** — `_load_sessions`, `_persist_sessions`, `load_vpc_config`, `load_mcp_installs`
+
+### Tests
+- **`tests/unit/test_security.py`** — 16개 신규 테스트: bcrypt 해시 라운드트립/유니크, MIME 검증, rate limit (29 → 31개 전체 통과)
+
+---
+
+## [0.1.8] - 2026-05-21
+
+### Added
+- **PWA (Progressive Web App)** — iPad / Android / Galaxy Tab 홈화면 설치 지원
+  - `manifest.json`: 앱 이름, 아이콘, 배경색, 테마색, 단축키 정의
+  - `sw.js` Service Worker: 정적 파일 캐시-퍼스트, API 네트워크-퍼스트, 오프라인 대응
+  - 192×192, 512×512, apple-touch-icon 180×180, favicon 32×32 PNG 아이콘 생성
+  - 모든 HTML에 `<link rel="manifest">`, `apple-mobile-web-app-*`, `theme-color` 메타태그 추가
+  - `viewport-fit=cover` — iPhone Dynamic Island / 노치 안전영역 확장
+- **서버 네트워크 공개 바인딩** — 기본 host `127.0.0.1` → `0.0.0.0`으로 변경
+  - 같은 Wi-Fi 내 iPad / Android / Galaxy Tab 에서 `http://<Mac IP>:4825` 로 바로 접근 가능
+  - 시작 배너에 로컬 / 네트워크 URL 및 "Add to Home Screen" 안내 출력
+- **Windows 서버 호환성**
+  - `computer_screenshot`: macOS `screencapture` 외 Windows/Linux에서 pyautogui fallback
+  - `computer_open_app` / `computer_open_url`: `open -a` (macOS) / `cmd /c start` (Windows) / `xdg-open` (Linux) 자동 분기
+  - `_PLATFORM` 상수 도입으로 향후 플랫폼 분기 일관성 확보
+- **배포 파일 포함**: `manifest.json`, `sw.js`, `icons/` 폴더를 npm · PyPI 패키지에 포함
+
+### Deployed
+- npm ✅
+- PyPI ✅
+- VS Code Marketplace ✅
+- Open VSX ✅
+
+---
+
+## [0.1.7] - 2026-05-21
+
+### Added
+- **모바일 반응형 UI** — 폰/태블릿 화면 크기에 자동 대응
+  - 768px 이하: 사이드바가 좌측 슬라이드 드로어로 전환, 헤더 햄버거(☰) 버튼으로 열기
+  - 오버레이 탭하면 사이드바 닫힘, 대화 선택 시 자동 닫힘
+  - ops-strip 카드 3개 → 가로 스크롤 한 줄 압축 (모바일)
+  - `100dvh` 적용 — iOS 소프트 키보드 올라와도 레이아웃 유지
+  - `env(safe-area-inset-bottom)` — iPhone 노치/홈바 안전영역 자동 여백
+  - textarea `font-size: 16px` (480px 이하) — iOS 자동 줌 방지
+- 브레이크포인트 3단계: 900px(태블릿) / 768px(모바일 드로어) / 480px(폰)
+
+---
+
+## [0.1.6] - 2026-05-21
+
+### Added
+- **LATTICEAI_ENABLE_GRAPH** 환경변수 — Data Graph 기능을 퍼블릭 서버에서 완전히 숨길 수 있는 토글 (기본값 `true`)
+  - `false`로 설정 시 모든 그래프 API 엔드포인트 404 반환, 인제스트 건너뜀, 사이드바 버튼 자동 숨김
+- `.env.example`에 `LATTICEAI_ENABLE_GRAPH` 항목 추가 (로컬/퍼블릭 모드 각각)
+
+---
+
+## [0.1.5] - 2026-05-21
+
+### Added
+- **Data Graph** — 채팅·AI 답변·업로드 문서를 SQLite 지식 그래프로 자동 구조화, `/graph`에서 Canvas 기반 Force-directed 시각화
+- **Graph RAG** — 그래프 검색 결과를 채팅 컨텍스트에 자동 주입하여 이전 대화·문서 참조 능력 강화
+- **Telegram 원격 제어** — 인라인 키보드 메뉴로 상태 조회, 모델 관리, 스크린샷, 그래프 통계, 문서 업로드 등 원격 제어
+- `knowledge_graph.py` — KnowledgeGraphStore (node/edge/chunk/event), `ingest_message()`, `ingest_document()`, `context_for_query()`, `search()`, `neighbors()`
+- `static/graph.html` — 타입별 색상, 줌/패닝, 핀치 줌, 이웃 하이라이트, 노드 상세 정보, 채팅 연결 링크
+
+### Security
+- 어드민 세션 핸드오프를 URL 파라미터 → `sessionStorage` 1회 읽기 방식으로 교체 (히스토리 노출 방지)
+- `X-Admin-Email` 헤더 폴백 제거 — Bearer 토큰 인증만 허용
+
+---
+
+## [0.1.4] - 2026-05-18
+
+### Added
+- **세션 영속성** — 서버 재시작 후에도 로그인 유지 (sessions.json 파일 기반)
+- **SSO 로그인** — Entra ID / Okta OIDC 지원 (`OIDC_DISCOVERY_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` 환경변수)
+- **채팅 히스토리 검색** — 사이드바 검색창으로 대화 내용 키워드 검색 (`GET /history/search`)
+- **대화 삭제** — 사이드바 각 대화에 삭제 버튼 추가
+- **MCP 서버 관리 UI** — 사이드바 "MCP 관리" 버튼으로 설치/목록 확인 모달
+- **인라인 Diff 뷰** — Edit Selection 결과를 diff로 보여주고 Apply/Discard 선택
+- **현재 파일 첨부** — `Lattice AI: Attach Current File to Chat` 명령 추가 (VS Code)
+- `authlib` 의존성 추가 (SSO OIDC 지원)
+
+### Deployed
+- PyPI ✅
+- npm ✅
+- VS Code Marketplace ✅
+- Open VSX ✅
+
+---
+
+## [0.1.3] - 2026-05-18
+
+### Added
+- 프로필 수정 API (`PATCH /account/profile`) 및 UI — 이름·닉네임 변경
+- 회원가입 폼 개선 — 비밀번호 확인 필드, 인라인 에러 메시지
+- 어드민 패널 초대 링크 섹션 — 원클릭 복사
+- 어드민 대시보드 메시지 활동 차트 (Chart.js, 최근 14일)
+- 웹 UI 한국어 / 영어 전환 (`🌐 Languages` 버튼, localStorage 저장)
+
+### Fixed
+- 로그아웃 시 `/logout` API 호출하여 서버 세션 쿠키 정상 만료
+- 인증(`account.html`)과 채팅(`chat.html`) UI 분리 — 레거시 `index.html` 제거
+- `chat.html` 내 죽은 인증 코드 제거
+- 채팅 헤더에서 언어 선택 드롭다운이 ops-strip을 가리는 문제 수정
+
+### Deployed
+- PyPI ✅
+- npm ✅
+- VS Code Marketplace ✅
+- Open VSX ✅
+
+---
+
+## [0.1.1] - 2026-05-18
+
+### Added
+- 비밀번호 변경 API (`POST /account/change-password`)
+- 웹 UI 비밀번호 변경 모달 (헤더 계정 아이콘)
+
+### Docs
+- 어드민 패널: 첫 가입자 자동 admin 안내 추가
+- 플랫폼 지원 범위 (Windows/Linux) 안내 추가
+- 언어 지원 (KO/EN) 안내 추가
+
+### Deployed
+- PyPI ✅
+- npm ✅
+- VS Code Marketplace ✅
+- Open VSX ✅
+
+---
+
+## [0.1.0] - 2026-05-17
+
+### Added
+- FastAPI 브릿지 서버 (port 4825)
+- Apple Silicon MLX 로컬 모델 지원 (Gemma 4, Qwen 2.5 등)
+- 클라우드 모델 지원 (OpenAI, Groq, Together, OpenRouter 등)
+- VS Code / Cursor / Antigravity 확장
+- Telegram 봇 (로컬 AI 미러 + Codex 클라우드 봇)
+- 어드민 패널 (`/admin`)
+- P-Reinforce 지식 정원 엔진
+- MCP 서버 연동
+- Ollama / vLLM / LM Studio / llama.cpp 연동
+
+### Security
+- 모든 민감 엔드포인트 인증 적용
+- SameSite=Lax 쿠키 (CSRF 방어)
+- scrypt 비밀번호 해싱
+- tempfile 레이스 컨디션 수정
+- `run_command()` 위험 플래그 차단
+
+### Deployed
+- PyPI ✅
+- npm ✅
+- VS Code Marketplace ✅
+- Open VSX ✅

package/docs/architecture.md

@@ -0,0 +1,121 @@
+# Lattice AI — 아키텍처
+
+## 전체 구조
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    클라이언트 레이어                      │
+│  웹 UI (chat.html)  │  VS Code 확장  │  Telegram 봇     │
+└──────────────────────────┬──────────────────────────────┘
+                           │ HTTP / SSE
+┌──────────────────────────▼──────────────────────────────┐
+│               server.py — FastAPI (port 4825)            │
+│                                                          │
+│  /chat  /agent  /models  /tools/*  /mcp/*  /garden      │
+│  /account  /admin  /auth/sso  /knowledge-graph  /graph   │
+└────┬──────────┬──────────┬──────────┬───────────────────┘
+     │          │          │          │
+     ▼          ▼          ▼          ▼
+llm_router  tools.py  knowledge_  p_reinforce
+  .py               graph.py      .py
+     │
+     ├── MLX (mlx_lm / mlx_vlm)   ← Apple Silicon 로컬
+     ├── OpenAI SDK                ← openai / groq / together / openrouter
+     └── Ollama / vLLM REST        ← 로컬 서버 연동
+```
+
+## 파일별 역할
+
+| 파일 | 역할 |
+|------|------|
+| `server.py` | FastAPI 앱, 모든 HTTP 엔드포인트, 인증/세션/CORS/rate limit |
+| `ltcai_cli.py` | CLI 엔트리포인트 (`LTCAI` 명령), `doctor` 서브커맨드, uvicorn 실행 |
+| `llm_router.py` | 로컬(MLX/Ollama) ↔ 클라우드(OpenAI/Groq/…) 라우팅, 스트리밍 SSE |
+| `tools.py` | 에이전트 도구 구현: read_file, edit_file, grep, run_command, todo_write/read, 스크린샷 등 |
+| `knowledge_graph.py` | SQLite 지식 그래프 (노드/엣지/청크), Graph RAG 컨텍스트 주입 |
+| `p_reinforce.py` | P-Reinforce 지식 정원 엔진, `~/.ltcai-brain/` 분류 저장 |
+| `telegram_bot.py` | 로컬 AI Telegram 미러 봇 |
+| `codex_telegram_bot.py` | 클라우드 Codex Telegram 봇 (GPT + GitHub 이슈) |
+| `vscode-extension/` | TypeScript VS Code 확장 |
+| `static/` | 웹 UI HTML (chat, account, admin, graph), PWA manifest/SW |
+| `bin/ltcai.js` | npm CLI 엔트리포인트 (Python 환경 자동 부트스트랩) |
+
+## 데이터 흐름
+
+### 채팅 요청
+
+```
+브라우저 → POST /chat
+  → server.py: 인증 확인, rate limit
+  → llm_router.py: 모델 선택 (로컬/클라우드)
+  → knowledge_graph.py: Graph RAG 컨텍스트 조회 + 주입
+  → LLM 스트리밍 응답 (SSE)
+  → knowledge_graph.py: 메시지/응답 인제스트
+```
+
+### 에이전트 요청
+
+```
+브라우저/VS Code → POST /agent
+  → server.py: 인증 확인, rate limit (6/분)
+  → llm_router.py: Discover→Plan→Implement→Verify 루프 (max 25스텝)
+  → tools.py: read_file / edit_file / grep / run_command / todo_*
+  → 각 스텝 결과 스트리밍
+```
+
+### 문서 업로드
+
+```
+브라우저 → POST /upload
+  → server.py: magic-number 검증, rate limit (12/분)
+  → tools.py: PDF/DOCX/XLSX/PPTX 파싱
+  → knowledge_graph.py: Chunk/Page/Sheet/Slide 노드 인제스트
+  → blob 저장: ~/.ltcai/knowledge_graph_blobs/
+```
+
+## 데이터 저장소
+
+```
+~/.ltcai/
+├── users.json                   # 사용자 계정 (scrypt 해시)
+├── sessions.json                # 세션 토큰 (24h TTL)
+├── chat_history.json            # 채팅 히스토리
+├── knowledge_graph.sqlite       # Graph RAG SQLite DB
+├── knowledge_graph_blobs/       # 원본 업로드 파일
+├── mcp_installs.json            # MCP 서버 설치 목록
+└── todos.json                   # 에이전트 TODO 리스트
+
+~/.ltcai-brain/
+├── INDEX.md
+├── 00_Raw/
+├── 10_Wiki/
+├── 20_Skills/
+├── 30_Projects/
+└── 40_Log/
+```
+
+## 인증 흐름
+
+```
+POST /login (username + password)
+  → scrypt 검증
+  → 세션 토큰 생성 (UUID, 24h TTL)
+  → Set-Cookie: session=<token>; HttpOnly; SameSite=Lax
+
+모든 민감 엔드포인트:
+  → _require_auth(): 쿠키 검증 → User 반환 또는 401
+```
+
+SSO (OIDC):
+
+```
+GET /auth/sso/login → 리디렉션 (Entra ID / Okta)
+GET /auth/sso/callback?code=... → 토큰 교환 → 세션 생성
+```
+
+## MCP 연동
+
+`/mcp/tools` — 에이전트 도구 카탈로그를 MCP 형식으로 노출  
+Claude Desktop / Cursor의 MCP 설정에 `http://localhost:4825/mcp` 추가 시 직접 도구 사용 가능.
+
+자세한 내용: [mcp-tools.md](mcp-tools.md)

package/docs/mcp-tools.md

@@ -0,0 +1,116 @@
+# MCP 도구 카탈로그
+
+Lattice AI는 MCP(Model Context Protocol) 서버로 동작하여 Claude Desktop, Cursor 등에서 직접 도구를 사용할 수 있습니다.
+
+## 연결 설정
+
+`claude_desktop_config.json` 또는 Cursor MCP 설정:
+
+```json
+{
+  "mcpServers": {
+    "lattice-ai": {
+      "url": "http://localhost:4825/mcp"
+    }
+  }
+}
+```
+
+## 도구 목록
+
+### 파일 시스템
+
+| 도구 | 설명 | 위험도 |
+|------|------|--------|
+| `read_file` | 파일 읽기 (라인 번호, offset/limit 지원) | 낮음 |
+| `edit_file` | 정밀 diff 편집 (`old_string` 유일성 검증) | 중간 |
+| `list_dir` | 디렉토리 목록 | 낮음 |
+| `grep` | 정규식 검색, glob 필터, context_lines | 낮음 |
+
+### 실행
+
+| 도구 | 설명 | 위험도 |
+|------|------|--------|
+| `run_command` | 셸 명령 실행 (위험 패턴 차단) | 높음 |
+| `run_terminal_command` | 터미널 명령 (별칭) | 높음 |
+
+### 작업 관리
+
+| 도구 | 설명 | 위험도 |
+|------|------|--------|
+| `todo_write` | TODO 항목 생성/업데이트 | 낮음 |
+| `todo_read` | TODO 목록 조회 | 낮음 |
+
+### 시스템
+
+| 도구 | 설명 | 위험도 |
+|------|------|--------|
+| `computer_screenshot` | 화면 캡처 | 낮음 |
+| `computer_open_app` | 앱 실행 | 중간 |
+| `computer_open_url` | URL 열기 | 낮음 |
+| `network_status` | IP, Wi-Fi 정보 | 낮음 |
+
+### 문서
+
+| 도구 | 설명 | 위험도 |
+|------|------|--------|
+| `pdf_to_text` | PDF → 텍스트 변환 | 낮음 |
+| `pdf_pages` | PDF 페이지 수 조회 | 낮음 |
+| `read_docx` | Word 문서 읽기 | 낮음 |
+| `read_xlsx` | Excel 파일 읽기 | 낮음 |
+| `read_pptx` | PowerPoint 읽기 | 낮음 |
+
+### 지식 정원 (P-Reinforce)
+
+| 도구 | 설명 | 위험도 |
+|------|------|--------|
+| `garden_save` | 지식 정원에 저장 | 낮음 |
+| `garden_tree` | 지식 트리 조회 | 낮음 |
+| `garden_read` | 정원 파일 읽기 | 낮음 |
+
+## REST API 직접 호출
+
+MCP 대신 REST API로도 동일한 도구를 호출할 수 있습니다:
+
+```bash
+# read_file
+curl -b "session=<token>" \
+  "http://localhost:4825/tools/read_file?path=server.py"
+
+# edit_file
+curl -b "session=<token>" -X POST \
+  http://localhost:4825/tools/edit_file \
+  -H "Content-Type: application/json" \
+  -d '{"path": "server.py", "old_string": "old code", "new_string": "new code"}'
+
+# grep
+curl -b "session=<token>" \
+  "http://localhost:4825/tools/grep?pattern=def%20main&glob=*.py"
+
+# run_command
+curl -b "session=<token>" -X POST \
+  http://localhost:4825/tools/run_command \
+  -H "Content-Type: application/json" \
+  -d '{"command": "python -m pytest tests/ -v"}'
+```
+
+## 도구 카탈로그 조회
+
+```bash
+curl http://localhost:4825/mcp/tools
+```
+
+응답:
+```json
+{
+  "tools": [
+    {
+      "name": "edit_file",
+      "description": "정밀 diff 편집. old_string이 파일에 유일해야만 성공.",
+      "risk": "medium",
+      "parameters": { ... }
+    },
+    ...
+  ]
+}
+```

package/docs/privacy.md

@@ -0,0 +1,74 @@
+# 개인정보 및 데이터 정책
+
+## 요약
+
+**Lattice AI는 데이터를 수집하거나 외부 서버로 전송하지 않습니다.**
+
+모든 데이터는 사용자의 로컬 머신에만 저장됩니다.
+
+## 저장되는 데이터
+
+| 데이터 | 저장 위치 | 설명 |
+|--------|-----------|------|
+| 사용자 계정 | `~/.ltcai/users.json` | 이름, scrypt 해시 비밀번호, 역할 |
+| 세션 토큰 | `~/.ltcai/sessions.json` | UUID 토큰, 만료시간 |
+| 채팅 히스토리 | `~/.ltcai/chat_history.json` | 사용자-AI 대화 내용 |
+| 지식 그래프 | `~/.ltcai/knowledge_graph.sqlite` | 채팅/문서 노드/엣지 |
+| 업로드 파일 | `~/.ltcai/knowledge_graph_blobs/` | 원본 PDF/DOCX 등 |
+| 지식 정원 | `~/.ltcai-brain/` | P-Reinforce 분류 저장 |
+| 설정 | `~/.ltcai/config.json` | 모델 설정, API 키 (keyring) |
+
+## 수집하지 않는 데이터
+
+- 사용 통계, 세션 길이, 클릭 이벤트
+- 오류 리포트 (로컬 `server.log`에만 기록)
+- 기기 정보, IP 주소
+- 프롬프트/응답 내용
+
+## 클라우드 모델 사용 시
+
+사용자가 직접 OpenAI, Groq, Together, OpenRouter 등의 API 키를 설정하고 클라우드 모델을 선택한 경우, 해당 프롬프트와 응답은 각 클라우드 제공업체의 서버를 경유합니다. 이는 각 제공업체의 개인정보처리방침을 따릅니다.
+
+- OpenAI: https://openai.com/privacy
+- Groq: https://groq.com/privacy-policy
+- Together AI: https://www.together.ai/privacy
+- OpenRouter: https://openrouter.ai/privacy
+
+Apple Silicon MLX 로컬 모델 사용 시에는 프롬프트가 외부로 전송되지 않습니다.
+
+## API 키 보안
+
+- API 키는 OS keyring(macOS Keychain, Windows Credential Manager, Linux Secret Service)에 저장됩니다
+- `LATTICEAI_ALLOW_PLAINTEXT_API_KEYS=true` 설정 없이는 디스크에 평문 저장되지 않습니다
+- 채팅 히스토리 저장 전 API key/token/password 패턴 자동 마스킹
+
+## 데이터 삭제
+
+```bash
+# 채팅 히스토리만 삭제
+rm ~/.ltcai/chat_history.json
+
+# 지식 그래프 삭제
+rm ~/.ltcai/knowledge_graph.sqlite
+rm -rf ~/.ltcai/knowledge_graph_blobs/
+
+# 전체 데이터 삭제
+rm -rf ~/.ltcai/
+rm -rf ~/.ltcai-brain/
+```
+
+웹 UI에서: `/clear` 명령 (현재 대화 삭제), 어드민 패널에서 사용자별 데이터 관리
+
+## 퍼블릭 배포 시
+
+외부 사용자가 접근할 수 있는 환경에 배포하는 경우, 사용자에게 다음을 고지하세요:
+
+1. 어떤 데이터가 서버에 저장되는지
+2. 사용하는 클라우드 AI 제공업체
+3. 채팅 내용의 보존 기간 및 삭제 방법
+
+Lattice AI 자체는 퍼블릭 배포 운영자의 데이터 처리 방식에 대해 책임지지 않습니다.
+
+## 문의
+
+개인정보 관련 문의: rnlgnquvk@gmail.com