install-maintenance-graft-rtk-ponytail-lite

Prompt

# Instalação e Manutenção Verificadas — Graft + RTK + Ponytail lite

Você está trabalhando no repositório atual para instalar, atualizar, reparar ou verificar esta stack:

- Graft: entendimento de código, grafo local e enriquecimento LSP.
- RTK: redução de ruído no terminal.
- Ponytail: política lite, com integração nativa quando compatível.

Comece com um inventário somente leitura. Depois, faça as perguntas faltantes abaixo.
Após as respostas, realize as operações autorizadas até as verificações finais.

Não inicie a instalação antes de determinar os clientes e o escopo.
Não pergunte novamente por uma decisão já dada nesta conversa.

## 1. Inventário, depois escolha do usuário

### Inventário sem modificação

Identifique:

- SO, arquitetura, shell, ambiente: máquina local, WSL, SSH, container;
- raiz do repositório, worktree, status Git e operações Git em andamento;
- caminhos reais, versões e método de instalação do Git, Node, npm, RTK, Graft e clientes disponíveis;
- Claude Code, Codex, Kimi, Cursor Agent CLI e Cursor IDE separadamente;
- Gemini, Copilot CLI ou outros clientes já presentes como alvos opcionais;
- diretórios de configuração realmente usados, variáveis de redirecionamento e qualquer orquestrador como AgentsRoom;
- configurações existentes de usuário, projeto, plugin e hooks herdados.

Verifique a identidade do `agent` antes de considerá-lo como Cursor.
Um binário presente não prova autenticação, funcionalidade do hook ou carregamento MCP.

Não inicie atualizações automáticas, conexões ou instalações durante este inventário.
Não publique valores secretos.

Apresente uma tabela curta:
Cliente | Binário/versão | Configuração efetiva | Status conhecido.

### Perguntas a fazer em um único lote

Pergunte apenas as questões para as quais a resposta está faltando:

1. Operação:
   - Instalar componentes faltantes e manter versões compatíveis.
   - Atualizar a stack para versões estáveis verificadas.
   - Reparar a instalação existente mantendo suas versões.
   - Apenas verificar, sem modificação.

2. Clientes:
   - Todos os clientes detectados.
   - Uma seleção da lista realmente detectada.
   - Também preparar configuração para alguns clientes ausentes.

3. Escopo de integração:
   - Projeto compartilhado: configurações portáteis destinadas ao repositório.
   - Projeto pessoal: ativação para este repositório, arquivos locais não versionados.
   - Usuário global: ativação para os projetos deste usuário.
   - Misto: escolha distinta por cliente ou componente.

Se o escopo for misto, pergunte apenas os esclarecimentos necessários.

Para uma atualização, pergunte também por qualquer restrição de versão se ainda não conhecida.
Caso contrário, proponha versões estáveis explícitas.

Não instale ou atualize os próprios aplicativos clientes:
a operação diz respeito a Graft, RTK, Ponytail e suas dependências necessárias.
Um cliente desatualizado é reportado com a versão requerida e ação restante.

### Tornar escolhas concretas

Antes de escrever, exiba o resultado planejado:

Componente/cliente | Versão alvo | Escopo | Arquivos alvo | Efeito compartilhado | Alternativa

Explique notadamente:

- Um executável instalado no nível do usuário pode servir múltiplos repositórios.
- Atualizar este executável afeta todos os seus usuários locais.
- Um plugin pode ter cache global, mas ativação por projeto.
- Um hook por projeto pode ainda usar um estado compartilhado.
- O índice Graft permanece específico ao repositório/worktree.
- Uma configuração global fornecida por um orquestrador pode ser isolada
  para um projeto: verifique seu escopo real, não apenas seu nome.

Uma vez obtidas as escolhas, prossiga sem confirmações repetidas.
Solicite uma nova decisão apenas se uma limitação exigir
extensão de escopo ou mudança material na solução.

## 2. Regras de execução

Ordem:
inventário → escolha → backups → RTK → Graft/LSP → Ponytail →
instruções → verificações → relatório.

Respeite as instruções do repositório e políticas administradas.
Se um arquivo for gerenciado por AgentsRoom ou outro orquestrador,
use seu mecanismo oficial; não modifique diretamente seus arquivos gerados.

Antes de cada modificação:

- valide o formato E a estrutura das configurações JSON/JSONC/TOML;
- faça backup dos arquivos afetados fora do repositório, com acesso restrito;
- registre versões e elementos necessários para rollback;
- revise o dry-run do instalador quando existir.

Um arquivo inválido nunca deve ser substituído por uma configuração vazia.

Mescle configurações preservando outros MCPs, hooks, permissões,
instruções, comentários quando possível e linhas de status.
Não altere regras de aprovação ou impressões digitais de confiança.

Preserve alterações Git pré-existentes. Sem commit, push, reset,
clean, stash ou alterações no código da aplicação.
Em caso de conflito não resolvido ou operação Git em andamento, suspenda
escritas no repositório; continue diagnósticos independentes.

Não instale Graphify, CodeGraph, Caveman ou Headroom.
Uma integração antiga conflitante é removida somente após identificação precisa,
backup e dentro do escopo autorizado.
Não desinstale globalmente uma ferramenta usada em outro lugar.

Um erro bloqueia seus passos dependentes, não outros clientes independentes.
Não declare um passo bem-sucedido para contornar uma limitação.

## 3. Capacidades e escopo: verifique antes de configurar

Consulte a ajuda das versões instaladas e os documentos correspondentes
às versões publicadas que você usará:

- https://github.com/rtk-ai/rtk
- https://github.com/trailhq/Graft
- https://github.com/DietrichGebert/ponytail
- documentação oficial de cada cliente selecionado.

O branch main/develop pode descrever recursos ausentes em uma release.
Para uma opção questionável, verifique a release, a ajuda ou o código entregue.

Estabeleça para cada integração:

Cliente | Hooks de projeto disponíveis | Instalador compatível |
Escopo de ativação | Escopo de estado | Prova

Não confunda:
"o cliente aceita hooks de projeto"
e "o instalador desta ferramenta sabe como instalá-los no nível do projeto."

Pontos de verificação para rever nas versões atuais:

- Claude: configurações do usuário, projeto compartilhado e projeto local.
- Cursor: hooks de usuário e projeto; testar IDE e CLI separadamente.
- Codex: configurações de usuário/projeto e ativação de plugin;
  verificar os mecanismos de hook realmente disponíveis.
- Kimi: não assumir uma configuração de hook por projeto;
  distinguir configuração do usuário, instruções do projeto e opções de lançamento.
- Gemini/Copilot: verificar seus próprios mecanismos se selecionados.

Se o instalador não respeitar o escopo solicitado:

1. Procure uma opção oficial apropriada.
2. Caso contrário, use uma configuração manual documentada do mesmo adaptador,
   somente se seu protocolo e caminhos permanecerem compatíveis.
3. Caso contrário, use fallback por instruções/prefixo explícito.
4. Nunca mude silenciosamente para global.

Inspecione hooks globais herdados antes de adicionar seus equivalentes locais:
eles podem se acumular em vez de se substituir.
Preserve hooks de segurança. Informe efeitos globais que permanecem ativos.

## 4. RTK

Verifique a origem `rtk-ai/rtk`, a versão, a ajuda, a configuração
 e `rtk gain`. Uma falha em `gain` pode vir da base ou permissões:
isso não é prova suficiente de um pacote ruim.

Instale ou atualize com o gerenciador já usado, se apropriado.
Verifique a origem da fórmula ou pacote e a versão obtida.
Evite instalações concorrentes e mudanças desnecessárias no PATH.
Não execute `cargo install rtk` cegamente.

Consulte `rtk init --help` para a versão escolhida.
Selecione opções por cliente e escopo; não copie sistematicamente
`-g` de um exemplo de documentação.

Não assuma que a integração Codex é sempre uma instrução simples,
nem que sempre tenha um hook: isso depende da versão do RTK.
Também verifique incompatibilidades entre opções de inicialização.

Na configuração realmente lida, mescle exclusões:

    [hooks]
    exclude_commands = ["graft", "curl", "playwright"]

Preserve exclusões existentes e verifique sua consideração.
Se essa configuração for global, indique esse efeito antes de modificá-la.
Desative telemetria opcional pelo mecanismo documentado,
dentro do escopo permitido.

RTK é o único componente autorizado a reescrever comandos shell.
Hooks de segurança, auditoria e aprovação permanecem aplicáveis.

Não copie um hook Claude para outro cliente sem compatibilidade documentada.
Sem reescrita efetiva, configure o prefixo explícito `rtk`.
Evite hooks duplos e prefixos duplos.

## 5. Graft com LSP

### Instalação e privacidade

Verifique a identidade do pacote `@nanonets/graft`, sua versão publicada
 e seus requisitos de Node.

Instale fora das dependências da aplicação, em local adequado.
Não modifique package.json ou o lockfile do projeto para instalar Graft.

Aplique `DO_NOT_TRACK=1` desde o primeiro lançamento e no MCP.
Use o comando oficial para desativar telemetria se disponível.

Não ative Brain, conta, enriquecimento LLM ou `--deep`.
Não prometa rede zero sem verificar.

Não execute automaticamente `graft init`.
Prefira conexão explícita; seu instalador pode escrever fora do repositório.

### LSP verdadeiramente operacional

Antes de explorar código da aplicação, respeite as regras Graft do repositório.
Depois identifique linguagens úteis e consulte as integrações LSP
da versão Graft escolhida.

Reutilize servidores compatíveis já presentes.
Instale apenas servidores necessários, com versões registradas,
fora das dependências da aplicação quando possível.

Verifique:

- o executável e sua versão;
- sua disponibilidade no PATH do processo Graft/MCP;
- pré-requisitos de linguagem e workspace;
- seu suporte por esta versão Graft.

Após ler a ajuda, use notadamente, se disponíveis, estas opções:

    graft build --lsp --no-ignore --no-gitignore
    graft check
    graft ask "Where are the main entry points and API routes, if any?" --source

Aplique DO_NOT_TRACK a esses comandos com a sintaxe shell atual.

Verifique o significado das opções: em algumas versões,
`--no-ignore` e `--no-gitignore` impedem a escrita de arquivos de exclusão;
não significam "indexar arquivos ignorados."

Gerencie explicitamente a exclusão Git de `/graft/` conforme o escopo escolhido.
Verifique com Git. Não remova automaticamente arquivos já rastreados.
Preserve anotações e conteúdo humano.

Uma build com `--lsp` e código de saída 0 não prova uso do LSP.
Procure prova direcionada: servidor realmente iniciado, resultado de resolução,
bordas enriquecidas ou diagnósticos documentados.

Informe por linguagem:
LSP verificado / disponível sem enriquecimento observado / indisponível / não suportado.

Nunca carregue o grafo inteiro ou wiring.json no contexto.
Também verifique se o enriquecimento LSP persiste após um refresh automático;
se não garantido, documente a reconstrução explícita necessária.

### MCP e atualidade

Configure uma única entrada Graft efetiva por cliente.
Descubra o arquivo, esquema e escopo realmente suportados.

Para cada servidor, verifique:
comando instalado, argumentos MCP, DO_NOT_TRACK, PATH e diretório de trabalho.

Não assuma que um arquivo `.kimi-code/mcp.json`, `.mcp.json` ou outro é carregado automaticamente: confirme o mecanismo do cliente ou a opção de lançamento necessária.

Uma configuração MCP global é aceitável somente se o processo alvo endereçar corretamente cada repositório. Caso contrário, mantenha o MCP no nível do projeto.

Não use `npx -y ...@latest` a cada inicialização.
Não version controle caminhos pessoais absolutos ou segredos.
Não invente uma variável universal `${workspaceFolder}`.

Neste perfil, não adicione hooks Graft.
Sem smart-grep, grep-redirect ou interceptação shell Graft.

Verifique o refresh e a ausência de desativação não intencional.
Um refresh falho proíbe apresentar o grafo como atualizado.

Inspecione integrações antigas e metadados de auto-wiring antes da migração.
Remova apenas elementos identificados e com backup.
Verifique que não reapareçam após inicialização e consulta MCP.

### Estatísticas Graft

Operação separada, uso observado e coleta de estatísticas.

Dependendo da versão, `graft stats` depende de hooks de sessão.
Sem esses hooks, "nenhuma sessão registrada ainda" pode ser esperado apesar de requisições Graft bem-sucedidas.

Não fabrique estatísticas nem execute `graft init` para fazer essa mensagem desaparecer.

Se o usuário requer estatísticas nativas, exponha a compatibilidade dos hooks de medição disponíveis e solicite explicitamente a evolução do perfil sem hooks antes de qualquer ativação.

## 6. Ponytail lite

Prefira uma integração oficial compatível com o cliente e escopo.
Verifique seu manifesto, eventos e dependências.

Distingua:
instalação do plugin, ativação, modo padrão e estado do modo atual.

Inspecione as fontes realmente lidas:
configuração, `PONYTAIL_DEFAULT_MODE`, estado persistente e dados do plugin.
`defaultMode: lite` não prova que um estado completo antigo foi substituído.

Se o modo for compartilhado entre conversas, indique isso.
No escopo do projeto, não altere silenciosamente o padrão global.
Use um mecanismo local documentado ou a política lite por instruções.

Por cliente:

- Claude/Codex: instalação e ativação oficiais no escopo disponível.
  Verifique subcomandos antes de usá-los.
  Aprovações de hooks permanecem com o usuário.
- Cursor: adaptador oficial, ou regra de instrução; evite seu acúmulo.
  Se `scripts/cursor-hooks.js install --project` existir, execute o script
  a partir da raiz do repositório alvo usando o caminho oficial de checkout.
  Sem `--project`, verifique o destino do usuário.
  Inspecione caminhos gerados: um hook de projeto contendo um caminho absoluto
  para um checkout pessoal não é portátil e não deve ser comitado.
- Kimi: procure um adaptador oficial compatível. Caso contrário, política lite
  em AGENTS.md; adicione uma skill local mínima somente se útil
  e se seu formato e carregamento forem confirmados.
  Identifique-o como uma adaptação, sem prometer comandos ou estatísticas nativas.
- Outros clientes selecionados: aplique a mesma verificação, sem transpor automaticamente
  eventos Claude/Codex.

Mantenha o checkout do adaptador em uma versão ou commit identificado.
Não faça git pull em um checkout modificado.
Não adicione statusline ou indicador visual.

Teste o modo efetivo em uma nova sessão.

## 7. Instruções comuns compactas

Mescle um bloco delimitado por:

    <!-- agent-stack:start -->
    ...
    <!-- agent-stack:end -->

em AGENTS.md. Preserve todo conteúdo externo e adições humanas.
Não copie este prompt de instalação nas instruções do agente.

O bloco deve expressar:

### Graft

Para entender ou modificar o código, primeiro exploração da aplicação:
`graft ask "<pergunta precisa>" --source`, ou a ferramenta MCP Graft realmente exposta.

Instruções, skills, Git, configurações e descoberta MCP podem preceder.
Após orientação, leia diretamente as porções úteis.
Para chamadores, use comandos/ferramentas de trace disponíveis.

Em caso de grafo desatualizado: verifique, reconstrução adaptada com LSP, depois nova consulta.
Após busca malsucedida: grep graft direcionado, depois leitura direta
ou rg limitado com explicação do limite.

Um arquivo fornecido, um stack trace, uma configuração ou uma linguagem não indexada
permitem leitura direta direcionada.
Ausência no grafo não prova ausência de código ou chamadores.

Após modificações: graft blast, base Git verificada e testes relevantes.
Sem --name, sem carregamento completo do grafo.
Reporte o número real de chamadas e quaisquer erros.

### RTK

Hook verificado: deixe a reescrita agir sem prefixo duplo.
Caso contrário: prefixe explicitamente comandos compatíveis.
Nunca passe Graft pelo RTK.

Para saída completa: recorra a --full se disponível, ou proxy.
Não reexecute automaticamente um comando com efeitos colaterais.
Preserve pipelines e redirecionamentos.

Antes da validação: diffs reais descompactados, diff --cached,
diff --check e inspeção separada de novos arquivos.
Sem staging automático.

### Ponytail lite

Implemente o pedido corretamente e reutilize o existente.
Reporte brevemente uma solução significativamente mais simples.
Preserve validação, segurança, permissões, acessibilidade, transações
e testes necessários. Verifique usos antes de deletar ou inline.

Completo somente sob pedido explícito, nunca ultra por padrão.
Uma auditoria não desencadeia um redesenho.
Correção tem prioridade para segurança, parsers, concorrência e migrações.

Não afirme que um modo compartilhado é local a uma conversa.
Após um full autorizado, verifique retorno ao lite.
Desligado não remove instruções já injetadas.

### Carregamento

Confirme como cada cliente realmente carrega essas instruções.
Use imports/adaptadores mínimos documentados.
Evite duplicações e imports circulares.

RTK permanece o único reescritor de shell.
Nenhum hook Graft neste perfil.

## 8. Atualização e Reparo

O mesmo prompt deve poder ser reexecutado sem duplicatas.

No modo atualização:

1. Releia as escolhas de escopo e o estado previamente verificado.
2. Compare versões instaladas, versões alvo e mudanças incompatíveis.
3. Faça backup antes de qualquer migração.
4. Atualize somente os componentes selecionados.
5. Atualize plugins/adaptadores com seu mecanismo oficial.
6. Reavalie capacidades: um fallback antigo pode ser substituído
   por uma integração nativa agora disponível, dentro do mesmo escopo.
7. Migre somente chaves e blocos pertencentes a esta stack.
8. Reconstrua o grafo se necessário e rechecagem do LSP.
9. Reinicie processos MCP/cliente necessários:
   um processo existente pode ainda estar rodando a versão antiga.
10. Refaça verificações e testes das integrações modificadas.

Não reinstale desnecessariamente um componente que já está conforme.
Não lance uma atualização geral dos pacotes da máquina.

No modo reparo, mantenha versões exceto por incompatibilidade demonstrada
e decisão explícita de atualização.

Prepare um rollback direcionado: versões anteriores, backups,
e comandos exatos. Não restaure cegamente um arquivo inteiro
se outras mudanças ocorreram desde seu backup.

Uma segunda execução sem mudanças solicitadas não deve criar
nenhum hook, servidor MCP ou seção de instrução duplicada.

## 9. Verificações e Evidências

Teste separadamente:

- Executável RTK e compressão explícita;
- disparo automático de hooks, exclusões e passagem direta raw;
- Graft: atualidade, resultado correspondente ao repositório e enriquecimento LSP;
- MCP: servidor funcional E carregamento real em cada cliente;
- Ponytail: ativação e modo efetivo;
- ausência de duplicatas e auto-conexão reaparecida;
- validade final das configurações e escopo efetivo.

Um arquivo presente não é prova de carregamento.
Uma sonda MCP externa não é prova de carregamento no cliente.
Um prefixo RTK explícito não é prova de hook automático.

Para cada cliente disponível e autenticado, abra uma nova sessão
no repositório, com suas proteções habituais, e forneça este ticket neutro:

"Sem modificar o código, localize os pontos principais de entrada.
Se houver uma API, indique onde suas rotas estão montadas e trace
um caminho até a lógica de negócio. Cite arquivos e linhas."

Não adicione "use Graft".
Inspecione chamadas visíveis de ferramentas, não raciocínio interno.
Mantenha evidências mínimas e redija dados sensíveis.

Se aprovação, login ou ação de UI estiver faltando:
NÃO TESTADO / AÇÃO DO USUÁRIO, nunca assuma sucesso.

## 10. Entregável

Dentro do escopo autorizado, mantenha uma documentação curta de manutenção:

- escolha da operação, clientes e escopo;
- versões exatas, origem e data de verificação;
- mecanismos de configuração e limites;
- reconstrução Graft/LSP;
- procedimento de atualização, verificação e rollback.

Para uma instalação compartilhada, use `docs/agent-stack.md`.
Para uma instalação pessoal/global, mantenha informações específicas da máquina
fora dos arquivos versionados.
No modo somente verificação, entregue o relatório sem criar esses arquivos.

Reporte comandos decisivos, seus resultados, arquivos modificados,
backups e ações exatas do usuário.

Faça inventário dos hooks finais:
cliente, origem, escopo, evento, matcher, papel e comando redigido.

Finalize com:

Cliente/versão | Escopo efetivo | Configuração presente |
MCP carregado | Graft observado na primeira exploração |
LSP | RTK | Ponytail | Prova/ação restante

Use estados explícitos:
CONFIGURADO / CARREGADO / USO OBSERVADO / NÃO TESTADO / BLOQUEADO / NÃO APLICÁVEL.

Classifique arquivos:
PARA COMMIT APÓS REVISÃO / PARA IGNORAR / CONFIGURAÇÃO DE MÁQUINA.

Caminhos pessoais, segredos, caches, gráficos, backups e transcrições
não devem ser incluídos em arquivos para commit.

Exiba o status final do Git e as mudanças introduzidas por esta intervenção,
distinguindo-as das mudanças pré-existentes. Não faça commit de nada.

Tags