Documentação

01Primeiros passos

Do instalador à primeira resposta da IA no seu código. Cinco minutos, sendo generoso.

Instalar

1. Instale a IDE pela página de download — Microsoft Store (um clique, sem SmartScreen), winget ou o .exe direto.
2. Abra o Lya Studio Coder pelo menu Iniciar. Na primeira execução aparece a splash com o manifesto — você pode revê-la depois em Ver Manifesto.
3. Escolha o ponto de partida na tela de boas-vindas: criar projeto do zero, abrir uma pasta existente ou clonar um repositório do Git.

Ligar um motor de IA

A IDE abre funcional mesmo sem nenhuma IA conectada — mas o interessante começa quando você liga um motor. Há dois caminhos, e você pode ter os dois:

• Sem chave, offline: instale o Ollama, baixe um modelo e selecione-o na IDE. Custo zero, dado nenhum sai da máquina. Veja §9.
• Com chave, na nuvem: registre sua chave no Chaveiro (§7) e configure o provedor (§8).

Primeira conversa

1. Abra o chat e peça algo concreto sobre o projeto aberto — por exemplo: "leia o package.json e me diga o que este projeto faz".
2. Repare que a IA usa ferramentas de verdade: ela lê o arquivo em vez de inventar. Cada ferramenta usada aparece na conversa.
3. Peça uma alteração. A IA edita o arquivo e você revisa o resultado no editor — com o diff do Git marcado na régua.

02Tour da interface

Quatro regiões, e você já sabe onde tudo mora.

Barra superior

• Menus Ver, Terminal e Ajuda — abrir painéis, criar ou dividir terminal.
• Busca (lupa) — arquivos e conteúdo do workspace.
• Super CLI — lançamento rápido de qualquer agente de código instalado, direto no terminal integrado, com o ícone real de cada motor e um selo off quando não está disponível.
• Olho do COSMOS — estado global num relance: missão, equipe e build. Diz se há missão rodando, quantos assentos estão configurados e como terminou o último build.
• Zoom (Ctrl + / Ctrl - / Ctrl 0) e os botões de janela.

Barra de atividades (esquerda)

Rodapé da barra lateral

Ali ficam o indicador de Memória: Conectada / Inativa, o acesso às Configurações e o atalho para rever o manifesto. A borda animada da memória é o próprio indicador de status — girando, está online; parada, offline.

03Projetos e arquivos

Criar do zero, abrir o que existe ou clonar do Git — e achar qualquer coisa depois.

Criar um projeto novo

1. Na tela de boas-vindas, escolha Criar projeto.
2. Selecione um modelo de partida ou use "Descreva seu projeto e o COSMOS monta" — escreva em português o que você quer (ex.: "uma API REST em Node com autenticação JWT e testes").
3. Escolha a pasta onde criar. A IDE cria a estrutura e convoca a orquestradora para montar o esqueleto.

Abrir um projeto existente

• Abrir pasta… na tela de boas-vindas, ou Abrir Pasta no topo do Explorador (troca o workspace).
• A lista de Recentes guarda as últimas pastas — um clique volta ao trabalho de ontem.
• A IDE lembra do último workspace e reabre nele na próxima vez.

Clonar um repositório

Clonar do Git na tela de boas-vindas: cole a URL (https://github.com/usuario/repo.git), escolha onde clonar e pronto — a pasta clonada já abre como workspace.

Explorador

• Novo arquivo / Nova pasta / Renomear / Copiar caminho / Revelar / Excluir no menu de contexto (botão direito).
• Status do Git por arquivo: modificado, adicionado, não rastreado, deletado, renomeado, conflito.
• Recolher tudo e Atualizar no cabeçalho do painel.

Busca

Dois modos no mesmo campo:

• Nome — filtra arquivos pelo nome, instantâneo.
• Conteúdo — varre o texto dos arquivos com regex e opção de diferenciar maiúsculas. Mostra trecho, arquivo e linha; clicar leva direto ao ponto.

04Editor de código

É o motor do VS Code por dentro — então o que você já sabe, funciona.

O que está disponível

• IntelliSense, F12 (ir para definição), find references, multi-cursor (Ctrl+D).
• Minimap e realce do diff do Git na régua lateral.
• Botão ▶ executa o arquivo atual no terminal integrado.
• Temas de sintaxe e de ícones instaláveis pela Loja — a coloração usa gramáticas reais, não regex improvisada.

Editar com IA — Ctrl+K

1. Selecione o trecho que quer mudar (ou nada, para agir no arquivo).
2. Pressione Ctrl+K e descreva a alteração em português.
3. A IDE mostra um diff lado a lado. Você decide: Aplicar ou Descartar.

05Terminal integrado

PTY nativo — um terminal de verdade, com cores, TUI e tudo mais.

• Novo Terminal e Dividir Terminal (lado a lado) pelo menu Terminal.
• Roda o que você roda normalmente: npm, python, node, git, tsc, gradle…
• O botão ▶ do editor e o Compilador transmitem a saída aqui, ao vivo.
• O Super CLI da barra superior abre qualquer agente de código instalado direto numa aba deste terminal.

06Chat com a IA

A sala central. Aqui você fala com a orquestradora — e ela age no projeto.

Enviar

• Tecla de envio configurável: Enter envia e Shift+Enter quebra linha — ou o contrário, se você preferir. Ajuste nas Configurações.
• Parar geração: o botão ⏹ aborta de verdade a requisição em andamento, inclusive no provedor de origem.
• Editar mensagem enviada: Ctrl+Enter confirma, Esc cancela.

Anexos e voz

• Anexar arquivos e colar print direto no campo (multimodal, quando o motor suporta).
• Gravar voz com player no preview antes de enviar.

Ferramentas do agente

O chat não é só texto: a IA tem ferramentas reais — ler e escrever arquivos, rodar comandos no terminal, buscar na memória, acionar servidores MCP conectados e usar comandos de extensões instaladas. Cada ferramenta pode ser ligada ou desligada individualmente, e o uso aparece na conversa: você vê o que ela fez, não só o que ela disse.

Continuidade em modelos com limite apertado

Modelos com teto baixo de tokens por minuto costumam interromper a resposta no meio. A IDE detecta o limite, mostra um selo com o tempo de espera, aguarda e retoma do ponto exato — sem reiniciar a conversa e sem perder contexto. Você também pode continuar enviando mensagens enquanto o modelo processa: elas entram numa fila e são respondidas em ordem.

07Chaveiro de chaves de API

Um lugar só para as chaves, cifradas em repouso. Você nunca precisa colá-las de novo.

Registrar uma chave

1. Abra Configurações → Provedores e escolha o provedor (ou crie um novo).
2. No bloco Chaveiro de APIs Seguro, clique em + Nova Chave.
3. Dê um identificador que faça sentido para você (ex.: "Gemini pessoal", "Claude do trabalho") e cole a chave.
4. Gravar no Chaveiro. A chave é cifrada com AES-256-GCM antes de tocar o disco — a partir daí você só a seleciona pelo nome, nunca vê o valor bruto de novo.

Reaproveitar

A mesma chave serve a vários lugares: o chat, os assentos da equipe e a memória (quando ela usa embeddings na nuvem). Registre uma vez, use em todo canto — e quando a chave girar, você troca num lugar só.

Onde mais entram credenciais

• Carteira de contas — além dos modelos, guarda credenciais de serviços como GitHub, Drive, SMTP e Partner Center, com teste real de conexão (não é só salvar e torcer).
• Endpoints locais — a chave é opcional; só preencha se o seu servidor local exigir.

08Configurar um provedor

Qualquer endpoint compatível com OpenAI entra aqui — NVIDIA NIM, Groq, DeepSeek, Together, OpenRouter e o que mais existir amanhã.

Passo a passo

1. Abra Provedores e clique em Adicionar provedor.
2. Identidade visual: dê um nome e um símbolo. O botão Obter baixa o logo automaticamente para você reconhecê-lo no seletor.
3. Tipo: Local (roda na sua máquina) ou Remoto (API na nuvem).
4. URL: o host da API — ex.: http://localhost:11434 para local, ou https://api.seu-provedor.com/v1 para remoto.
5. Chave: selecione uma do Chaveiro (§7). Em endpoint local, geralmente pode ficar vazio.
6. Testar Conexão. O console de handshake mostra a conversa real com o servidor.
7. Escolha o modelo padrão entre os motores que a API realmente devolveu — e adicione outros se quiser alternar.

Memória no provedor (RAG)

• RAG v2 (padrão) — as respostas recebem contexto recuperado da memória vetorial local.
• RAG v1 — sem recuperação: o modelo responde só com o histórico da conversa.

A preferência é salva por provedor, então você pode ter um "com memória" e outro "puro".

09Motores locais e OmniRoute

Custo zero, offline e sem nenhum dado saindo da máquina.

Ollama

1. Instale o Ollama na máquina.
2. Baixe um modelo pelo terminal integrado — ex.: ollama pull mistral.
3. Na IDE, o provedor local aparece com os modelos detectados. Selecione e use.

Nas configurações avançadas do provedor local você ajusta janela de contexto, limite de geração e tempo de permanência do modelo na memória — por modelo. A IDE avisa quando o pedido não cabe na janela, em vez de cortar em silêncio.

OmniRoute — instalar e ligar

O OmniRoute (repositório) é um roteador de modelos local: um gateway compatível com OpenAI que coloca um catálogo enorme de modelos atrás de um único endereço na sua máquina. A IDE o adotou como provedor nativo e cuida do ciclo de vida dele.

1. Abra Configurações → Infraestrutura (capacidades instaláveis).
2. No cartão do OmniRoute, clique em Instalar — a IDE baixa, prepara e já liga o serviço.
3. Pronto. A partir daí ele sobe junto com a IDE em todo boot e a conexão é feita sozinha: nada de chave para colar, nada de voltar em Provedores para salvar. Se preferir ligar na mão, desmarque "Subir junto com a IDE" no mesmo cartão.
4. Abrir Dashboard serve para cadastrar contas novas no OmniRoute — não é um passo obrigatório do dia a dia.

Capacidades de desenvolvimento

Ainda em Infraestrutura, a IDE detecta e instala sob demanda type checkers (LSP), linters, formatters e test runners — e sabe executá-los sobre o workspace. Nada de "instale isso manualmente e boa sorte": o botão Rodar no projeto executa de verdade.

10CLIs de agente

Agentes de código de linha de comando viram assentos da equipe — com as ferramentas deles, dentro da sua missão.

Instalar as CLIs oficiais

1. Vá em Configurações → Infraestrutura → CLI de Agentes IA.
2. A IDE mostra o caminho real detectado de cada CLI, ou não detectado.
3. Clique em Instalar para instalação com um clique, ou Abrir terminal para fazer à mão.
4. Depois de instalar, Verificar confirma que o executável responde.
5. Autentique a CLI uma vez no terminal integrado (cada uma tem seu próprio login).

Claude Code (Anthropic) e AGY / Antigravity (o oficial do Google) têm instalação assistida aqui. A Gemini CLI foi descontinuada em 18/06/2026 — se você usa um fork da comunidade, aponte o executável manualmente.

Ligar o opencode ou qualquer CLI própria

1. Instale a CLI normalmente pelo terminal integrado (por exemplo, o opencode).
2. Em CLI de Agentes IA, use 📁 Caminho manual para apontar o executável — serve para fork, instalação própria ou versão fora do PATH.
3. Ou cadastre do zero em + Cadastrar CLI: nome + comando/caminho do executável.
4. Salvar e depois Verificar.

Onde as CLIs aparecem

Tudo que estiver marcado como visível na lista de "CLIs registradas" aparece nos seletores do chat e dos assentos Star 1–4, além do Super CLI da barra superior. As CLIs fixas não podem ser excluídas (vivem no código), mas podem ser ocultadas; as personalizadas podem ser editadas ou excluídas.

11Criar e ajustar agentes

Cada assento tem nome, personalidade, motor e um cardápio de skills. Você monta a equipe do jeito que o seu trabalho pede.

Onde fica

Painel Orquestração IA → aba 🤖 Perfil. À esquerda, a lista de inteligências ("Filhas de Lya"); à direita, o perfil da selecionada.

Configurar um agente

1. Nome da IA — aparece no cabeçalho do chat, nas mensagens e no projeto todo.
2. Tagline — o subtítulo dela (ex.: Orquestradora).
3. Prompt base / personalidade — quem ela é e como deve trabalhar. É aqui que você define método, tom e limites.
4. Motor — escolha entre modelo local, provedor de API ou uma CLI registrada. Use 📡 Testar conexão: manda um "oi" real e mostra a resposta.
5. Skills — anexe roteiros do cardápio (§15). Cada skill é um procedimento que ela passa a saber executar.
6. Seu nome — como você aparece no chat. Vazio vira "Arquiteto".

Níveis de agressividade

Quem orquestra

Marque a Orquestradora Ativa: quem estiver marcado planeja, distribui e consolida, comandando as demais com o motor próprio. O padrão é o COSMOS — e a recomendação é mantê-lo, já que a soberania da revisão é dele.

12Orquestrar uma missão

Do objetivo escrito em português à entrega consolidada, com a equipe inteira trabalhando.

Antes de disparar

• Cada assento que você pretende usar tem um motor selecionado e ONLINE (teste com 📡).
• O workspace aberto é o certo — a equipe vai agir sobre ele.
• O teto de custo está no valor que você aceita gastar nessa missão.

Disparar

1. Painel Orquestração IA → aba Orquestração.
2. Escreva a Meta / Objetivo. Seja específico no resultado, não no passo a passo: "migrar todos os callers da APIv1 para a v2 conforme MIGRATION.md e deixar os testes verdes".
3. Clique em Iniciar Orquestração.
4. Acompanhe o Mapa da Equipe: quem está ativo, em qual motor, com qual estado.

Durante

• Pausar / Retomar a missão inteira — ou só um agente, deixando os demais seguirem.
• Parar aborta de verdade (não é um pedido educado que fica pendurado).
• Fila de ordens — enfileire as próximas missões; avançar inicia a seguinte na hora, e uma ordem pode ser cancelada.
• Custo — tokens estimados e custo real, ao vivo. Ao bater o teto, a missão é abortada de fato.
• Mural / feed da equipe — o que cada Star entregou, e o que o maestro devolveu para refazer.

Como saber que está orquestrando de verdade

Procure o laço de revisão no feed: a orquestradora lê a entrega de cada Star, aponta o problema e manda refazer. Se as entregas só se acumulam e viram um resumo no fim, aquilo é disparo paralelo — não orquestração. Entenda o modelo completo na página do COSMOS.

13Memória Deep

O que a IDE aprende sobre o seu projeto fica — e volta na próxima sessão.

As abas do painel

Como o conhecimento é organizado

• Episódico — o que aconteceu (sessões, missões, decisões).
• Semântico — fatos e conceitos do domínio.
• Procedural — como se faz (receitas que funcionaram).
• Identidade — quem é quem, preferências, contexto do projeto.

Alimentar a memória

1. Sozinha: decisões relevantes da conversa são enfileiradas e gravadas em lote, sem travar o chat.
2. Pela Inbox: cole um texto, dê um nome, salve.
3. Por pasta monitorada: aponte um diretório e a IDE ingere o conteúdo, sem reprocessar o que não mudou.

14Core5 e backends de memória

Qual motor de memória usar — e a resposta curta é: não mexa, já vem certo.

Core5 (padrão, embutido)

• Roda dentro do processo da IDE. Não exige Python, Docker nem serviço em segundo plano.
• Embedding nomic-embed-text-v1.5, 768 dimensões.
• Cascata segura: embedding online (chave resolvida da carteira) → modelo local na CPU → guarda que descarta vetor de dimensão incompatível. É por isso que a base não corrompe.
• Velocímetro com embeddings por segundo, latência, fonte ativa e capacidade — telemetria real, não enfeite.

ChromaDB (legado, opcional)

É o motor anterior, que precisava de Python à parte. Continua disponível e só participa das buscas se você habilitar. Faz sentido ligar apenas se você já tem uma base ChromaDB de uma versão anterior e quer consultá-la. Os dois podem rodar juntos: cada busca consulta os motores habilitados e mescla os resultados sem duplicar.

Compartilhar memória com outras ferramentas

A IDE fala MCP com uma instância externa do Core5 — assim uma CLI de agente e a IDE trabalham sobre o mesmo contexto do mesmo projeto. O indicador de status só acende quando a conexão foi provada por handshake real. Como conectar: §18.

Cicatrizes: aprender com o próprio erro

Quando um erro de build é resolvido, a receita vira uma cicatriz consultável — da próxima vez que o mesmo erro aparecer, a IA já entra sabendo o caminho. Cicatriz só nasce de sucesso comprovado (código de saída real do comando), nunca de uma IA alegando que consertou.

15Skills — ensinar procedimentos à IA

Uma skill é um roteiro real de comandos que o agente passa a saber executar. É como treinar um colega novo: uma vez, e ele sabe para sempre.

Obter skills

1. Abra a Loja Lya.
2. Importar do Git: cole a URL https://… de um repositório — a IDE clona, varre as definições de skill e indexa de verdade no catálogo.
3. Compilar uma nova: descreva a ideia e deixe a IA montar o cartão da skill.
4. Criar/editar à mão pelo editor de skills: nome, descrição, categoria e funções.

Ativar numa IA

1. Vá em Orquestração IA → 🤖 Perfil e selecione o agente.
2. No Cardápio de Skills, clique em + Anexar nas que ele deve saber.
3. As anexadas aparecem em Habilidades Adquiridas — clique numa delas para remover.

Skills anexadas à orquestradora são carregadas no chat do agente. Anexe o que é pertinente ao papel: encher todo mundo de tudo só gasta contexto.

Modo de consulta do catálogo

• Cartões de visita — a visão legível, para você navegar.
• IA (modo otimizado) — índice compacto e categorizado que a IA consulta. Em vez de engolir o script inteiro de cada ferramenta, ela lê um menu seletivo — o que derruba drasticamente o contexto gasto.

16Loja Lya

Um lugar para tudo que se instala na IDE.

Cada item traz origem, autor e as funções que expõe. Skills importadas podem ser editadas ou removidas do registro a qualquer momento.

17Extensões (Open VSX)

Extensões reais do VS Code, vindas de um registro aberto.

1. Abra o painel Extensões e busque (ex.: prettier, python, eslint).
2. Repare no selo de suporte de cada resultado — a IDE é honesta sobre o que roda:
   • JS — roda no host: extensão com código, executada no Extension Host.
   • Declarativa: tema, snippet ou keymap — aplicada sem executar código.
   • Não suportada: depende de recurso que a IDE ainda não oferece (ex.: debuggers).
3. Instalar — a instalação é real; o que não é suportado é recusado com o motivo, em vez de fingir sucesso.
4. Ativar / Desativar / Desinstalar na lista de instaladas. Extensões ativas carregam em runtime, sem rebuild.

Também dá para importar um .vsix local ou instalar por URL — com o mesmo crivo de validação. Fonte de terceiros é sinalizada como não verificada.

18Servidores MCP

Cada servidor MCP conectado expõe ferramentas reais para a orquestradora usar.

1. Abra Configurações → Servidores MCP e clique em Adicionar servidor MCP.
2. Nome do servidor (ex.: filesystem).
3. Transporte:
   • STDIO — processo local: informe o comando, os argumentos e, se precisar, o diretório de trabalho.
   • HTTP ou SSE — servidor remoto: informe a URL.
4. Adicione variáveis de ambiente se o servidor exigir (chaves, caminhos).
5. Salvar e depois Testar conexão real.
6. Conectado, a IDE mostra ● conectado — N ferramenta(s) disponível(is). Só então elas ficam ao alcance da IA.

Servidores podem ser ativados/desativados sem perder a configuração, editados ou excluídos.

19n8n e pipeline RAG

Automação visual gerenciada pela própria IDE.

• Servidor n8n gerenciado: instalar, iniciar e parar pelo painel — sem terminal, sem configurar serviço.
• Editor de pipeline RAG: monte o fluxo recupera memória → dispara o modelo com contexto → publica o resultado.
• Webhooks: combinado com o túnel de compartilhamento, seus fluxos recebem chamadas externas enquanto você testa.

20Compilador e Simulador

Build e run reais, com a saída transmitida ao vivo.

• Detecção do comando do projeto — npm, gradle, tsc, python — sem você configurar.
• Saída ao vivo no terminal, em streaming: você vê o erro no instante em que ele acontece.
• Preview ao vivo — dev server gerenciado e a interface do seu app dentro da IDE, em molde de celular ou desktop.

21Run & Debug

Depuração de verdade — breakpoint, passo a passo, variáveis.

• Node.js via protocolo do Chrome DevTools e Python via debugpy/DAP.
• Breakpoints, step over / into / out.
• Variáveis e call stack inspecionáveis durante a pausa.

Combine com o chat: pare no breakpoint, mostre o estado à IA e pergunte por que a variável está com aquele valor. Ela lê o código que produziu aquilo.

22Lya Publisher — publicar na Microsoft Store

Da versão ao pacote submetido, sem sair da IDE. É assim que a própria Lya se publica.

Preparar uma vez

1. Tenha uma conta de desenvolvedor no Partner Center e um app reservado.
2. Cadastre as credenciais (Entra ID) na Carteira de contas — elas são cifradas com AES-256-GCM, como qualquer chave.
3. Prepare as screenshots obrigatórias (mínimo 1366×768) — arraste e solte no painel.

Publicar

1. Abra o painel Lya Publisher.
2. Rode o dry-run primeiro: ele percorre o pipeline sem submeter nada.
3. Bump de versão — a IDE atualiza todos os arquivos de versão do projeto de uma vez.
4. Build + empacotamento geram o pacote de instalação.
5. Em Pacote a enviar, escolha explicitamente o pacote pela versão e pelo hash — nada de adivinhação sobre qual arquivo subiu.
6. Enviar. O log ao vivo acompanha upload e submissão; o histórico guarda cada envio.

23Segurança e sandbox

O que a IA pode tocar — e o que ela não alcança de jeito nenhum.

• Sandbox de caminhos: o agente só lê e escreve dentro dos diretórios autorizados. Tentativa de sair da árvore permitida é recusada, inclusive por caminho relativo malicioso.
• Credenciais cifradas em repouso (AES-256-GCM), com a chave mestra restrita ao seu usuário do sistema.
• Servidor local fechado: a IDE só aceita requisições da própria máquina.
• Trilha de auditoria: as ações do agente ficam registradas — e edições podem ser revertidas.
• Teto de custo por missão, que aborta de verdade ao estourar.

24Configurações

Onde ajustar aparência, atalhos, infraestrutura e atualização.

Idioma

Português, English e Español — a interface inteira, incluindo mensagens de erro da orquestração. Troque na barra superior; a mudança é imediata.

Atualizar a IDE

Configurações → Verificar atualização. Instalado pela Microsoft Store, a atualização é automática; instalado pelo .exe, a IDE aponta a nova versão e você instala por cima.

25Atalhos essenciais

26Se algo der errado

Ainda travado?

• Abrir uma issue — todo relato é lido e respondido.
• Perguntar em Discussions → Q&A.
• Documentos complementares: Instalação · Quick Start · FAQ · Arquitetura