npm - @purpleraven/hits - Versions diffs - 0.2.0 → 0.2.2 - Mend

@purpleraven/hits 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/AGENTS.md CHANGED Viewed

@@ -19,137 +19,137 @@ If pre-flight checks fail, fix the errors before proceeding.
 ## AI Session Handover Protocol
-토큰 한계 등으로 AI 세션이 교체될 때, 프로젝트별 인수인계가 자동으로 동작합니다.
-모든 데이터는 `~/.hits/data/`에 중앙 집중 저장되며, 프로젝트 경로로 격리됩니다.
+When an AI session is replaced due to token limits, project-specific handover activates automatically.
+All data is centrally stored at `~/.hits/data/` and isolated by project path.
-### 세션 시작 시
+### On Session Start
 ```bash
-# HTTP API (HITS 서버 실행 중일 때)
+# HTTP API (when HITS server is running)
 curl -s "http://localhost:8765/api/handover?project_path=$(pwd)" | python -m json.tool
-# 또는 MCP 툴 (HITS MCP가 설정된 경우):
-# hits_get_handover → 이전 세션의 작업 내용, 결정 사항, 미완료 항목 조회
+# Or via MCP tool (when HITS MCP is configured):
+# hits_get_handover → Retrieve previous session's work, decisions, and unfinished items
 ```
-### 세션 종료 시 (반드시 기록)
+### On Session End (MUST record)
 ```bash
 curl -X POST http://localhost:8765/api/work-log \
   -H "Content-Type: application/json" \
   -d '{
-    "performed_by": "<AI_도구_이름>",
-    "request_text": "<작업 요약>",
-    "context": "<상세 내용, 결정 사항>",
+    "performed_by": "<AI_tool_name>",
+    "request_text": "<work summary>",
+    "context": "<details, decisions>",
     "source": "ai_session",
-    "tags": ["<태그>"],
-    "project_path": "<프로젝트_절대경로>",
+    "tags": ["<tag>"],
+    "project_path": "<project_absolute_path>",
     "result_data": {
-      "files_modified": ["<수정한_파일>"],
-      "commands_run": ["<실행한_명령>"]
+      "files_modified": ["<modified_file>"],
+      "commands_run": ["<executed_command>"]
     }
   }'
 ```
-### performed_by 규칙
+### performed_by Values
-| AI 도구 | performed_by 값 |
-|---------|----------------|
+| AI Tool | performed_by Value |
+|---------|-------------------|
 | OpenCode | `"opencode"` |
 | Claude Code | `"claude"` |
 | Cursor | `"cursor"` |
 | GitHub Copilot | `"copilot"` |
-| 사용자 직접 | `"manual"` 또는 사용자명 |
+| Manual | `"manual"` or username |
-### project_path 규칙
+### project_path Rules
-- **항상 절대경로 사용**: `"/home/user/source/my-project"` (O), `"./my-project"` (X)
-- **자동 감지**: CWD에서 `.git` 디렉토리가 있는 루트를 프로젝트 경로로 사용
-- **프로젝트별 격리**: 서로 다른 `project_path`는 완전히 독립된 인수인계 컨텍스트를 가짐
+- **Always use absolute paths**: `"/home/user/source/my-project"` (O), `"./my-project"` (X)
+- **Auto-detection**: Use the directory containing `.git` from CWD as the project path
+- **Project isolation**: Different `project_path` values have completely independent handover contexts
-### MCP 툴 사용 (권장)
+### MCP Tools (Recommended)
-HITS MCP 서버가 설정된 경우, HTTP API 대신 직접 툴 호출:
+When the HITS MCP server is configured, use direct tool calls instead of HTTP API:
 ```
-hits_record_work    → 작업 기록 (project_path 자동 감지)
-hits_get_handover   → 인수인계 요약 조회
-hits_search_works   → 이전 작업 검색
-hits_list_projects  → 프로젝트 목록
-hits_get_recent     → 최근 작업 조회
+hits_record_work    → Record work entry (auto-detects project_path)
+hits_get_handover   → Query handover summary
+hits_search_works   → Search past work
+hits_list_projects  → List projects
+hits_get_recent     → Get recent work
 ```
-### 기록 시점
+### When to Record
-- 사용자와 긴 작업 세션 종료 시
-- 주요 기능 구현 완료 시
-- 버그 수정 완료 시
-- 사용자가 명시적으로 종료 요청 시
-- **토큰 한계 경고 수신 시** (즉시 기록!)
+- At the end of a long work session with the user
+- After completing a major feature implementation
+- After fixing a bug
+- When the user explicitly requests to end the session
+- **On token limit warning** (record immediately!)
-### 데이터 저장소
+### Data Store
-| 위치 | 설명 |
-|------|------|
-| `~/.hits/data/work_logs/` | 작업 기록 (JSON) |
-| `~/.hits/data/trees/` | 지식 트리 |
-| `~/.hits/data/workflows/` | 워크플로우 |
-| `~/.hits/.auth/` | 인증 데이터 (권한 600/700) |
-| `HITS_DATA_PATH` 환경변수 | 저장소 경로 오버라이드 |
+| Location | Description |
+|----------|-------------|
+| `~/.hits/data/work_logs/` | Work logs (JSON) |
+| `~/.hits/data/trees/` | Knowledge trees |
+| `~/.hits/data/workflows/` | Workflows |
+| `~/.hits/.auth/` | Auth data (permissions 600/700) |
+| `HITS_DATA_PATH` env var | Override storage path |
 ## API Endpoints
-### 인증
+### Authentication
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/auth/status` | 인증 상태 (초기화 여부, 로그인 여부) |
-| POST | `/api/auth/register` | 사용자 등록 (첫 사용자 = admin) |
-| POST | `/api/auth/login` | 로그인 (HttpOnly 쿠키 설정) |
-| POST | `/api/auth/logout` | 로그아웃 |
-| POST | `/api/auth/refresh` | 액세스 토큰 갱신 |
-| GET | `/api/auth/me` | 현재 사용자 정보 |
-| PUT | `/api/auth/password` | 비밀번호 변경 |
+| GET | `/api/auth/status` | Auth status (initialized, logged in) |
+| POST | `/api/auth/register` | Register user (first user = admin) |
+| POST | `/api/auth/login` | Login (sets HttpOnly cookies) |
+| POST | `/api/auth/logout` | Logout |
+| POST | `/api/auth/refresh` | Refresh access token |
+| GET | `/api/auth/me` | Current user info |
+| PUT | `/api/auth/password` | Change password |
-### 작업 기록
+### Work Logs
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/health` | 서버 상태 확인 |
-| POST | `/api/work-log` | 작업 기록 생성 |
-| GET | `/api/work-logs` | 작업 기록 목록 (`project_path` 필터 지원) |
-| GET | `/api/work-logs/search?q=키워드` | 작업 검색 (`project_path` 필터 지원) |
-| GET | `/api/work-log/{id}` | 단건 조회 |
-| PUT | `/api/work-log/{id}` | 수정 |
-| DELETE | `/api/work-log/{id}` | 삭제 |
+| GET | `/api/health` | Server health check |
+| POST | `/api/work-log` | Create work log |
+| GET | `/api/work-logs` | List work logs (supports `project_path` filter) |
+| GET | `/api/work-logs/search?q=keyword` | Search work logs (supports `project_path` filter) |
+| GET | `/api/work-log/{id}` | Get single entry |
+| PUT | `/api/work-log/{id}` | Update entry |
+| DELETE | `/api/work-log/{id}` | Delete entry |
-### 인수인계
+### Handover
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/handover?project_path=...` | 프로젝트별 인수인계 요약 |
-| GET | `/api/handover/projects` | 프로젝트 목록 |
-| GET | `/api/handover/project-stats?project_path=...` | 프로젝트 통계 |
+| GET | `/api/handover?project_path=...` | Project handover summary |
+| GET | `/api/handover/projects` | List projects |
+| GET | `/api/handover/project-stats?project_path=...` | Project stats |
-### 지식 카테고리
+### Knowledge Categories
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/knowledge/categories` | 카테고리 목록 |
-| POST | `/api/knowledge/category` | 카테고리 생성 |
-| PUT | `/api/knowledge/category/{name}` | 카테고리 수정 |
-| DELETE | `/api/knowledge/category/{name}` | 카테고리 삭제 |
-| POST | `/api/knowledge/category/{name}/nodes` | 노드 추가 |
-| PUT | `/api/knowledge/category/{name}/nodes/{idx}` | 노드 수정 |
-| DELETE | `/api/knowledge/category/{name}/nodes/{idx}` | 노드 삭제 |
+| GET | `/api/knowledge/categories` | List categories |
+| POST | `/api/knowledge/category` | Create category |
+| PUT | `/api/knowledge/category/{name}` | Update category |
+| DELETE | `/api/knowledge/category/{name}` | Delete category |
+| POST | `/api/knowledge/category/{name}/nodes` | Add node |
+| PUT | `/api/knowledge/category/{name}/nodes/{idx}` | Update node |
+| DELETE | `/api/knowledge/category/{name}/nodes/{idx}` | Delete node |
-### 지식 트리 (노드 기반)
+### Knowledge Tree (Node-based)
 | Method | Path | Description |
 |--------|------|-------------|
-| POST | `/api/node` | 지식 노드 생성 |
-| PUT | `/api/node/{id}` | 지식 노드 수정 |
-| DELETE | `/api/node/{id}` | 지식 노드 삭제 |
+| POST | `/api/node` | Create knowledge node |
+| PUT | `/api/node/{id}` | Update knowledge node |
+| DELETE | `/api/node/{id}` | Delete knowledge node |
 ## Development Workflow

package/README.md CHANGED Viewed

@@ -1,336 +1,373 @@
-# HITS - Hybrid Intel Trace System
+# hits
-> AI를 가장 적게 쓰면서, 전임자의 뇌를 가장 완벽하게 복제하는 시스템
+> Replicate your predecessor's brain as perfectly as possible, using the least amount of AI.
-## 개요
+A secure web-based knowledge management system that preserves organizational context across AI tool sessions. When your Claude session hits the token limit and you switch to a new one — HITS ensures nothing is lost.
-HITS는 기업의 핵심 지식과 의사결정 맥락을 보존하기 위한 하이브리드 지식 관리 시스템입니다. AI 도구 간(Claude, OpenCode, Cursor 등) 세션 전환 시 프로젝트별 인수인계를 자동화합니다.
+## What Problem Does This Solve?
-### 핵심 가치
+You're working on a project with Claude Code. After a long session, you hit the token limit. A new session starts — but it has **no idea** what you did, what decisions were made, or what was left unfinished.
-- **토큰 최적화**: AI 비용 절감을 위한 시멘틱 압축과 온디맨드 분석
-- **맥락 보존**: Why-How-What 계층 구조로 의사결정 과정 저장
-- **실패 경험**: Negative Path로 실패한 접근법도 함께 기록
-- **보안 강화**: Argon2id 해싱, JWT HttpOnly 쿠키, CSP, Rate Limiting
-- **AI 세션 인수인계**: 토큰 한계로 AI 교체 시 프로젝트별 컨텍스트 자동 전달
-- **중앙 집중 저장**: `~/.hits/data/`에 모든 AI 도구의 작업 기록이 통합 저장
-- **프로젝트별 격리**: 프로젝트 경로 기반으로 완전히 독립된 컨텍스트 관리
+**HITS fixes this:**
-## 기술 스택
+1. **Record work** during each AI session (manually or via MCP tools)
+2. **Query handover** when a new session starts — it gets the full context
+3. **Knowledge trees** preserve the WHY/HOW/WHAT of every project
+4. **All AI tools share the same data** — Claude, OpenCode, Cursor, it doesn't matter
-| 영역 | 기술 |
-|------|------|
-| **백엔드** | Python 3.10+, FastAPI, Pydantic v2 |
-| **프론트엔드** | Svelte 5, Vite, TypeScript |
-| **인증** | Argon2id (비밀번호), JWT HS256 (HttpOnly 쿠키) |
-| **저장소** | 파일 기반 (`~/.hits/data/`), Redis (선택) |
-| **보안** | CSP, CORS, Rate Limiting, Secure Headers |
-## 설치
-### 요구사항
-- Python 3.10 이상
-- Node.js 18+ (프론트엔드 빌드용)
-- Redis (선택사항, 없으면 파일 저장소 사용)
-### 빠른 시작
-```bash
-cd hits
-./run.sh          # 자동 설치 + 서버 시작
 ```
-#### 개발 모드
-```bash
-./run.sh --dev    # Vite HMR + FastAPI 백엔드
+[OpenCode session ends]              [Claude session starts]
+        │                                    │
+   Record work:                          Query handover:
+   "Added JWT auth,                      → Previous: Added JWT auth
+    chose Argon2id over                     → Decisions: Argon2id > bcrypt
+    bcrypt, still need to                    → Pending: rate limiting
+    add rate limiting"                       → Files: auth/manager.py, ...
 ```
-#### 수동 설치
+## Quick Start
-```bash
-# Python 환경
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-# 프론트엔드 빌드
-cd hits_web
-npm install
-npm run build
-cd ..
+### One Command — That's It
-# 서버 실행
-python -m hits_core.main --port 8765
+```bash
+npx hits
 ```
-## 보안
+That single command will:
-### 인증 시스템
+1. **Detect Python 3.10+** on your system
+2. **Create a virtual environment** automatically
+3. **Install Python dependencies** (FastAPI, Argon2id, etc.)
+4. **Start the Python backend** (FastAPI on port 8765)
+5. **Start the web server** (Express on port 8765)
+6. Open **http://127.0.0.1:8765** in your browser
-| 기능 | 구현 |
-|------|------|
-| **비밀번호 해싱** | Argon2id (memory=64MB, iterations=3, parallelism=1) |
-| **비밀번호 최소 길이** | 8자 |
-| **JWT 토큰** | HttpOnly + Secure + SameSite=Lax 쿠키 |
-| **액세스 토큰** | 15분 만료 |
-| **리프레시 토큰** | 7일 만료, `/api/auth/refresh` 경로에서만 전송 |
-| **첫 사용자** | 자동으로 admin 역할 부여 |
-| **이후 사용자** | admin만 생성 가능 |
+### First Time Setup
-### 보안 헤더
+On first visit, you'll create an admin account:
 ```
-Content-Security-Policy: default-src 'self'; script-src 'self'; ...
-X-Content-Type-Options: nosniff
-X-Frame-Options: DENY
-Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
-Referrer-Policy: strict-origin-when-cross-origin
-Permissions-Policy: camera=(), microphone=(), geolocation=()
+┌──────────────────────────────────────┐
+│         🌳 HITS                      │
+│    Hybrid Intel Trace System         │
+│                                      │
+│  ┌────────────────────────────────┐  │
+│  │  Username: [____________]      │  │
+│  │  Password: [____________]      │  │
+│  │                                │  │
+│  │  [ Create Account ]            │  │
+│  │                                │  │
+│  │  First account = admin role    │  │
+│  └────────────────────────────────┘  │
+└──────────────────────────────────────┘
 ```
-### Rate Limiting
+### Custom Port
-- 로그인 엔드포인트: 10회/분 (IP 기준)
-- 429 Too Many Requests 응답으로 제한
+```bash
+npx hits --port 9000
+# or
+HITS_PORT=9000 npx hits
+```
-### 데이터 보호
+## Requirements
-| 항목 | 권한 | 설명 |
-|------|------|------|
-| `~/.hits/.auth/users.json` | 600 | 사용자 데이터 (소유자만) |
-| `~/.hits/.pepper` | 600 | HMAC 페퍼 (소유자만) |
-| `~/.hits/.jwt_secret` | 600 | JWT 서명 키 (소유자만) |
-| `~/.hits/.auth/` | 700 | 인증 디렉토리 (소유자만) |
+| Requirement | Version | Why |
+|-------------|---------|-----|
+| **Node.js** | ≥ 18 | Runs the web server and manages the Python process |
+| **Python** | ≥ 3.10 | Runs the FastAPI backend (auto-installed into venv) |
-## 웹 UI
+That's it. No database required — HITS uses file-based storage at `~/.hits/data/`.
-### 화면 구성
+## What You Get
+### Web UI
 ```
 ┌─────────────┬───────────────────────────────────┐
-│  사이드바    │  헤더 (탭 + 사용자 메뉴)            │
+│  Sidebar    │  Header (tabs + user menu 🌐 lang) │
 │             ├───────────────────────────────────┤
-│  📂 프로젝트 │                                   │
-│  ────────── │  메인 컨텐츠 영역                   │
+│  📂 Projects│                                   │
+│  ────────── │  Main content area                 │
 │  /project-a │                                   │
-│  /project-b │  📋 지식 트리 | 📝 타임라인 | 🔄 인수인계 │
+│  /project-b │  📋 Knowledge | 📝 Timeline | 🔄 Handover │
 │  /project-c │                                   │
 │             │                                   │
 └─────────────┴───────────────────────────────────┘
 ```
-### 주요 기능
+**Knowledge Tree** — Organize project knowledge as Why-How-What nodes:
-- **지식 트리**: 카테고리별 Why-How-What 노드 관리 (CRUD)
-- **타임라인**: 프로젝트별 작업 기록, 날짜별 그룹핑, 검색
-- **인수인계**: 프로젝트 선택 시 자동 생성된 인수인계 요약
-- **프로젝트 전환**: 사이드바에서 프로젝트 선택으로 즉시 전환
-- **사용자 관리**: 비밀번호 변경, 로그아웃
+```
+📁 Authentication
+  ├── WHY  "Need secure user auth for web UI"
+  ├── HOW  "Argon2id hashing + JWT HttpOnly cookies"
+  └── WHAT "POST /api/auth/login → Set-Cookie"
+      └── ❌ Negative Path: "Tried bcrypt first — too fast, GPU-vulnerable"
+```
-## AI 세션 인수인계
+**Timeline** — Chronological work log, grouped by date, filterable by project
-### 작동 방식
+**Handover** — Auto-generated summary of a project's context, ready to paste into a new AI session
-```
-[OpenCode 세션]                    [Claude 세션]
-      │                                  │
-  작업 수행                           세션 시작
-      │                                  │
-  작업 기록 ──────────────────────→ 인수인계 조회
-  POST /api/work-log               GET /api/handover
-  project_path: /my-project        project_path: /my-project
-      │                                  │
-      └──→ ~/.hits/data/ ←──┘            │
-           (중앙 집중)              이전 컨텍스트 파악
-                                         │
-                                    작업 이어서 수행
-```
+**i18n** — Korean/English toggle (🌐 button in header)
-### MCP 설정
+### MCP Tools for AI Assistants
-OpenCode 또는 Claude의 MCP 설정에 추가:
+HITS includes an MCP server so your AI can read and write handover data directly:
+#### Register with OpenCode (`~/.config/opencode/opencode.json`)
 ```json
 {
-  "hits": {
-    "type": "local",
-    "command": ["python", "-m", "hits_core.mcp.server"],
-    "cwd": "/path/to/hits"
+  "mcp": {
+    "hits": {
+      "type": "local",
+      "command": ["python", "-m", "hits_core.mcp.server"],
+      "cwd": "/path/to/hits"
+    }
   }
 }
 ```
-MCP 툴:
-- `hits_record_work`: 작업 기록
-- `hits_get_handover`: 인수인계 요약
-- `hits_search_works`: 작업 검색
-- `hits_list_projects`: 프로젝트 목록
-- `hits_get_recent`: 최근 작업
+#### Register with Claude Code
-## API 엔드포인트
+```bash
+claude mcp add hits \
+  -e HITS_DATA_PATH="$HOME/.hits/data" \
+  -- python -m hits_core.mcp.server
+```
-### 인증
+#### 5 MCP Tools
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/auth/status` | 인증 상태 확인 |
-| POST | `/api/auth/register` | 사용자 등록 |
-| POST | `/api/auth/login` | 로그인 (HttpOnly 쿠키 설정) |
-| POST | `/api/auth/logout` | 로그아웃 |
-| POST | `/api/auth/refresh` | 액세스 토큰 갱신 |
-| GET | `/api/auth/me` | 현재 사용자 정보 |
-| PUT | `/api/auth/password` | 비밀번호 변경 |
+| Tool | What It Does |
+|------|-------------|
+| `hits_record_work` | Record a work entry (auto-detects project path from CWD) |
+| `hits_get_handover` | Get handover summary for the current project |
+| `hits_search_works` | Search past work by keyword |
+| `hits_list_projects` | List all projects with recorded work |
+| `hits_get_recent` | Get the most recent work entries |
-### 작업 기록
+#### Example AI Workflow
-| Method | Path | Description |
-|--------|------|-------------|
-| POST | `/api/work-log` | 작업 기록 생성 |
-| GET | `/api/work-logs` | 작업 목록 (`project_path` 필터) |
-| GET | `/api/work-logs/search?q=...` | 작업 검색 |
-| GET | `/api/work-log/{id}` | 단건 조회 |
-| PUT | `/api/work-log/{id}` | 수정 |
-| DELETE | `/api/work-log/{id}` | 삭제 |
+```
+User: "Continue working on the auth system"
-### 인수인계
+AI (auto-calls hits_get_handover):
+  → Previous session added Argon2id password hashing
+  → Decisions: Argon2id (not bcrypt), JWT HS256, HttpOnly cookies
+  → Pending: Rate limiting, password change endpoint
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/handover?project_path=...` | 프로젝트별 인수인계 요약 |
-| GET | `/api/handover/projects` | 프로젝트 목록 |
-| GET | `/api/handover/project-stats?project_path=...` | 프로젝트 통계 |
+AI: "I see the auth system uses Argon2id + JWT. Let me add rate limiting..."
-### 지식 카테고리
+(later)
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/api/knowledge/categories` | 카테고리 목록 |
-| POST | `/api/knowledge/category` | 카테고리 생성 |
-| PUT | `/api/knowledge/category/{name}` | 카테고리 수정 |
-| DELETE | `/api/knowledge/category/{name}` | 카테고리 삭제 |
-| POST | `/api/knowledge/category/{name}/nodes` | 노드 추가 |
-| PUT | `/api/knowledge/category/{name}/nodes/{idx}` | 노드 수정 |
-| DELETE | `/api/knowledge/category/{name}/nodes/{idx}` | 노드 삭제 |
+AI (auto-calls hits_record_work):
+  → Recorded: "Added rate limiting (10 req/min on login endpoint)"
+```
+### REST API
+All features are also accessible via HTTP API:
+```bash
+# Health check
+curl http://localhost:8765/api/health
+# Record work
+curl -X POST http://localhost:8765/api/work-log \
+  -H "Content-Type: application/json" \
+  -b cookies.txt \
+  -d '{
+    "performed_by": "claude",
+    "request_text": "Added rate limiting to login endpoint",
+    "context": "10 req/min per IP, 429 response on limit",
+    "project_path": "/home/user/my-project",
+    "tags": ["security", "api"]
+  }'
+# Get handover summary
+curl "http://localhost:8765/api/handover?project_path=/home/user/my-project" \
+  -b cookies.txt
+# Search past work
+curl "http://localhost:8765/api/work-logs/search?q=auth" \
+  -b cookies.txt
+```
+## Security
-### performed_by 규칙
+HITS is built with security as a first-class concern:
-| AI 도구 | 값 |
-|---------|-----|
-| OpenCode | `opencode` |
-| Claude Code | `claude` |
-| Cursor | `cursor` |
-| 사용자 직접 | `manual` |
+| Feature | Implementation |
+|---------|---------------|
+| **Password Hashing** | Argon2id (64MB memory, 3 iterations, parallelism=1) |
+| **JWT Tokens** | HttpOnly + Secure + SameSite=Lax cookies |
+| **Access Token** | 15-minute expiry |
+| **Refresh Token** | 7-day expiry, restricted to `/api/auth/refresh` path |
+| **Brute Force Protection** | 10 login attempts/minute per IP |
+| **Security Headers** | CSP, X-Frame-Options: DENY, HSTS preload, nosniff |
+| **Data Protection** | Auth files stored with `chmod 600` (owner-only) |
+| **First User Policy** | First registered user becomes admin; subsequent users need admin approval |
-## 아키텍처
+## How It Works Under the Hood
 ```
-┌──────────────────────────────────────────────────────────┐
-│                   hits_web (Svelte 5 + Vite)              │
-│              Material Dark 테마 · TypeScript               │
-│  ┌──────────┬──────────┬──────────────────────────┐       │
-│  │ Sidebar  │ Knowledge│ HandoverPanel            │       │
-│  │ Projects │ Tree     │ 인수인계 요약 뷰          │       │
-│  │ Filter   │ Timeline │                          │       │
-│  └──────────┴──────────┴──────────────────────────┘       │
-│         ↕ API Client (fetch + HttpOnly cookies)           │
-├──────────────────────────────────────────────────────────┤
-│                   hits_core (Apache 2.0)                  │
-│  ┌──────────┬──────────┬──────────┬──────────┐           │
-│  │  Models  │ Storage  │    AI    │ Auth     │           │
-│  │  Tree    │ Redis    │ Compress │ Argon2id │           │
-│  │  Node    │ File     │ SLM/LLM  │ JWT      │           │
-│  │  WorkLog │(~/.hits) │ Filter   │ Middleware│           │
-│  └──────────┴──────────┴──────────┴──────────┘           │
-│  ┌──────────┬──────────┬──────────┐                      │
-│  │  API     │ Collector│   MCP    │                      │
-│  │ FastAPI  │ Git/Shell│ Server   │                      │
-│  │ + Static │ AI Sess. │ 5 Tools  │                      │
-│  │  Serve   │          │          │                      │
-│  └──────────┴──────────┴──────────┘                      │
-│  ┌──────────────────────────────┐                        │
-│  │       Service Layer          │                        │
-│  │  TreeService  HandoverService│                        │
-│  │  KnowledgeService            │                        │
-│  └──────────────────────────────┘                        │
-└──────────────────────────────────────────────────────────┘
+npx hits
+  │
+  ├── 1. findPython()       → Detect Python 3.10+ on system
+  ├── 2. setupPython()      → Create venv, install deps
+  ├── 3. startBackend()     → Spawn FastAPI process (port 8765)
+  └── 4. startExpress()     → Serve frontend + proxy /api → FastAPI
+  Browser                    Express (8765)           FastAPI (8765 internal)
+     │                           │                         │
+     ├── GET /             ───→  static (Svelte SPA)       │
+     ├── GET /some/route   ───→  SPA fallback              │
+     └── GET /api/*        ───→  proxy  ──────────────→   FastAPI routes
+         POST /api/*       ───→  proxy  ──────────────→   FastAPI routes
 ```
-## 지식 트리 구조
+All data is stored centrally:
+```
+~/.hits/
+├── data/                ← All project data
+│   ├── work_logs/       ← AI session work logs (JSON)
+│   ├── trees/           ← Knowledge trees
+│   └── workflows/       ← Workflows
+├── .auth/               ← User accounts (chmod 700)
+│   └── users.json       ← User data (chmod 600)
+├── .pepper              ← HMAC pepper (chmod 600)
+└── .jwt_secret          ← JWT signing key (chmod 600)
+Override with HITS_DATA_PATH environment variable
+```
-### Why-How-What 계층
+## CLI Options
 ```
-├── WHY (의도/목적)
-│   ├── "왜 이 시스템을 만들었나?"
-│   └── "비즈니스 목표가 무엇인가?"
-│
-├── HOW (논리/방법)
-│   ├── "어떻게 구현했나?"
-│   └── "어떤 의사결정을 내렸나?"
-│
-└── WHAT (실행/작업)
-    ├── "구체적으로 무엇을 하나?"
-    └── "실행 가능한 액션"
+npx hits [options]
+Options:
+  -p, --port <port>   Server port (default: 8765)
+  -d, --dev           Development mode (verbose logging)
+  -s, --setup         Install dependencies only, don't start
+  -h, --help          Show help
+Environment:
+  HITS_PORT           Server port override
+  HITS_PYTHON         Path to python executable (default: auto-detect)
+  HITS_DATA_PATH      Data storage path (default: ~/.hits/data)
 ```
-## 개발
+## API Reference
+### Authentication
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/auth/status` | Check if auth is initialized, current login status |
+| POST | `/api/auth/register` | Register user (first user = admin) |
+| POST | `/api/auth/login` | Login — sets HttpOnly cookies |
+| POST | `/api/auth/logout` | Logout — clears cookies |
+| POST | `/api/auth/refresh` | Refresh access token |
+| GET | `/api/auth/me` | Get current user info |
+| PUT | `/api/auth/password` | Change password |
+### Work Logs
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/api/work-log` | Create work log |
+| GET | `/api/work-logs` | List logs (filter by `project_path`) |
+| GET | `/api/work-logs/search?q=...` | Search logs by keyword |
+| GET | `/api/work-log/{id}` | Get single entry |
+| PUT | `/api/work-log/{id}` | Update entry |
+| DELETE | `/api/work-log/{id}` | Delete entry |
+### Handover
-### 개발 모드
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/handover?project_path=...` | Get project handover summary |
+| GET | `/api/handover/projects` | List all projects |
+| GET | `/api/handover/project-stats?project_path=...` | Get project statistics |
+### Knowledge
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/knowledge/categories` | List categories |
+| POST | `/api/knowledge/category` | Create category |
+| PUT | `/api/knowledge/category/{name}` | Update category |
+| DELETE | `/api/knowledge/category/{name}` | Delete category |
+| POST | `/api/knowledge/category/{name}/nodes` | Add node to category |
+| PUT | `/api/knowledge/category/{name}/nodes/{idx}` | Update node |
+| DELETE | `/api/knowledge/category/{name}/nodes/{idx}` | Delete node |
+## Troubleshooting
+### "Python 3.10+ not found"
+Install Python 3.10 or later:
 ```bash
-./run.sh --dev    # Vite HMR + FastAPI
+# Ubuntu/Debian
+sudo apt install python3.12
+# macOS
+brew install python@3.12
+# Or set manually:
+export HITS_PYTHON=/usr/bin/python3.12
 ```
-### 테스트
+### "Frontend not built"
+This shouldn't happen with the npm package (frontend is pre-built). If it does:
 ```bash
-./run.sh --test   # pytest 실행
+npx hits --setup
 ```
-### 프론트엔드 개발
+### "ModuleNotFoundError: No module named 'hits_core'"
+Python dependencies failed to install. Try:
 ```bash
-cd hits_web
-npm install        # 의존성 설치
-npm run dev        # Vite 개발 서버 (http://localhost:5173)
-npm run build      # 프로덕션 빌드
+npx hits --setup
 ```
-## 라이선스
+### Redis Connection Failed
-| 패키지 | 라이선스 | 상업적 사용 |
-|--------|---------|-------------|
-| `hits_core` | Apache 2.0 | ✅ 자유로움 |
-| `hits_web` | Apache 2.0 | ✅ 자유로움 |
+Not a problem — HITS automatically uses file-based storage. Redis is optional.
-## 문제 해결
+## Development
-### Node.js가 없습니다
+If you're working on HITS itself:
 ```bash
-# Ubuntu/Debian
-curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
-sudo apt install -y nodejs
-```
+git clone https://github.com/lhjnano/hits.git
+cd hits
-### Redis 연결 실패
+# Backend setup
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
-Redis 없이도 HITS는 정상 작동합니다. 파일 기반 저장소를 자동으로 사용합니다.
+# Frontend build
+cd hits_web && npm install && npm run build && cd ..
-### 데이터가 어디에 저장되나요?
+# Development mode (Vite HMR + FastAPI)
+./run.sh --dev
+# Run tests
+./run.sh --test
 ```
-~/.hits/
-├── data/                ← 모든 데이터의 기본 위치
-│   ├── work_logs/       ← AI 세션 작업 기록
-│   ├── trees/           ← 지식 트리
-│   └── workflows/       ← 워크플로우
-├── .auth/               ← 인증 데이터
-│   └── users.json       ← 사용자 정보 (권한 600)
-├── .pepper              ← HMAC 페퍼 (권한 600)
-└── .jwt_secret          ← JWT 서명 키 (권한 600)
-HITS_DATA_PATH 환경변수로 경로 변경 가능
-```
+## License
+Apache 2.0 — free for commercial use.
+## Links
+- **GitHub**: [https://github.com/lhjnano/hits](https://github.com/lhjnano/hits)
+- **Issues**: [https://github.com/lhjnano/hits/issues](https://github.com/lhjnano/hits/issues)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@purpleraven/hits",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "HITS - Hybrid Intel Trace System. AI session handover with secure web UI.",
   "keywords": [
     "knowledge-management",