Contexto além
do repositório.

Referências dão ao agente acesso a diretórios fora do projeto — documentação, bibliotecas compartilhadas, outro repositório — por um alias que funciona no @ e no contexto do sistema.

01Declarando

{
  "references": {
    "docs": {
      "path": "../product-docs",
      "description": "Use para comportamento do produto e convenções de docs"
    },
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
      "description": "Use para detalhes de implementação do Effect"
    }
  }
}

Atalho de string para os casos simples: "docs": "../docs" ou "effect": "Effect-TS/effect".

02Diretórios locais

path aceita caminhos relativos à config, absolutos, ou ~/. Bom para monorepos vizinhos, design systems e documentação interna.

03Repositórios Git

repository aceita URL Git, host/caminho ou o atalho owner/repo do GitHub. O MVCode materializa o repositório num cache local e expõe o checkout como diretório de referência. Sem branch, usa a default do repo.

04Usando com @

Compare esta implementação com @effect/packages/effect/src/Stream.ts

• @alias anexa a raiz da referência.
• @alias/ autocompleta arquivos dentro dela.
• Referências com descrição também entram no contexto do sistema — o agente as inspeciona sozinho quando são relevantes. Sem descrição, ficam disponíveis só via autocomplete.
• hidden: true tira do autocomplete sem tirar do contexto.

05Permissões se mantêm

Diretórios de referência passam pela fronteira de diretório externo automaticamente — mas as permissões de ferramenta continuam valendo. Um agente sem edit não ganha edição porque o diretório virou referência.

06Campos

Aliases não podem ser vazios nem conter /, espaços, crases ou vírgulas.