Disponibilidade de material de apoio

Este texto do catálogo contém as orientações inline abaixo, mas não inclui os seguintes caminhos de suporte. Eles são pré-requisitos externos, não arquivos incluídos:

• <support-root>/references/install-vexor.md

Solicite o material de apoio original ou uma instalação existente antes de usar uma etapa que dependa desses caminhos; este catálogo não identifica uma fonte de download verificada para eles. Resolva cada caminho em relação a essa instalação, inspecione seu conteúdo e verifique quaisquer licenças e pré-requisitos de execução aplicáveis. Não execute um comando ou afirme que um procedimento referenciado foi seguido até que seu arquivo necessário exista. Não crie os scripts ausentes nem trate um arquivo não relacionado com o mesmo nome como equivalente. Etapas independentes totalmente documentadas aqui podem prosseguir dentro do escopo autorizado do usuário; relate qualquer etapa dependente como indisponível.

Habilidade Vexor CLI

Quando Usar

• Você precisa localizar arquivos por intenção, em vez de nome de arquivo exato ou correspondência de texto.
• O repositório é grande o suficiente para que a navegação manual ou o grep ingênuo sejam muito lentos ou ambíguos.
• Você deseja descoberta semântica de onde algo é implementado, carregado, definido ou documentado.

Objetivo

Encontrar arquivos por intenção (o que eles fazem), não por texto exato.

Use Assim

• Use vexor primeiro para descoberta de arquivos baseada em intenção.
• Se vexor estiver faltando, siga references/install-vexor.md.

Comando

vexor "<QUERY>" [--path <ROOT>] [--mode <MODE>] [--ext .py,.md] [--exclude-pattern <PATTERN>] [--top 5] [--format rich|porcelain|porcelain-z]

Flags Comuns

• --path/-p: diretório raiz (padrão: diretório atual)
• --mode/-m: estratégia de indexação/pesquisa
• --ext/-e: limita extensões de arquivo (por exemplo, .py,.md)
• --exclude-pattern: exclui caminhos por padrão no estilo gitignore (repetível; .js → **/*.js)
• --top/-k: número de resultados
• --include-hidden: inclui arquivos ocultos (dotfiles)
• --no-respect-gitignore: inclui arquivos ignorados
• --no-recursive: apenas o diretório superior
• --format: rich (padrão) ou porcelain/porcelain-z para scripts
• --no-cache: apenas em memória, não lê/escreve cache de índice

Modos (escolha o mais barato que funcionar)

• auto: roteia por tipo de arquivo (padrão)
• name: apenas nome de arquivo (mais rápido)
• head: apenas primeiras linhas (rápido)
• brief: resumo de palavras-chave (bom para PRDs)
• code: divisão consciente de código para .py/.js/.ts (melhor padrão para bases de código)
• outline: títulos/seções Markdown (melhor para documentação)
• full: divide o conteúdo completo do arquivo (mais lento, maior recall)

Solução de Problemas

• Precisa de arquivos ignorados ou ocultos: adicione --include-hidden e/ou --no-respect-gitignore.
• Saída scriptável: use --format porcelain (TSV) ou --format porcelain-z (delimitado por NUL).
• Obtenha ajuda detalhada: vexor search --help.
• Problemas de configuração: vexor doctor ou vexor config --show diagnosticam API, cache e conectividade (instrua o usuário a configurar).

Exemplos

# Find CLI entrypoints / commands
vexor search "typer app commands" --top 5

# Search docs by headings/sections
vexor search "user authentication flow" --path docs --mode outline --ext .md --format porcelain

# Locate config loading/validation logic
vexor search "config loader" --path . --mode code --ext .py

# Exclude tests and JavaScript files
vexor search "config loader" --path . --exclude-pattern tests/** --exclude-pattern .js

Dicas

• A primeira pesquisa indexará arquivos (pode levar um minuto). Pesquisas subsequentes são rápidas. Use tempos limite mais longos, se necessário.
• Os resultados retornam classificação de similaridade, localização exata do arquivo, números de linha e prévia do trecho correspondente.
• Combine --ext com --exclude-pattern para focar em um subconjunto (regras de exclusão se aplicam por cima).

Limitações

• Use esta habilidade apenas quando a tarefa corresponder claramente ao escopo descrito acima.
• Não trate a saída como substituta para validação específica do ambiente, testes ou revisão especializada.
• Pare e peça esclarecimentos se os inputs necessários, permissões, limites de segurança ou critérios de sucesso estiverem faltando.