Busca comum e o índice local opcional

	Comum (padrão)	Avançado: índice local (opcional)
O que faz	Lê o .fig a cada chamada e responde search, find, inspect e export.	Cria uma vez um índice de busca de um escopo escolhido e responde search a partir dele, com ranking entre fontes.
O que é gravado	Nenhum workspace nem banco de índice (export grava só os arquivos que você pedir).	Um workspace local (banco SQLite) no diretório de estado do usuário, ou no --storage escolhido.
Quando usar	Perguntas pontuais, scripts, CI.	Buscas repetidas em um arquivo; vários arquivos de um projeto como um único corpus (--workspace <dir>); usos exatos de componentes, variáveis, estilos e imagens.

Uma pergunta de design comum nunca cria um índice. Você ativa uma vez, de forma explícita ("crie um índice para este design"); o figlens escolhe o armazenamento e não exige SQLite nem outra configuração.

# Comum: sem estado, não cria nada
figlens search design.fig "checkout button"

# Avançado, uma vez: escolha um escopo (um id de nó, ou 0:0 para o arquivo inteiro); o build roda em primeiro plano
figlens index prepare design.fig --scope 0:0

# Busca indexada; adicione --node quando o escopo indexado não for o arquivo inteiro
figlens search --file design.fig "checkout button" --node 0:0

# Depois de editar ou reexportar o .fig: recrie só os escopos cujos bytes mudaram
figlens index refresh --file design.fig

# Depois de mover o .fig: mantenha o workspace e faça refresh (use o workspaceId impresso por prepare)
figlens index relocate <sourceId> new/design.fig --id <workspaceId>
figlens index refresh --id <workspaceId>

MCP: index prepare devolve um job; consulte jobs até succeeded e busque com o workspaceId da resposta.

{"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"}}

Ciclo de vida: refresh recria só os escopos cujos bytes do .fig mudaram; rebuild recria mesmo sem mudança; clear_cache apaga só dados que um build pode recriar e mantém o registro e os índices publicados; reset apaga o banco de dados deste workspace (nunca o .fig nem as exportações) e só roda a pedido explícito. Novas fontes, um escopo maior, reset e recriação exigem, cada um, um pedido explícito próprio.

Moveu o .fig? index relocate mantém workspaceId, sourceId e armazenamento; depois faça refresh dos escopos afetados. Não há descoberta automática nem fusão por hash, e não é preciso reset.

Vários designs em uma pasta? index add <dir> --workspace DIR registra de uma vez até 10 arquivos .fig desse diretório e ignora links que saem dele; a resposta traz added, existing, skipped e truncated, repetir não adiciona nada, e cada arquivo ainda precisa do próprio prepare --scope. Um arquivo movido dentro da pasta é uma nova fonte, a menos que você use relocate. Passe o nextCursor da resposta como --cursor C (MCP cursor) para adicionar os 10 seguintes. Os cursores paginados de busca e de biblioteca duram uma hora; depois disso retornam cursor_expired, então busque de novo.

Dados: o banco SQLite guarda caminhos locais registrados, nomes de camadas e texto efetivo dos escopos escolhidos, valores de propriedades de componente das instâncias, postings de busca, relações exatas (contenção, instâncias, variantes, vínculos de variáveis/estilos/imagens, destinos de protótipo) e as definições a que apontam, hashes, gerações e jobs. O .fig original permanece inalterado onde está; seus bytes brutos não são guardados no banco. Camadas de modelos semânticos e de visão acrescentam os vetores que incorporam, e a indexação visual que você ativar acrescenta renderizações PNG das camadas indexadas, mesmo sem modelo; imagens de consulta nunca são guardadas.

Pi, OpenCode e OMP usam o mesmo índice por meio de sua própria entrada opt-in, e o workspace é reutilizado entre reinícios e hosts. Não implementado: eventos de arquivo (um watch consulta o arquivo, e só enquanto um holder roda) e eventos push.