---
name: kuma:vault
description: "Kuma Vault SSoT retrieval. Trigger on 새 작업/플랜, vault-backed 도메인/프로젝트 키워드, domains/* edits, previous-context recall, decisions/6원칙. Modes: search/timeline/get/ingest/curate."
---

# /vault — Kuma Vault 지식 서빙

Vault에 저장된 도메인 지식을 로드하는 단일 인터페이스.

> **vault = 쿠마(나)의 뇌**. amnesiac 가정으로 동작 — vault 외에는 아무것도 기억 못 한다. semantic 지식 + working memory + episodic memory + procedural memory 모두 vault 에서 꺼낸다.

## Intent Router (literal "vault" keyword 보다 우선)

쿠마는 매 유저 메시지에 대해 literal `vault` keyword 가 아니라 **memory intent** 를 우선 인식한다. 다음 패턴이 보이면 즉시 vault retrieval chain 을 돌린다 — 디스코드 히스토리부터 fetch 하지 않는다.

### 트리거 패턴

**A. memory-recall (이전 컨텍스트 복원)**
- "지금 뭐 하던 중이지?", "어디까지 했지?", "이전 결정", "지난번"
- "그 작업", "그 워커", "그 프로젝트" (deictic reference)
- "노을이/뚝딱이/다람이/하울 등 워커 이름" + 상태 질문
- "디코 thread 어디", "메시지 어디"
- 컨텍스트 끊긴 직후 재개 ("세션 끊겼다", "다시 시작")

**B. domain-keyword (작업 시작 / 신규 토픽 진입)** — context7 식 description-match 트리거. 사용자 메시지·편집 파일·plan 본문에 vault 페이지가 존재하는 토픽 키워드가 등장하면 즉시 해당 페이지 로드.
- **토픽 enumeration 은 본 SKILL.md 에 박지 않는다.** 어떤 토픽이 vault 에 있는지는 *runtime* 에 `~/.kuma/vault/index.md` + `~/.kuma/vault/domains/<category>/` + `~/.kuma/vault/projects/` 트리에서 직접 확인한다. 이유: (a) public skill 본문에 vault 토픽을 박으면 private vault repo 의 도메인·프로젝트 목록이 public repo 로 새고, (b) vault 가 추가될 때마다 skill 을 같이 갱신해야 하는 drift 가 생긴다.
- 매핑 alias 가 있으면 `/kuma:vault <alias>`, 없으면 `/kuma:vault get domains/<category>/<file>.md` 또는 `/kuma:vault get projects/<slug>.md`.
- 비-trivial 작업 시작 단계에서 vault 진입은 *권장이 아니라 의무* (CLAUDE.md Vault-first 룰). 매칭은 LLM 이 vault tree 에서 직접 한다 — context7 이 라이브러리 doc 매칭을 description-shape 로 하는 것과 같다.

**C. 결정·원칙 단서**
- `SSoT`, `SRP`, `atomicity`, `idempotency`, `consistency`, `silent fallback`, `failover`, 알렉스 6원칙/decisions 어휘 등장 → `~/.kuma/vault/decisions.md` + 현재 프로젝트 `projects/<slug>.project-decisions.md` + 관련 `operational-rules/<rule>.md` 우선 로드.

**D. plan 작성/갱신**
- 새 plan 작성 또는 기존 plan 갱신 turn → 작업 도메인 + `vault/projects/<slug>.md` (canonical project summary) + 관련 operational-rules 로드 후 plan 본문 작성.

### Retrieval Chain (Boot Pack Load Order — schema.md 기준)

1. `~/.kuma/vault/dispatch-log.md` **tail 20** — episodic ledger (`type: special/dispatch-log`)
2. `~/.kuma/vault/decisions.md` global + current project `projects/*.project-decisions.md` — 최신 entry 10 로드 (`type: special/decisions` / `special/project-decisions`, writer 는 `user-direct` 전용)
3. `${KUMA_PLANS_DIR:-./.kuma/plans}/index.md` Active — 큰 plan
4. Vault retrieval (on demand) — **3-layer progressive disclosure**: `/vault search <q>` (L1: hits-only 리스트) → `/vault timeline <q>` (L2: ±2줄 snippets) → `/vault get <id|path>` (L3: 전문)

상위에서 답이 나오면 하위 단계 skip. 4번까지 다 봐도 답 없으면 그제서야 디스코드 히스토리/Grep 등 외부 탐색.

**불변식:** L1 에서 전문 dump 금지. 순서 고정 `search → timeline → get`.

**우선순위 규칙:** 현재 canonical truth 가 필요한 질의에서는 `decisions.md` / `projects/*.project-decisions.md` → `calendar/` (시간·장소가 정해진 일정/행사/대회 질의일 때) → `projects/<slug>.md` → `memos/` → `learnings/` / `domains/` / `operational-rules/` → `results/` / `raw/` 순으로 본다. 결과 리포트와 dispatch log 는 증적/역사 계층이지 정책 SSOT 가 아니다.

### Anti-pattern
- ❌ literal "vault" keyword 가 없다고 vault 를 안 본다
- ❌ 디스코드 히스토리부터 fetch 한다
- ❌ Grep/Glob 로 직접 코드베이스 탐색한다 (vault 부터 보기)
- ❌ 검색 결과 전문을 바로 읽는다 (`/vault search` 후 바로 전체 본문 dump 기대 금지. 먼저 `search -> timeline -> get`)

## Special Files

`type: special/*` frontmatter 를 가진 runtime memory layer. 일반 vault page 와 다르게 writer/reader/trigger/retention 이 고정.

| 파일 | type | 역할 | Primary writer | Boot pack 로드 |
|------|------|------|----------------|----------------|
| `dispatch-log.md` | `special/dispatch-log` | episodic ledger (task 사건열) | `kuma-dispatch lifecycle hook` | tail 20 |
| `decisions.md` | `special/decisions` | global decision memory (유저 확정 결정 단일 레이어) | `user-direct` 전용 | 최신 entry 10 |
| `projects/<slug>.project-decisions.md` | `special/project-decisions` | 프로젝트별 실행/설계 결정 | `user-direct` 전용 (프로젝트 scope) | 현재 프로젝트 한정 로드 |

**decisions.md 단일 레이어 구조:**
- `## About` + `## Decisions` 두 섹션만 존재. Inbox / Ledger / Open Decisions 하위 섹션 없음.
- `## Decisions` 는 `- <resolved_text>` 한 줄씩만 쓴다. 날짜 / id / action / scope / context_ref 필드 없음.
- writer 는 항상 `user-direct`. detector/lifecycle/audit/noeuri 자동 append 경로 없음. 노을이는 후보를 제안할 수 있어도 canonical writer 가 아니다.
- AI 해석·요약·추론 금지. 유저가 말한 resolved text 그대로 저장.

## 사용법

```
/vault <domain>       해당 도메인 지식 전문 로드
/vault index          전체 페이지 목록 조회
/vault search <q>     키워드 검색 (L1)
/vault timeline <q>   매칭 라인 주변 스니펫 (L2)
/vault get <id>       특정 문서 전문 로드 (L3)
/vault ingest [args]  새 소스를 canonical vault page 로 승격
/vault curate [args]  기존 vault 의 고아 raw, 깨진 링크, 중복 page, drift 보수
```

## 서브커맨드

`ingest` / `curate` 는 이 스킬의 서브커맨드다. 상세 규칙/절차/불변식은 진입 시 해당 reference 파일을 Read 로 로드한다.

| 서브커맨드 | 상세 문서 | 요약 |
|------------|-----------|------|
| (없음) / domain / index / search / timeline / get | 이 파일 | 읽기·조회 경로 |
| `ingest` | `references/ingest.md` | 새 소스 승격 — archive-first, explicit canonical promotion |
| `curate` | `references/curate.md` | 기존 vault 정리 — broken link / orphan raw / duplicate page / drift |

**실행 규칙:**
- `/vault ingest ...` → `references/ingest.md` Read → 규칙대로 승격 절차 수행
- `/vault curate ...` → `references/curate.md` Read → 규칙대로 정리 절차 수행
- 읽기/조회 경로는 이 파일만 있으면 된다. reference 로딩 불필요.

### 예시

```
/vault security       → domains/security.md 로드
/vault analytics      → domains/analytics.md 로드
/vault image-gen      → domains/image-generation.md 로드
/vault content        → domains/content-pipeline.md 로드
/vault index          → index.md 전체 목록
/vault search vault   → 제목/path/짧은 snippet 목록
/vault timeline vault → 주변 라인 snippet 2~3개
/vault get domains/security.md → 해당 문서 전문
/vault ingest raw/memo.md      → 지식 승격 (references/ingest.md 기반)
/vault curate raw              → raw 고아 점검 (references/curate.md 기반)
```

## Vault 위치

```
~/.kuma/vault/
├── index.md              전체 페이지 목록 + 교차참조
├── schema.md             운영 규칙
├── decisions.md          결정 이력
├── dispatch-log.md       task 사건열
├── log.md                변경 이력 (append-only)
├── calendar/             시간·장소가 정해진 일정/행사/대회 event catalog
├── domains/              도메인별 지식 (security, analytics, image-gen 등)
├── projects/             얇은 canonical project summary
├── memos/                유저 즐겨찾기 메모 layer (read-only user-owned)
├── learnings/            벤치마크, 디버깅 패턴, 누적 관찰
├── operational-rules/    런타임 rule layer (반복 운영 규칙)
├── docs/                 모델 등 참고 문서
├── images/               이미지 아카이브
├── raw/                  원본 보존 archive (변경 금지)
├── inbox/                정리 대기 raw 데이터
└── results/              worker result / evidence archive
```

**slot contract:**
- `projects/<slug>.md` 는 chronicle 이 아니라 현재 상태 summary 다. 장문 history 와 result 본문은 `results/`에 둔다.
- `calendar/` 는 "오늘/내일/몇 시/어디/대회/행사" 같은 schedule recall 의 canonical slot 이다. Google Calendar 나 웹 검색보다 먼저 `calendar/index.md` 를 본다.
- `memos/` 는 메모 전용 canonical slot 이다. 결정이나 일반화 지식과 섞지 않고, background agent 는 read-only 로 취급한다.
- skill 문서는 repo source 가 SSOT 이다. vault 는 curated output 만 유지하고, skill → vault 자동 동기화는 하지 않는다.
- **첨부/이미지 동시 보존 의무** — 메모/플랜/learnings 등 vault page 저장 시 컨텍스트에 첨부 또는 paste 이미지가 있으면 `raw/<topic>-YYYY-MM-DD/` 에 함께 복사 + page 본문에 raw 절대 경로 명시. 텍스트 요약만 남기고 원본을 vault 밖에 두는 패턴 금지. 자세한 절차/path 매핑은 `kuma-panel` skill `Attachments / Images` 섹션 SSoT.

## 도메인 별칭 매핑

`vault <alias>` 로 직접 로드 가능한 별칭 (CLI `vault` 바이너리 기준):

| 별칭 | 파일 |
|------|------|
| `security`, `sec` | `domains/security.md` |
| `analytics`, `usage`, `insights` | `domains/analytics.md` |
| `image-gen`, `imagegen`, `image` | `domains/image-generation.md` |
| `content`, `content-pipeline`, `pipeline` | `domains/content-pipeline.md` |

그 외 `domains/` 하위 파일(예: `careers.md`, `autoresearch.md`, `fatch.md`, `kuma-picker.md` 등)은 별칭 없이 경로 직접 지정 또는 `/vault get domains/<file>.md` 로 접근한다.

## 도메인 로드는 명시 호출

페르소나는 작업 컨텍스트에 따라 필요할 때 `/vault <domain>` 으로 직접 도메인 페이지를 로드한다. 정적 role → vault 자동 매핑은 사용하지 않는다 (페르소나 모델이 정적 위계에서 동적 라우팅으로 이전됨, `kuma-studio/persona-doctrine-split.md` 참고).

자주 쓰이는 페르소나별 진입점 예시:
- 라우터(쭈니) — 라우팅 판단에 vault 거의 불필요. 잡담 라우팅 시 노을이에게 dispatch.
- 프로젝트 멤버(하울·뚝딱이·다람이 등) — 고정 역할 없이 dispatch 받은 작업 내용에 맞춰 관련 도메인(`security`, `analytics`, `image-generation` 등)을 케이스별로 호출.
- 노을이 — vault 큐레이터. `/vault search → timeline → get` 사이클 일상.

자동 매핑이 사라진 이유: 모델 발전으로 페르소나가 정적 role 에 묶이지 않고, GUI 동적 라우팅(후속 plan `gui-dynamic-routing.md`)에서 알렉스가 그때그때 책임을 지정한다.

## Context Router

평소 대화와 코딩 중 vault 가 자연스럽게 묻어나오는 기준은 `~/.kuma/vault/operational-rules/context-router.md` 가 SSoT 다. System prompt 에 긴 vault 본문을 넣지 않고, 해당 manifest 가 정한 trigger 별로 최대 1~3개 capsule 만 로드한다.

개인 말투·취향·프라이버시 capsule 은 `~/.kuma/vault/domains/personal/` 아래의 schema 문서가 소유한다. account/contact/real name/secret/token/password/민감정보는 `kuma-lesson` detector 가 canonical page 에 자동 승격하지 않고 proposed-only 후보로 남긴다.

router/capsule drift 는 `kuma-lesson router-check --project <project>` 로 검사한다. 결과는 `router-update` lesson 후보이며, 알렉스 승인 전 자동 수정하지 않는다.

## 실행 절차

`/vault <arg>` 호출 시:

1. **arg = `index`**: `~/.kuma/vault/index.md` 읽어서 목록 출력
2. **arg = `search <q>`**: 가벼운 index 결과만 확인. title / path / 1줄 snippet 위주.
3. **arg = `timeline <q>`**: 매칭 라인 주변 ±2줄 스니펫으로 중간 detail 확인.
4. **arg = `get <id|path>`**: 특정 문서를 지목했을 때만 전문 로드.
5. **arg = 도메인 이름/별칭**: 위 매핑 테이블에서 파일 경로 결정 → Read로 전문 로드
6. **arg 없음**: 사용법 출력

### 주의사항

- Vault 내용은 **읽기 전용**으로 취급 (수정은 vault-ingest를 통해서만)
- 대용량 파일은 요약 우선, 전문은 요청 시만
- 기본 retrieval 순서는 `search -> timeline -> get` 이다
- inbox/ 내용은 미검증 데이터 — 사실 확인 없이 인용 금지