일반 검색과 선택형 로컬 인덱스

	일반(기본)	고급: 로컬 인덱스(선택)
하는 일	호출할 때마다 .fig를 읽어 search, find, inspect, export에 답합니다.	선택한 범위의 검색 인덱스를 한 번 만들고, 이후 search는 그 인덱스로 소스 전체를 함께 순위 매겨 답합니다.
기록되는 것	workspace도 인덱스 데이터베이스도 만들지 않습니다(export는 요청한 파일만 씁니다).	사용자별 state 디렉터리 또는 선택한 --storage 아래의 로컬 workspace(SQLite 데이터베이스).
쓰는 때	일회성 질문, 스크립트, CI.	한 파일을 반복 검색할 때, 프로젝트의 여러 파일을 하나의 코퍼스로 검색할 때(--workspace <dir>), 컴포넌트, 변수, 스타일, 이미지의 정확한 사용처를 찾을 때.

일반적인 디자인 질문은 인덱스를 만들지 않습니다. 한 번 명시적으로 켭니다("이 디자인의 인덱스를 만들어 줘"). 저장 위치는 figlens가 고르며 SQLite 등 별도 설정은 필요 없습니다.

# 일반: 상태 없음, 아무것도 만들지 않음
figlens search design.fig "checkout button"

# 고급, 한 번만: 범위(노드 id, 파일 전체는 0:0) 선택; 빌드는 포그라운드로 실행
figlens index prepare design.fig --scope 0:0

# 인덱스 검색; 인덱스 범위가 파일 전체가 아니면 --node 추가
figlens search --file design.fig "checkout button" --node 0:0

# .fig를 수정하거나 다시 내보낸 뒤: 바이트가 바뀐 범위만 다시 빌드
figlens index refresh --file design.fig

# .fig를 옮긴 뒤: workspace를 유지하고 refresh (prepare가 출력한 workspaceId 사용)
figlens index relocate <sourceId> new/design.fig --id <workspaceId>
figlens index refresh --id <workspaceId>

MCP: index prepare는 job을 반환합니다. succeeded가 될 때까지 jobs를 조회한 뒤 응답의 workspaceId로 검색합니다.

{"tool": "index", "arguments": {"action": "prepare", "file": "/abs/path/design.fig", "scope": "0:0"}}
{"tool": "jobs", "arguments": {"action": "status", "jobId": "<jobId from the reply>"}}
{"tool": "search", "arguments": {"workspaceId": "<workspaceId from the reply>", "node": "0:0", "query": "checkout button"}}

수명 주기: refresh는 .fig 바이트가 바뀐 범위만 다시 빌드하고, rebuild는 바뀌지 않았어도 다시 빌드합니다. clear_cache는 빌드로 다시 만들 수 있는 데이터만 지우며 레지스트리와 게시된 인덱스는 유지합니다. reset은 이 workspace의 데이터베이스를 지우며(.fig와 내보내기는 건드리지 않음) 명시적으로 요청했을 때만 실행됩니다. 새 소스, 더 넓은 범위, reset, 재생성은 각각 별도의 명시적 요청이 필요합니다.

.fig를 옮겼나요? index relocate는 workspaceId, sourceId, 저장 위치를 유지합니다. 이후 영향받은 범위를 refresh하세요. 자동 탐색이나 해시 기반 자동 병합은 없으며 reset은 필요 없습니다.

한 폴더에 디자인이 여러 개인가요? index add <dir> --workspace DIR는 그 디렉터리 아래의 .fig 파일을 한 번에 최대 10개 등록하고, 디렉터리 밖으로 나가는 링크는 건너뜁니다. 응답에는 added, existing, skipped, truncated가 있으며, 반복해도 아무것도 추가되지 않고 각 파일에는 여전히 자체 prepare --scope가 필요합니다. 폴더 안에서 옮긴 파일은 relocate를 쓰지 않으면 새 소스가 됩니다. 응답의 nextCursor를 --cursor C(MCP cursor)로 넘기면 다음 10개를 추가합니다. 페이지 검색과 라이브러리 커서는 한 시간 동안 유효하며, 이후에는 cursor_expired를 반환하므로 다시 검색하세요.

데이터: SQLite 데이터베이스에는 등록된 로컬 경로, 선택한 범위의 레이어 이름과 유효 텍스트, 인스턴스의 컴포넌트 속성 값, 검색 postings, 정확한 관계(포함, 인스턴스, 변형, 변수/스타일/이미지 바인딩, 프로토타입 대상)와 그 대상 정의, 해시, 세대, job이 들어 있습니다. 원본 .fig는 제자리에서 변경되지 않으며, 원시 바이트는 데이터베이스에 저장되지 않습니다. 시맨틱·비전 모델 레이어는 임베딩한 벡터를, 활성화한 시각 인덱싱은 모델이 없어도 인덱싱된 레이어의 PNG 렌더링을 추가합니다. 쿼리 이미지는 저장하지 않습니다.

Pi, OpenCode, OMP는 각자의 opt-in 진입점으로 같은 인덱스를 쓰며, workspace는 재시작과 호스트를 넘어 재사용됩니다. 미구현: 파일 이벤트(watch는 파일을 폴링하며, holder가 실행 중일 때만 동작)와 푸시 이벤트.