# VibeNotes 공식 사용자 및 운영자 매뉴얼 (User & Operator Manual) > **"판단 자체가 곧 문제 해결 과정이다."** > VibeNotes는 정보의 단순 저장을 넘어, 사용자의 의식적 인지 협업과 책임 있는 의사결정을 돕는 **의식적 인지 작업공간(Conscious Cognitive Workspace)**입니다. --- ## 1. VibeNotes 개요 및 설계 철학 현대 지식 노동과 AI 협업의 본질적 병목은 "답변의 생성"이 아니라 **"답변의 신뢰성 검증과 실행 판단"**입니다. VibeNotes는 AI가 사용자를 대신해 결정을 내리는 것이 아니라, 인간의 문제 해결 루프 안에서 협력자로 작동하는 **Machine in the Loop (MITL)** 원칙을 따릅니다. ### Co-OS 3대 패턴 거버넌스 - **Fixed (불변식 & 기계적 무결성)**: CAS(Compare-and-Swap) 기반 리비전 충돌 방지, 248개 불변식 린터, 파일 시스템 격리 및 샌드박스 보안. - **Flexible (창의적 대안 & 탐색)**: 3-페르소나(경영진·엔지니어·초심자) 모의 독자 시뮬레이션, Gary Klein RPD 성찰 질문을 통한 잠재적 가정 발굴. - **Decision (인간 책임 결속점)**: 원클릭 자동 보강과 20단계 실행 취소(`_undoStack`)를 지원하여 모든 변경의 최종 승인 권한을 사용자에게 보장. --- ## 2. 3단계 순차 기동 절차 (3-Step Deterministic Launch Flow) VibeNotes는 보안과 로컬 무결성을 위해 임의의 뷰 우회를 엄격히 차단하며, **Step 1 ➔ Step 2 ➔ Step 3**의 3단계를 순차적으로 통과해야 본 앱에 진입합니다. ```mermaid flowchart LR Step1["Step 1: 로그인 (#login)
TheProxy OIDC / 로컬 게스트"] --> Step2["Step 2: 기기 부트스트래핑 (#bootstrap)
macOS 권한 & DuckDB 원장 확인"] Step2 --> Step3["Step 3: 본 앱 진입 (#home)
오늘의 나 작업공간 활성화"] ``` ### [Step 1] VibeNotes 로그인 (`#login`) - **UI 상태**: 상단 헤더 및 좌측 사이드바가 잠금 처리(`body.vn-auth-locked`)되어 외부 내비게이션이 비활성화됩니다. - **인증 옵션**: 1. **TheProxy 계정으로 로그인**: TheProxy OIDC 중앙 인증을 거쳐 로컬 기기 페어링(`/connect/mac`, `returnTo` 딥링크 지원)을 수행합니다. 2. **로컬 작업공간으로 시작**: 외부 네트워크 연결 없이 완전한 온디바이스 로컬 모드로 즉시 기동합니다. - **통과 조건**: 인증 토큰 획득 또는 로컬 게스트 승인 시 Step 2로 자동 전환. ### [Step 2] 기기 권한 및 원장 부트스트래핑 (`#bootstrap`) - **기능**: VibeNotes가 macOS 시스템 및 로컬 데이터베이스와 안전하게 통신할 수 있도록 필수 런타임 환경을 진단합니다. - **5대 필수 검사 항목**: 1. **캘린더 접근 권한**: macOS EventKit 캘린더 일정 동기화. 2. **시스템 자동화 권한**: AppleScript 및 애플리케이션 간 안전한 신호 연동. 3. **손쉬운 사용 (Accessibility)**: 카카오톡 등 외부 메신저 UI 탐색 및 윈도우 인지. 4. **전체 디스크 접근 권한**: SQLite/Mailbox 로컬 신호 무손실 안전 판독. 5. **로컬 DuckDB 원장 무결성**: 로컬 암호화 저장소(`vibenotes.duckdb`) 스키마 및 쓰기 권한 검증. - **진입**: "기기 권한 점검 완료 및 VibeNotes 시작" 버튼을 누르면 작업공간 크롬 잠금이 해제되며 Step 3로 이동합니다. ### [Step 3] 본 앱 진입 (`#home`) - '오늘의 나' 메인 대시보드로 진입하여 사이드바, 도크, AI 어시스턴트 등 전체 기능이 활성화됩니다. - 로그아웃 실행 시 로컬 세션 및 진행 플래그가 안전하게 초기화되어 다시 Step 1로 복귀합니다. --- ## 3. 정보구조(IA) 및 5대 도크 내비게이션 VibeNotes는 인지 부하를 줄이기 위해 **1장면 1주동사(1-Scene 1-Primary-Verb)** 원칙에 따라 설계되었습니다. 좌측 도크는 5개 기능 그룹(그룹당 최대 4개 항목)으로 체계화되어 있습니다. ```mermaid flowchart TD Dock["VibeNotes 5대 도크 내비게이션"] Dock --> G1["그룹 1 [내 작업]
오늘(#home) · 노트북(#notebooks) · 프로젝트(#projects) · 노트(#notes)"] Dock --> G2["그룹 2 [일정과 자료]
캘린더(#calendar) · 신호함(#signals) · 서재와 숙의(#board) · 데이터 분석(#data-analysis)"] Dock --> G3["그룹 3 [앱과 확장]
AI 대화(#ai) · 로컬 모델 관리(#app-local-model) · 마켓(#extensions)"] Dock --> G4["그룹 4 [최근 작업]
데이터 분석 원장 · 최근 노트와 판단 · 신호 인박스 확인"] Dock --> G5["그룹 5 [도구 & 설정]
기기·수집 설정 · 전체 동기화 · 신호 마법사 · 테마 전환"] ``` ### 17개 표준 장면 및 주동사 명세 | 장면 식별자 | 뷰 경로 | 표기명 | 주 행동 동사 | 설명 | | :--- | :--- | :--- | :--- | :--- | | **Scene 1** | `#home` | 오늘 | **초점 정하기** | 당일 3대 우선순위, 퀵노트, 오늘의 AI 큐레이션 | | **Scene 2** | `#notebooks` | 노트북 | **맥락 묶기** | 주제별 노트북 생성, 속성 관리, 보관(Archive) | | **Scene 3** | `#projects` | 프로젝트 | **목표 완주하기** | 프로젝트 상태(기획/진행/완료), 마일스톤 추적 | | **Scene 4** | `#notes` | 노트 | **생각 집필하기** | VibeNotesEditor 블록 편집기, 슬래시(`/`) 명령 | | **Scene 5** | `#calendar` | 캘린더 | **시간 조율하기** | macOS 캘린더 연동, 일별/주별 일정 타임라인 | | **Scene 6** | `#signals` | 신호함 | **신호 선별하기** | 외부 앱(카톡, 메일, 메모) 수집 신호 검토 | | **Scene 7** | `#board` | 서재와 숙의 | **자료 숙의하기** | 수집된 문헌, 리서치 팩트 대조 및 숙의 캔버스 | | **Scene 8** | `#data-analysis` | 데이터 분석 | **원장 분석하기** | DuckDB 로컬 SQL 쿼리, 시계열 통계 차트 | | **Scene 9** | `#ai` | AI 대화 | **협력 자문하기** | 다중 LLM 엔진 자문, RPD 성찰 대화 | | **Scene 10** | `#app-local-model`| 로컬 모델 관리 | **엔진 전환하기** | 호스트 실측 LLM 모델 감지 및 활성화 | | **Scene 11** | `#extensions` | 마켓 | **기능 확장하기** | Co-OS 플러그인, 위젯, 외부 커넥터 관리 | | **Scene 12** | `#login` | 로그인 | **계정 연결하기** | TheProxy OIDC 및 로컬 인증 (Step 1) | | **Scene 13** | `#bootstrap` | 기기 부트스트래핑 | **권한 확인하기** | 시스템 접근 권한 및 원장 무결성 검증 (Step 2) | | **Scene 14** | `#settings` | 환경 설정 | **환경 맞춤하기** | 테마, 폰트, 단축키, 프라이버시 정책 구성 | | **Scene 15** | `#timeline` | 타임라인 | **흐름 되짚기** | 시계열 활동 로그 및 변경 이력 추적 | | **Scene 16** | `#workspace` | 워크스페이스 | **영역 관리하기** | 다중 작업공간 전환 및 멤버 권한 설정 | | **Scene 17** | `#archive` | 보관함 | **기록 보존하기** | 완료된 프로젝트 및 오래된 노트의 안전 보관 | --- ## 4. 내 컴퓨터 로컬 LLM 및 프론티어 AI 통합 VibeNotes는 가공의 하드코딩 모델 목록을 배제하고, **사용자의 Mac 로컬 환경에 실제로 설정·설치된 모델을 정밀 측정하여 표시**합니다. ```mermaid flowchart TD Detector["Native LLMDetector (Swift) & Rust Bridge"] Detector --> Codex["OpenAI Codex CLI
설정값: ~/.codex/config.toml (gpt-6-sol)"] Detector --> Claude["Anthropic Claude Code
설정값: ~/.claude.json (claude-3-7-sonnet)"] Detector --> AGY["Google AGY / Gemini CLI
설정값: gemini-4-argon-high / gemini-2.5-pro"] Detector --> Llama["Llamafile On-Device (Apple Metal)
디렉터리: ~/models/*.gguf (오프라인 보존)"] ``` ### 호스트 실측 모델 스택 1. **Google Antigravity CLI (AGY)**: 측정 모델 `gemini-4-argon-high` 2. **Anthropic Claude Code**: 측정 모델 `claude-3-7-sonnet` 3. **OpenAI Codex / ChatGPT CLI**: 측정 모델 `gpt-6-sol` 4. **Google Gemini CLI**: 측정 모델 `gemini-2.5-pro` 5. **Llamafile On-Device AI (Apple Metal)**: `~/models/` 내 보유 GGUF 모델(`Qwen3.5-2B-Q4_K_M.gguf` 등) 목록 및 오프라인 대기 상태 표시. 서버 미구동 시에도 등록 모델을 보존하여 불필요한 오류 알림을 방지합니다. ### AI 모델 선택 및 협력 사용법 1. 도크에서 **로컬 모델 관리 (`#app-local-model`)**를 엽니다. 2. 각 서비스별 카드에서 실제 설정값으로 자동 선택된 모델을 확인하고 **[이 로컬 모델 선택]**을 클릭합니다. 3. 도크의 **AI 대화 (`#ai`)**로 이동하여 상단에 표시된 선택 모델과 즉시 질의응답 및 성찰 대화를 나눕니다. --- ## 5. 지능형 신호 수집 엔진 및 카카오톡 선별 추적 VibeNotes는 사용자의 프라이버시를 최우선으로 보호하며, 무차별적인 화면 스크래핑을 금지합니다. ### 카카오톡 선별 지속 추적 (Selective Continuous Tracking) - **핵심 불변식**: 전체 대화방을 일괄 수집하지 않고, **사용자가 명시적으로 추적을 요청한 대화방만 선별 추적**합니다. - **지속성**: 사용자가 대화창에서 명시적으로 **"중단"을 요청할 때까지 백그라운드에서 추적을 유지**합니다. - **비간섭성**: 카카오톡 창을 활성화하거나 포커스를 빼앗지 않으며, macOS Accessibility API(AXUIElement)를 통해 무간섭으로 메시지를 수집합니다. - **수집 파이프라인**: 1. 신호함(`#signals`) ➔ [카카오톡 추적 설정] 진입. 2. 추적할 대화방 제목 입력 및 [추적 시작] 클릭. 3. 백그라운드 센티널(`vibenotes-kakao-sentinel`)이 5초 간격으로 신규 메시지 증분을 감지하여 로컬 DuckDB에 멱등 보관. 4. 추적 중단 시 [추적 중지] 버튼 또는 명령어로 즉시 안전 해제. ### Apple 시스템 신호 연동 - **Apple Notes (메모)**: 변경된 최근 노트를 비파괴적으로 읽어 초안 후보로 등록. - **Apple Mail (메일)**: 플래그가 지정된 중요 메일의 발신자, 제목, 요약을 신호함으로 인입. - **Apple Calendar (캘린더)**: 당일 회의 및 약속을 '오늘의 나' 타임라인에 동기화. --- ## 6. VibeNotesEditor 집필 및 인지 평가 엔진 ### 블록 기반 통합 편집기 - **슬래시(`/`) 명령**: 제목(H1/H2/H3), 할 일, 글머리 기호, 번호 목록, 콜아웃, 인용구, 코드 블록, 구분선 등 11종 블록을 키보드 단축으로 즉시 생성. - **양방향 마크다운 직렬화**: 모든 블록은 표준 마크다운(`.md`)과 실시간 1:1 동기화됩니다. ### 5축 인지 평가 (5-Axis Evaluation) 문서 작성 중 우측 인지 패널에서 다음 5개 축을 실시간 감사합나다: 1. **A1. 주장 & 경계 무결성 (Claim & Boundary)**: 근거 없는 100% 단언 감지. 2. **A2. 3층 명시지 균형 (3-Tier Knowledge)**: 선언적(What), 절차적(How), 상황적(Why) 지식의 조화. 3. **A3. 1장면 1주동사 (1-Scene 1-Primary-Verb)**: 장면당 주 행동 동사 1개 고정 및 목표 산출물 점검. 4. **A4. 입출력 연계 파이프라인 (DAG Traceability)**: 선행 입력과 후행 산출물 간의 연결성. 5. **A5. 한국어 구어 자연성 (Spoken Korean Naturalness)**: 번역투 피동형, 모호한 관료어, 80자 이상 만연체 문장 정밀 교정. ### 8대 표준 자동 패치 (1-Click Auto Patch) - 발견된 인지 결함에 대해 **[1-클릭 자동 보강]** 버튼을 제공합니다. - 최대 20단계 실행 취소(`_undoStack`)를 지원하여 언제든 원본 상태로 복귀할 수 있습니다. --- ## 7. 빌드, 서명, 릴리즈 및 설치 관리 지침 운영자와 개발자는 다음의 표준 명령어를 통해 무결성이 검증된 데스크톱 앱을 빌드 및 배포합니다. ### 1. 5-Lens 패리티 및 행동 IA 감사 ```bash # 116개 소스 파일 해시 및 5-Lens 패리티 검증 npm run check:5lens-parity # 17개 표준 장면 및 행동 IA 규칙(1장면 1주동사, 5대 도크) 감사 python3 -B scripts/audit_vibenotes_behavioral_ia.py ``` ### 2. 통합 단위 및 시나리오 테스트 ```bash # 전체 핵심 자바스크립트 테스트 실행 (42/42 통과) node --test Tests/step_by_step_launch_flow.test.mjs \ Tests/theproxy_oidc_return_to.test.mjs \ Tests/llm_end_to_end_unification.test.mjs \ Tests/llm_model_curation_ui.test.mjs \ Tests/projects_recommendation.test.mjs \ Tests/home_view_actions.test.mjs # Rust 백엔드 테스트 (21/21 통과) cargo test --lib --manifest-path src-tauri/Cargo.toml ``` ### 3. 프로덕션 데스크톱 앱 빌드 & 코드 서명 ```bash # Vite 번들링 + Tauri 릴리즈 빌드 + Developer ID 서명 + DMG/ZIP 생성 bash scripts/build_vibenotes_desktop_app.sh ``` ### 4. 로컬 안전 설치 및 백업 관리 ```bash # 이전 버전 자동 ZIP 백업 + /Applications/VibeNotes.app 안전 교체 bash scripts/install_vibenotes_desktop_app.sh --install ``` > **[주의사항]**: > 빌드 및 설치 중에는 사용자 작업 데이터 보호를 위해 `/Applications/VibeNotes.app`이 실행 중이지 않아야 합니다. 실행 중일 경우 정상 종료 후 설치 스크립트를 재수행하십시오.