# AGENTS.md — habraid

> Codex 에이전트를 위한 프로젝트 지도. 상세한 내용은 docs/ 참조.

## 작업 시작 전 필수 읽기

1. `docs/specs/host-following-llm.md` (해당 변경 작업일 때)
2. `docs/architecture.md`
3. `docs/config-reference.md`
4. 관련 `PLAN*.md`

## 작업 규칙

- 구현 전에 관련 `docs/specs/*.md`를 먼저 읽고, 없으면 먼저 spec부터 작성한다.
- 프롬프트/요구사항 정리는 `Goal / Context / Constraints / Done when` 구조를 우선한다.
- 큰 변경은 탐색 → 설계 → 구현 → 검증 순서로 진행한다.
- HaBraid는 memory backend를 wiki 표현층으로 바꾸는 orchestration layer다.
- 모델 선택은 기본적으로 host가 담당하고, habraid는 host-following을 기본값으로 지향한다.
- standalone LLM backend는 fallback/독립 실행 용도로만 유지한다.

## 프로젝트 개요

**habraid**: Obsidian 마크다운 위키 엔진. 지식 아이템을 수집/검색/위키화.
MemPalace가 있으면 연동하고, 없어도 자체 SQLite DB로 완전 동작.

## 빠른 시작

```bash
npm install
npx tsx src/index.ts --help     # 실행
npx tsx src/index.ts init       # 볼트 초기화
npx tsx src/index.ts sync       # 전체 동기화
```

## 아키텍처

```
src/
├── index.ts          # CLI 진입점 (commander)
├── mcp-server.ts     # MCP 서버 (stdio)
├── types.ts          # 공통 타입
├── config.ts         # 설정 로드 (JSON)
├── errors.ts         # 커스텀 에러
├── utils.ts          # 유틸
├── db/
│   ├── database.ts   # SQLite 연결 + 마이그레이션
│   ├── items.ts      # items CRUD + FTS5 검색
│   └── kg.ts         # Knowledge Graph
├── sources/
│   ├── adapter.ts    # SourceAdapter 인터페이스
│   ├── mempalace.ts  # MemPalace 연동 (선택)
│   └── manual.ts     # 직접 추가
├── vault/
│   ├── init.ts       # 볼트 디렉토리 + SCHEMA.md 생성
│   ├── render.ts     # 아이템 → 마크다운 렌더링
│   ├── index.ts      # index.md 갱신
│   └── log.ts        # log.md 갱신
├── wiki/
│   ├── generator.ts  # 위키 생성 오케스트레이터
│   ├── llm.ts        # z.ai API 클라이언트 (OpenAI 호환)
│   └── prompts.ts    # 시스템 프롬프트
├── sync/
│   ├── git.ts        # git pull/push (simple-git)
│   └── pipeline.ts   # 전체 sync 파이프라인
└── cli/
    └── commands.ts   # CLI 명령어 정의
```

## 핵심 규칙

### 코딩 규칙
- TypeScript strict mode, ES2022 target, Node16 module resolution
- 모든 함수와 클래스에 JSDoc 주석
- 에러는 커스텀 에러 클래스로 래핑 (src/errors.ts)
- async 함수는 항상 try/catch로 감싸기
- 파일 경로는 항상 path.join() / path.resolve() 사용

### 볼트 규칙
- raw/ 아래 파일은 **절대 수정하지 않음** (불변)
- 모든 마크다운은 YAML frontmatter 포함
- Obsidian 호환: 백링크 `[[]]`, frontmatter `---`
- 한국어 본문, 코드/경로는 영어 원문 유지

### MemPalace 연동 (선택)
- `mempalace.enabled: true` + 경로 존재 시에만 활성화
- 없으면 자체 SQLite DB로 동작
- ChromaDB 직접 접근하지 않음 (Python 스크립트나 MCP 경유)

### Git
- 커밋 메시지: `type: description` (conventional commits)
- 볼트 변경 후 항상 index.md 갱신

## 의존성

| 패키지 | 용도 |
|--------|------|
| commander | CLI 프레임워크 |
| gray-matter | YAML frontmatter 파싱 |
| better-sqlite3 | 자체 DB + MemPalace DB 읽기 |
| simple-git | Git 조작 |
| chalk | 터미널 색상 |
| ora | 스피너 |
| @modelcontextprotocol/sdk | MCP 서버 |
| zod | MCP 툴 스키마 |

## MCP 툴

| 툴 | 설명 |
|----|------|
| `hw_status` | 볼트 + DB 통계 |
| `hw_ingest` | 소스 → raw/ 수집 (MemPalace + 기타) |
| `hw_add` | 아이템 직접 추가 |
| `hw_search` | FTS5 키워드 검색 |
| `hw_generate` | raw/ → wiki/ LLM 생성 |
| `hw_sync` | 전체 파이프라인 |
| `hw_read` | vault 내 파일 읽기 |
| `hw_lint` | 정합성 검사 |
| `hw_graph` | KG 쿼리 |

## 설정

기본 경로: `~/.habraid/data/config.json`
레거시 fallback: `~/.config/habraid/config.json`

## 상세 문서

- `docs/architecture.md` — 전체 아키텍처 설계
- `docs/vault-schema.md` — 볼트 디렉토리/파일 스키마
- `docs/wiki-generation.md` — 위키 생성 프롬프트 전략
- `docs/config-reference.md` — 설정 파일 레퍼런스
- `PLAN.md` — v1 기획서
- `PLAN-v2.md` — v2 독립 아키텍처 기획서