Initial Global Release v1.0 (Localization & Security Hardening)

docs/README.md

@@ -0,0 +1,30 @@
+# 🧠 뇌사료 (Brain Dogfood) 프로젝트 문서화 (v5.0+)
+
+> **"지식은 기록될 때 힘을 얻고, 연결될 때 생명을 얻는다."**
+
+본 프로젝트는 개인용 지식창고 및 메모 서버로, **보안**, **지능형 연결(Nebula)**, 그리고 **기록의 습관(Heatmap)**을 핵심 가치로 삼습니다.
+
+## 🚀 프로젝트 개요
+- **이름**: 뇌사료 (Brain Dogfood)
+- **핵심 가치**: 
+    - **지식 네뷸라 (Knowledge Nebula)**: D3.js 기반의 유기적인 지식 그래프 시각화.
+    - **지식 성장 히트맵 (Growth Heatmap)**: 꾸준한 기록을 시각화하는 활동 대시보드.
+    - **이중 보안**: 메모별 개별 암호화 및 미디어 보안 실드.
+    - **AI 구조화**: Gemini 2.0 Flash 기반 자동 요약 및 지능형 태깅.
+
+## ✨ What's New in v5.0
+- **Heatmap**: 최근 1년/6개월/3개월/1개월 활동량 지표 추가.
+- **Performance**: 대량 데이터 로딩 최적화(Bulk Fetch) 및 무한 스크롤 도입.
+- **Editor**: 중요 지식 강조를 위한 글자 색상(Color Syntax) 기능 통합.
+
+## 📂 문서 인덱스
+1. [**사용자 매뉴얼 (User Manual)**](user_manual.md): **[최초 사용자 필독]** 사용법 및 연결 문법
+2. [**시스템 아키텍처 (Architecture)**](architecture.md): 폴더 구조 및 모듈형 설계
+3. [**데이터베이스 및 API 명세 (API Reference)**](api_reference.md): DB 스키마 및 확장된 API 명세
+4. [**핵심 기능 가이드 (Features)**](features.md): 히트맵 알고리즘 및 AI 인사이트 메커니즘
+5. [**로직 흐름도 (Logic Flow)**](logic_flow.md): 앱 라이프사이클 및 보안 상태 전이 규칙
+6. [**소스 매핑 가이드 (Source Mapping)**](source_mapping.md): 호출 관계 및 Ops 도구 매핑
+7. [**단축키 가이드 (Shortcuts Guide)**](shortcuts.md): **[업무 효율 극대화]** 탐색 및 편집 단축키 총정리
+
+---
+*Last Updated: 2026-04-15*

docs/api_reference.md

@@ -0,0 +1,44 @@
+# 📡 데이터베이스 및 API 명세서 (v13.5)
+
+본 문서는 `뇌사료` 프로젝트의 데이터 저장 구조(Schema)와 모든 외부 통신 인터페이스(API)를 상세히 기술합니다.
+
+## 🗄️ 1. 데이터베이스 스키마 (DB Schema)
+
+### 1.1 `memos` 테이블
+메모의 핵심 데이터를 저장합니다.
+| 컬럼명 | 타입 | 기본값 | 설명 |
+| :--- | :--- | :--- | :--- |
+| `id` | INTEGER | PRIMARY KEY | 자동 증가 고유 아이디 |
+| `title` | TEXT | - | 메모 제목 |
+| `content` | TEXT | - | 메모 본문 (암호화 시 바이너리 텍스트) |
+| `is_encrypted` | BOOLEAN | 0 | 암호화 여부 |
+
+### 1.2 `memo_links` 테이블 (v7.0 추가)
+메모 간의 `[[#ID]]` 링크 및 시각화 인력을 관리합니다.
+| 컬럼명 | 타입 | 설명 |
+| :--- | :--- | :--- |
+| `source_id` | INTEGER | 링크를 건 메모 ID |
+| `target_id` | INTEGER | 링크 대상 메모 ID |
+
+---
+
+## 🌐 2. API 엔드포인트 전수 명세
+
+### 2.1 Memos & Analysis
+| Method | URL | Description |
+| :--- | :--- | :--- |
+| `GET` | `/api/memos` | 전체 메모 목록, 태그, 첨부파일, **백링크** 정보 통합 조회 |
+| `POST` | `/api/memos/<id>/decrypt` | 비밀번호 검증 및 본문 일시 복호화 |
+| `GET` | `/api/stats/heatmap` | 최근 N일간의 일자별 메모 작성 수(통계) 조회 (`days` 파라미터 지원) |
+
+### 2.2 Assets (제한적 접근)
+| Method | URL | Security Policy | Description |
+| :--- | :--- | :--- | :--- |
+| `GET` | `/api/download/<filename>` | **세션 필수(로그인 상호작용)** | 이미지/파일 다운로드. 이미지인 경우 `inline` 처리 및 암호화 메모 관련 파일은 로그인 미달 시 403 차단. |
+| `POST` | `/api/upload` | `login_required` | 파일 업로드 및 서버 측 마스터 키 암호화 저장. |
+
+### 2.3 Settings & Ops (v11.0 추가)
+| Method | URL | Description |
+| :--- | :--- | :--- |
+| `GET` | `/api/settings` | 서버 사이드 테마 및 전역 설정 조회 |
+| `POST` | `/api/settings` | UI 테마 설정을 서버에 영구 기록 |

docs/architecture.md

@@ -0,0 +1,38 @@
+# 🏢 시스템 아키텍처 및 폴더 구조 (v5.0+)
+
+본 문서는 `뇌사료` 프로젝트의 물리적 파일 구조와 논리적 설계 아키텍처를 상세히 기술합니다.
+
+## 📁 1. 폴더 구조 (Folder Structure)
+
+| 경로 | 역할 | 상세 설명 |
+| :--- | :--- | :--- |
+| `/app` | **Backend Core** | Flask 애플리케이션의 핵심 로직 및 라우트 |
+| `/app/routes` | **Modular Routes** | 기능별로 분리된 API 엔드포인트 패키지 |
+| `/data` | **Database Box** | SQLite3 DB 파일 (`memos.db`) 저장 위치 |
+| `/docs` | **Documentation** | 시스템 기술 문서 및 가이드 |
+| `/logs` | **Log Box** | 시스템 작동 및 접근 로그 (`app.log`) |
+| `/static` | **Static Assets** | CSS, 이미지, 파비코 및 프론트엔드 JS |
+| `/static/js/components` | **UI Components** | D3.js 시각화 모듈 및 UI 핵심 로직 |
+| `/templates` | **HTML Templates** | Jinja2 기반 레이아웃 및 페이지 |
+| `deploy.py` | **Ops Tool** | 수술적 정밀 배포 도구 (Surgical Deployment) |
+| `backup.py` | **Disaster Recovery** | 핵심 데이터(DB, .env, 첨부파일) 증분 백업 도구 |
+
+---
+
+## 🏗️ 2. 설계 아키텍처 (Design Architecture)
+
+### 2.1 Backend: Blueprint-based Modular Flask
+- **패키지 구조**: `app/__init__.py`에서 중앙 집중식으로 앱을 생성하고, `routes/` 아래의 각 기능을 Blueprint로 등록합니다.
+- **보안 실드 (Security Shield)**: `before_request` 단계에서 비정상적인 트래픽 및 파라미터를 필터링하는 로깅 시스템이 선제적으로 작동합니다.
+- **성능 최적화 (Bulk Fetch)**: 다량의 메모리 조회 시 발생하는 N+1 문제를 방지하기 위해 태그, 첨부파일, 백링크 정보를 한꺼번에 Fetch하는 벌크 조회 로직이 적용되었습니다.
+
+### 2.2 Frontend: Modular Component Architecture
+- **지식 네뷸라 (Knowledge Nebula)**: D3.js의 물리 시뮬레이션 엔진을 도입하여 유기적인 성단 구조를 시각화합니다.
+- **컴포넌트 중심 설계**: `HeatmapManager.js` (활동 시각화), `CalendarManager.js` (달력), `Visualizer.js` (그래프), `DrawerManager.js` (탐색기) 등으로 독립된 모듈 구조를 채택하여 유지보수성을 극대화했습니다.
+- **레이아웃 혁명**: **무한 스크롤(Infinite Scroll)** 페이징 기법을 도입하여 수천 개의 지식 파편도 성능 저하 없이 탐색할 수 있습니다.
+- **State Management**: `AppService.js`를 중앙 상태 관리 엔진으로 활용하여 데이터 요청과 UI 업데이트의 정합성을 유지합니다.
+
+### 2.3 Ops & Reliability
+- **Merged Configuration**: 개발/운영 환경의 환경변수를 한곳에서 관리하며, 배포 시 `.env` 파일을 통해 보안 설정이 주입됩니다.
+- **Surgical Cleanup**: 배포 시 운영 데이터(DB, Uploads)는 보존하고 코드 영역만 정밀하게 교체하는 수술적 배포 방식을 채택했습니다.
+- **Disaster Recovery**: `backup.py`를 통해 서버 침해나 시스템 붕괴 시에도 3대 핵심 자산(.env, DB, Uploads)만으로 즉시 복구가 가능한 구조를 갖췄습니다.

docs/features.md

@@ -0,0 +1,48 @@
+# 💎 핵심 기능 가이드 (v13.3)
+
+본 문서는 `뇌사료` 프로젝트를 상징하는 핵심 기능들인 **지식 시각화**, **암호화**, **AI 분석**에 대한 상세 명세를 담고 있습니다.
+
+## 🌌 1. 지식 네뷸라 (Knowledge Nebula)
+D3.js v7 물리 시뮬레이션 엔진을 통해 파편화된 메모들을 유기적인 우주 성단 구조로 시각화합니다.
+
+### 1.1 시각화 아키텍처
+- **엔진**: D3.js Force Simulation
+- **성단(Constellation) 로직**:
+    - **그룹 인력**: 같은 그룹에 속한 메모들은 서로를 끌어당겨 하나의 별무리를 형성합니다.
+    - **의미론적 연결**: 공통 태그를 공유하는 노드들 사이에 보이지 않는 인력을 설정하여 맥락이 유사한 지식들이 근접하게 배치됩니다.
+- **인터랙션**: 노드 클릭 시 상세 정보 모달이 출력되며, 마우스 호버 시 연결된 지식망이 강조(Highlight)됩니다.
+
+## 🔒 2. 이중 보안 암호화 시스템 (Dual-Layer Security)
+
+### 2.1 메모 및 파일 보안
+- **개별 암호화**: 메모마다 고유한 비밀번호를 사용하여 `Fernet (AES-128 CBC/HMAC)` 방식으로 본문을 암호화합니다.
+- **미디어 실드 (v10.1)**: 모든 첨부파일은 서버 마스터 키로 암호화되어 저장됩니다. 암호화된 메모의 이미지는 **로그인된 세션**에서만 정밀하게 렌더링을 허용하여 데이터 유출을 원천 차단합니다.
+
+## 🧠 3. Gemini AI 기반 지식 구조화 (AI Insight)
+
+### 3.1 자동 추출 및 요약
+- **학습된 페르소나**: 최신 Gemini 2.0 Flash 모델이 메모의 맥락을 분석하여 핵심 요약과 태그를 생성합니다. (.env에서 모델 식별자를 언제든 변경할 수 있습니다.)
+- **지능형 연동**: AI가 생성한 태그는 지식 네뷸라 엔진의 인력 설정에 반영되어, 사용자가 명시적으로 연결하지 않아도 관련 지식끼리 우주 상에서 가까이 부유하게 됩니다.
+
+## 🔗 4. 내부 링크 및 백링크 시스템
+
+### 4.1 연결 문법 (`[[#ID]]`)
+- **자동 링크**: 본문에 `[[#12]]`와 같이 입력하면 뷰어에서 클릭 가능한 링크로 변환되며, 지식 맵 상에서 두 노드 사이에 **강력한 실선**이 형성됩니다.
+- **역방향 추적 (Backlinks)**: 특정 메모 카드 하단에 해당 메모를 인용 중인 다른 메모의 목록이 노출되어, 지식의 흐름을 양방향으로 추적할 수 있습니다.
+27: 
+32: ## 🌡️ 5. 지식 성장 히트맵 (Intellectual Growth Heatmap) - v14.0
+33: 
+34: ### 5.1 활동 시각화
+35: - **기록 습관 형성**: 최근 365일간의 활동량을 GitHub 스타일의 그리드로 시각화하여 지식 축적의 꾸준함을 독려합니다.
+36: - **동적 범위 필터링**: 사용자의 필요에 따라 **1개월 / 3개월 / 6개월 / 1년** 단위를 자유롭게 선택하여 볼 수 있습니다.
+37: - **상태 보존**: 선택한 보기 설정은 `localStorage`에 저장되어 재접속 시에도 유지됩니다.
+38: 
+39: ### 5.2 지능형 히트맵 알고리즘
+40: - **단계별 농도**: 해당 일의 메모 작성 수에 따라 5단계(`lvl-0`~`lvl-4`)의 색상 농도가 적용됩니다.
+41: - **프리미엄 그라데이션**: 뇌사료 특유의 Cyan(시안)에서 Purple(보라)로 이어지는 네온 그라데이션 테마를 따릅니다.
+42: 
+43: ## 🎨 6. 확장된 에디터 스타일링 (Enhanced Editor)
+44: 
+45: ### 6.1 컬러 텍스트 (Color Syntax)
+46: - **시각적 강조**: Toast UI Editor의 컬러 신택스 플러그인을 통합하여, 본문 중 중요한 지식 키워드를 다양한 색상으로 강조할 수 있습니다.
+47: - **지각적 설계**: 다크 모드 환경에서도 가독성이 뛰어난 색상 팔레트를 우선적으로 제공합니다.

docs/logic_flow.md

@@ -0,0 +1,55 @@
+# ⚙️ 로직 흐름 및 비즈니스 규칙 (v5.0+)
+
+본 문서는 `뇌사료` 프로젝트 내부에서 작동하는 특수 로직들과 데이터 처리 규칙을 상세히 설명합니다.
+
+## 🔒 1. 암호화 전이 및 보안 로직
+본 시스템은 메모의 보안 상태 변화에 따른 정교한 전이 로직을 가지고 있습니다.
+
+### 1.1 암호화 해제 시 상태 전이
+- **명시적 해제**: 사용자가 비밀번호를 입력하여 암호화를 해제하고 저장하는 경우, 해당 메모는 **평문(Plaintext)** 상태로 전환됩니다. 이는 사용자의 명시적 의사 결정으로 간주합니다.
+- **수정 시 유지**: 암호화된 상태에서 내용만 수정할 경우, 기존 비밀번호를 사용하여 백엔드에서 다시 암호화(Re-encrypt) 과정을 거쳐 저장됩니다.
+
+### 1.2 첨부파일 접근 제어 (403 해결)
+- **인증 연동**: `/api/download` 라우트는 단순히 파일 존재 여부만 체크하지 않고, 사용자의 **세션 로그인 여부**를 확인합니다.
+- **인라인 표시**: 이미지 파일의 경우 `Content-Disposition: inline` 헤더를 강제하여 브라우저 마크다운 본문 내에서 선명하게 렌더링되도록 지원합니다.
+
+---
+
+## 🌌 2. 지식 네뷸라 성단(Constellation) 로직
+D3.js 엔진은 데이터 간의 명시적 링크 외에도 의미론적 연결을 자동으로 시뮬레이션합니다.
+
+### 2.1 자동 연결 규칙 (Semantic Linking)
+1. **명시적 링크**: `[[#ID]]` 패턴으로 작성된 내부 링크 (실선 표시).
+2. **동일 그룹**: 같은 그룹에 속한 메모들끼리 부유하며 성단을 형성 (은은한 연결선).
+3. **공통 태그**: 같은 태그를 공유하는 메모들 사이에 인력이 작용하여 근접 배치.
+
+### 2.2 이미지 경로 보정 (Path Resolution)
+- **후처리 로직**: 마크다운 본문의 `img src="photo.png"`와 같은 상대 경로를 `fixImagePaths` 유틸리티가 감지하여 `/api/download/photo.png`로 자동 보정합니다.
+
+---
+
+---
+
+## 🔄 3. 애플리케이션 라이프사이클 및 데이터 흐름
+### 3.1 초기화 및 갱신 사이클 (App Cycle)
+1. **DOM 로드**: `DOMContentLoaded` 발생 시 모든 매니저(`Editor`, `Heatmap`, `Visualizer` 공히)가 `init()`을 거칩니다.
+2. **데이터 호출**: `AppService.refreshData()`가 실행되어 첫 페이지 메모를 가져옵니다.
+3. **병렬 동기화**: 메모 데이터 수신 시 `HeatmapManager.refresh()`가 별도 API를 호출하여 최근 1년(또는 선택 기간)의 통계를 가져와 렌더링합니다.
+
+### 3.2 검색 및 실시간 필터링 (Debounce)
+- **지연 처리**: 검색창 입력 시 300ms의 `searchTimer`가 작동하여 불필요한 API 요청을 최소화합니다.
+- **상태 통합**: 검색어는 그룹/날짜 필터와 결합되어 중앙 상태(`AppService.state`)에서 관리됩니다.
+
+### 3.3 무한 스크롤 및 페이징 (Infinite Scroll)
+- **오프셋 제어**: `this.state.offset`을 통해 현재 로드된 개수를 추적하며, 하단 도달 시 `limit` 단위로 다음 데이터를 추가 로드합니다.
+
+---
+
+## 🚀 4. 정밀 배포 및 재난 복구 로직
+
+### 4.1 수술적 정리 (Surgical Cleanup)
+- **보호 대상**: `.env`, `data/`, `static/uploads/`, `memos.db` 등 사용자의 생성 데이터는 삭제 목록에서 철저히 제외됩니다.
+- **정밀 삭제**: 부모 폴더(예: `static`)를 지우지 않고 그 내부의 코드(JS, CSS)만 선별 삭제하여, 하위의 보호 폴더(`uploads`) 유실을 방지합니다.
+
+### 4.2 핵심 자산 백업 (Disaster Recovery)
+- **3대 요소**: DB, 첨부파일, 환경설정(.env)을 하나의 압축파일(`tar.gz`)로 통합합니다. 이 세 가지만 있으면 서버가 완전히 붕괴되어도 다른 환경에서 즉시 복호화 및 서비스 재개가 가능합니다.

docs/shortcuts.md

@@ -0,0 +1,32 @@
+# ⌨️ 단축키 가이드 (Keyboard Shortcuts)
+
+'뇌사료'를 더욱 빠르고 효율적으로 활용하기 위한 단축키 일람입니다. 
+**Ctrl + Shift**를 주력으로 하며, 전설적인 **Quake 스타일**의 새 메모 단축키를 추가 지원합니다.
+
+## 🚀 전역 단축키 (Global Navigation)
+어느 화면에서나 즉시 실행됩니다.
+
+- **`Alt + `** (Backtick): ⚡ **Quake 스타일 새 메모** (가장 빠른 작성기 호출)
+- **`Ctrl + Shift + N`**: 📝 **새 메모 작성**
+- **`Ctrl + Shift + G`**: 🕸️ **지식 네뷸라** (시각화 모달 열기)
+- **`Ctrl + Shift + E`**: 🔍 **지식 탐색기** (사이드바 드로어 열기)
+- **`Ctrl + Shift + C`**: 📅 **캘린더 토글** (사이드바 미니 달력)
+- **`Ctrl + Shift + Q`** 또는 **`ESC`**: 🚪 **닫기**
+
+---
+
+## ✍️ 메모 편집 (Editor Mode)
+- **`Ctrl + Enter`** 또는 **`Ctrl + S`**: 💾 **저장 및 게시**
+- **`/` (Slash)**: 🪄 **슬래시 명령**
+- **`Shift + ESC`**: 🗑️ **작성 취소**
+
+---
+
+## 🖱️ 마우스 인터렉션
+- **Alt + 클릭**: 🪄 **즉시 수정**
+- **클릭**: 상세 보기
+
+---
+
+> [!TIP]
+> - **`Alt + `** 단축키는 게임 'Quake'의 콘솔창 호출 방식에서 유래한 것으로, 영감이 떠오른 순간 가장 빠르게 기록을 시작할 수 있는 방법입니다.

docs/source_mapping.md

@@ -0,0 +1,42 @@
+# 🔗 소스 매핑 및 호출 관계 (v13.4)
+
+본 문서는 프론트엔드 컴포넌트와 백엔드 API, 그리고 내부 함수 간의 호출 관계와 인터페이스를 기술합니다.
+
+## 📱 1. 프론트엔드 모듈간 관계
+
+| 모듈 (Component) | 기능 설명 | 주요 호출 (Callee) |
+| :--- | :--- | :--- |
+| `app.js` | **Orchestrator** | `Visualizer`, `DrawerManager`, `ModalManager`, `API` |
+| `Visualizer.js` | **Nebula Engine** | `D3.js`, `ModalManager.open()`, `AppService` |
+| `DrawerManager.js` | **Explorer** | `AppService.filterMemos()`, `ModalManager` |
+| `ModalManager.js` | **Viewer** | `utils.parseInternalLinks()`, `utils.fixImagePaths()` |
+| `ComposerManager.js` | **Editor** | `API.saveMemo()`, `AttachmentBox` |
+
+---
+
+## ⚙️ 2. 백엔드 핵심 함수 매핑
+
+### 2.1 보안 및 유틸리티
+| 함수명 | 모듈 | 역할 | 호출자 |
+| :--- | :--- | :--- | :--- |
+| `decrypt_file` | `app/security.py` | 첨부파일 물리 복호화 | `file.py:download_file` |
+| `extract_links` | `app/utils.py` | `[[#ID]]` 패턴 추출 | `memo.py:create/update` |
+
+### 2.2 운영 도구 (Ops)
+| 파일명 | 역할 | 주요 로직 |
+| :--- | :--- | :--- |
+| `deploy.py` | **정밀 배포** | SSH/SFTP 기반 Surgical Cleanup & Upload |
+| `backup.py` | **백업** | 핵심 자산(.env, DB, Uploads) Tarball 생성 |
+
+---
+
+## 🌐 3. 클라이언트-서버 통신 파라미터 (API Flow)
+
+### 3.1 `GET /api/download/<filename>` (보안 하향 링크)
+- **Caller**: `ModalManager.js` (Inline Images) or `AttachmentBox.js`
+- **Security**: `session['logged_in']` 확인 -> `is_encrypted` 상태에 따른 접근 제어.
+- **Header**: 이미지인 경우 `Content-Disposition: inline`.
+
+### 3.2 `PUT /api/memos/<id>` (수정 및 보안 전이)
+- **Status Change**: 암호화 해제 저장 시 `is_encrypted: 0`으로 DB 상태 업데이트.
+- **Process**: `memo.py:update_memo`에서 `password` 유무에 따른 Re-encryption 수행.

docs/user_manual.md

@@ -0,0 +1,113 @@
+# 📔 뇌사료 (Brain Dogfood) 사용자 매뉴얼 (v5.0+)
+
+'뇌사료' 프로젝트에 오신 것을 환영합니다! 본 매뉴얼은 파편화된 영감을 체계적인 지식 성단(Nebula)으로 구축하는 데 필요한 모든 가이드를 제공합니다.
+
+---
+
+## 🌌 1. 지식 네뷸라 (시각화 탐색)
+
+메인 전면에 펼쳐진 **지식 네뷸라**는 단순한 목록이 아닌 지식의 유기적인 지도를 보여줍니다.
+
+- **노드(Node)**: 각각의 메모를 상징합니다.
+    - **크기**: 내용이 많거나 연결이 많을수록 노드가 거대해집니다.
+    - **색상**: 각 메모에 설정된 고유한 그룹 색상을 따릅니다.
+    - **🔒 아이콘**: 암호화된 메모임을 나타내며, 제목만 미리보기로 제공됩니다.
+- **링크(Link)**: 
+    - **실선**: `[[#ID]]` 문법으로 명시적으로 연결된 관계입니다.
+    - **인력(Gravity)**: 같은 그룹이나 공통 태그를 가진 메모들은 서로를 끌어당겨 가까이 배치됩니다.
+
+---
+
+## 🌡️ 3. 지식 성장 히트맵 (Heatmap) 사용법
+
+사이드바에 위치한 히트맵은 사용자의 기록 강도를 시각적으로 보여줍니다.
+
+- **기간 전환**: 히트맵 상단 제목 옆의 드롭다운을 통해 **1개월 / 3개월 / 6개월 / 1년** 단위를 선택할 수 있습니다.
+- **상태 유지**: 한 번 선택한 기간은 브라우저에 저장되어 다음 접속 시에도 그대로 유지됩니다.
+- **활동량 확인**: 각 칸에 마우스를 올리면 해당 날짜에 작성된 메모의 개수를 확인할 수 있습니다. 색상이 진해질수록(Cyan -> Purple) 더 많은 지식을 축적했음을 의미합니다.
+
+---
+
+## ✍️ 4. 메모 작성 및 스타일링
+
+### 4.1 지식 연결 문법 (`[[#ID]]`)
+메모 간의 명시적인 지식을 연결하려면 본문에 샵(#) 기호와 메모 번호를 사용하세요.
+> 예: "이 개념은 `[[#12]]`에서 다룬 내용과 상충됩니다."
+- **효과**: 뷰어에서 클릭 시 해당 메모로 바로 이동하며, 지식 네뷸라 상에 강력한 연결선이 형성됩니다.
+
+### 4.2 컬러 텍스트 (Color Syntax)
+에디터 상단 툴바의 **색상 선택 아이콘**을 사용하여 텍스트에 색상을 입힐 수 있습니다. 중요 키워드를 강조하여 지식의 가독성을 높이세요.
+
+### 4.3 개별 메모 암호화
+중요한 개인 정보나 아이디어는 암호화하여 보호할 수 있습니다.
+- **사용법**: 편집기 하단의 **[암호화 사용]** 체크 -> 비밀번호 설정.
+- **특약**: 암호화된 메모는 서버 측에서도 해독이 불가능하며, 비밀번호 분실 시 복구가 절대 불가능하므로 주의하세요.
+- **복호화**: 작성된 암호화 메모 옆의 **🔓 해독** 버튼을 눌러 비밀번호 입력 시 일시적으로 내용을 확인할 수 있습니다.
+
+---
+
+---
+
+## 🧠 5. AI 인텔리전스 (AI Insights)
+
+### 5.1 AI 활성화 및 API 키 설정 (초보자 가이드)
+'뇌사료'의 지능형 기능을 사용하려면 Google의 Gemini API 키가 필요합니다. 다음 단계에 따라 **1분 만에 무료로** 설정을 마칠 수 있습니다.
+
+1.  **키 발급**: [Google AI Studio (https://aistudio.google.com/app/apikey)](https://aistudio.google.com/app/apikey)에 접속합니다.
+2.  **프로젝트 생성**: "Create API key in new project" 버튼을 누릅니다.
+3.  **키 복사**: 생성된 `AIza...`로 시작하는 긴 문자열을 복사합니다.
+4.  **서버 적용**: 본 프로젝트 폴더의 `.env` 파일을 열고 `GEMINI_API_KEY=` 뒤에 복사한 키를 붙여넣고 저장합니다.
+5.  **활성화**: 앱 우상단 **[⚙️ 설정]** -> **AI 기능 활성화** 체크박스를 켜고 저장합니다.
+
+> [!TIP]
+> - API 키 발급은 완전히 무료이며, 개인적인 용도로는 충분한 할당량이 제공됩니다.
+> - 키가 없더라도 메모 작성 및 시각화 등 기본적인 기능은 "NO AI" 모드로 완벽하게 작동합니다.
+
+### 5.2 주요 기능
+- **자동 요약**: 방대한 내용을 AI가 1~2문장의 핵심 문장으로 압축해줍니다.
+- **스마트 태그**: 본문을 분석하여 자동으로 추천 태그를 생성합니다. 
+- **추론형 배치**: AI가 생성한 태그를 기반으로 지식 네뷸라 상에서 비슷한 맥락의 메모들이 자동으로 성단을 형성합니다.
+
+---
+
+---
+
+## ⌨️ 6. 단축키 및 작업 효율 (Shortcuts)
+
+'뇌사료'는 마우스 없이도 거의 모든 작업을 수행할 수 있도록 강력한 **Ctrl 기반** 단축키를 지원합니다.
+
+### 6.1 전역 내비게이션
+- **`Alt + `** (Backtick): ⚡ **Quake 스타일 새 메모** (영감을 즉시 기록)
+- **`Ctrl + Shift + N`**: 새 메모 작성기 열기 📝
+- **`Ctrl + Shift + G`**: 지식 네뷸라(시각화) 열기 🕸️
+- **`Ctrl + Shift + E`**: 지식 탐색기(사이드바) 열기 🔍
+- **`Ctrl + Shift + C`**: 사이드바 캘린더 토글 📅
+- **`Ctrl + Shift + Q`** 또는 **`ESC`**: 모든 모달 및 드로어 닫기
+
+### 6.2 에디터 작업
+- **`Ctrl + Enter`** 또는 **`Ctrl + S`**: **현재 메모 저장 및 게시** 💾
+- **`/` (Slash)**: 슬래시 명령 오픈 (AI 요약, 서식 등) 🪄
+- **`Shift + ESC`**: 작성 취소 및 닫기
+
+### 6.3 마우스 팁
+- **`Alt + 클릭`**: 메인 그리드에서 메모를 즉시 수정 ✏️
+
+---
+
+## 🚀 7. 운영 및 관리 (Ops & Backup)
+
+### 7.1 정밀 배포 (`deploy.py`)
+개발 환경에서 작업한 코드를 서버로 안전하게 배포합니다.
+```bash
+python deploy.py
+```
+
+### 7.2 재난 복구 백업 (`backup.py`)
+서버의 모든 핵심 데이터를 압축하여 안전하게 보관합니다.
+```bash
+python backup.py
+```
+
+---
+
+**지식의 우주를 마음껏 탐험하세요!** 🛸🌌

docs/v2_mobile_roadmap.md

@@ -0,0 +1,49 @@
+# 📱 v2.0 모바일 최적화 로드맵 (Roadmap)
+
+본 문서는 `뇌사료` 프로젝트 v2.0에서 다룰 모바일 해상도 지원 및 UX 최적화 범위에 대한 정밀 분석 내역을 담고 있습니다.
+
+## 1. 레이아웃 및 응답성 (Responsive Layout)
+
+### 1.1 오프캔버스 사이드바 (Off-canvas Sidebar)
+-   **현황**: 사이드바가 가로 공간을 상시 점유하여 모바일에서 가독성 저해.
+-   **v2.0 목표**: 768px 이하에서 사이드바를 기본적으로 숨기고, 상단 햄버거 메뉴 버튼 클릭 시 왼쪽에서 슬라이드되는 드로어(Drawer) 방식으로 전환.
+-   **기술적 구현**: `transform: translateX(-100%)` 및 `z-index`를 활용한 오버레이 처리.
+
+### 1.2 가변형 메모 그리드 (Fluid Masonry Grid)
+-   **현황**: 열 개수가 고정되거나 모바일에서 너무 좁게 보임.
+-   **v2.0 목표**: 모바일 해상도에서 메모 카드를 1열(100%)로 강제하여 텍스트 가독성 극대화. 패딩 값을 `3rem`에서 `1rem`으로 축소.
+
+---
+
+## 2. 입력 및 작성 경험 (Composer UX)
+
+### 2.1 인터페이스 수직 스태킹 (Vertical Stacking)
+-   **현황**: 제목, 그룹, 태그 입력창이 가로로 배치되어 모바일에서 잘림.
+-   **v2.0 목표**: `flex-direction: column`을 적용하여 제목 -> 메타 정보(그룹/태그) -> 에디터 순서로 자연스럽게 흐르도록 재배치.
+
+### 2.2 모바일 에디터 최적화
+-   **v2.0 목표**: Toast UI 에디터의 불필요한 툴바를 숨기고, 모바일 자판이 올라와도 입력 영역이 충분히 확보되도록 높이 자동 조절 기능 추가.
+
+---
+
+## 3. 터치 및 제스처 (Touch & Gestures)
+
+### 3.1 터치 타겟(Touch Target) 확장
+-   **목표**: 모든 버튼 및 상호작용 요소의 크기를 최소 44x44px 이상으로 확보하여 오클릭 방지.
+-   **세부 사항**: 삭제, 수정, 암호화 토글 버튼의 여백 조정.
+
+### 3.2 제스처 지원
+-   **목표**: 화면 왼쪽 가장자리를 스와이프하여 사이드바를 여는 제스처 로직 검토.
+
+---
+
+## 4. 기술적 체크리스트 (Technical Checklist)
+
+-   [ ] `@media (max-width: 768px)` 기준점 확립.
+-   [ ] 터치 이벤트(`touchstart`, `touchend`) 처리 최적화.
+-   [ ] `safe-area-inset-bottom` 등 최신 모바일 기기의 노치 및 하단 바 대응.
+-   [ ] 모바일 데이터 환경을 고려한 이미지 지연 로딩(Lazy Loading) 적용.
+-   [ ] 모달 창의 `width: 100%; height: 100%;` 전체 화면 모드 지원.
+
+---
+*Generated for Brain Dogfood v2.0 Development*