---
name: studiolocal-install
description: Prepara o data root global do StudioLocal (~/.studiolocal): cria tracker.db, aplica migrations e, só se pedirem, escreve o bloco no CLAUDE.md. Use quando o usuário pedir "instala o studiolocal", "/studiolocal-install", ou quando o CLI disser que o root global não existe ("StudioLocal não instalado em ...", `studiolocal root` com tracker ausente).
---

# Skill: studiolocal-install

## Quando usar
- Usuário digita `/studiolocal-install` ou pede "instala o StudioLocal".
- Um comando do CLI respondeu `StudioLocal não instalado em <root>`, ou `studiolocal root` diz `tracker: ausente`.

**Não acione porque a pasta atual não tem `.studiolocal/`.** O estado é global e único por máquina, e a pasta onde a pessoa abriu o terminal não diz nada sobre estar instalado ou não. Foi esse gatilho que produziu banco duplicado, um por pasta, com o custo do mês repartido entre eles sem ninguém perceber.

## O que fazer

1. **Ver o CLI e o root**:
   ```bash
   studiolocal root
   ```
   Ele diz qual data root está em uso, de onde veio essa decisão (default, `--root`, `STUDIOLOCAL_ROOT` ou `STUDIO_DATA_ROOT`) e se o `tracker.db` já existe. Se o tracker já existe, não há o que instalar: diga qual é o root e pule para o passo 5.

   Se `studiolocal` não estiver no PATH, o StudioLocal não está instalado nesta máquina, e a saída depende de como a pessoa recebeu: quem usa o pacote do mK AI Studio roda o instalador dele (`Instalar AI Studio`), e quem tem o clone do repo roda `bash scripts/install.sh` de dentro dele. **Não presuma caminho de disco**: o repo não fica no mesmo lugar em toda máquina.

2. **Anunciar o modo de credencial**, em PT-BR direto. O root é global, mas a credencial continua em cascata a partir do PWD, e é isso que muda de pasta para pasta:
   - Se há `.envmk`, `.env` ou `CLAUDE.md` no PWD: "Modo **embedded**: credencial herdada do `.envmk`/`.env` desta pasta."
   - Senão: "Modo **standalone**: a credencial vem do `.env` do root global, que você precisa preencher."

3. **Pedir confirmação** dizendo o que de fato acontece:
   "Vou preparar o root global em `<root do passo 1>`: `tracker.db`, pastas e migrations. Nada é criado nesta pasta. Quer também o bloco `<!-- studiolocal -->` no `CLAUDE.md` daqui?"

   O `CLAUDE.md` só é tocado quando pedem, e aí via `--claude-md <dir>`. Sem a flag o comando não escreve em arquivo versionado de outro repo.

4. **Executar**:
   ```bash
   studiolocal install                  # só o root global
   studiolocal install --claude-md .    # root global + bloco no CLAUDE.md desta pasta
   ```

   O próprio comando imprime o schema do `tracker.db`, as pastas criadas, o data root em uso e o modo de credencial. Se ele disser que adotou uma instalação antiga, repasse os números: é histórico de custo vindo da pasta antiga.

5. **Próximo passo**: pergunte "Quer criar o primeiro project?"
   - Sim → invoque `/studio-project`.
   - Não → fim.

## Notas

- **NUNCA** reaplique sobre um root que já tem `tracker.db` sem `--force` explícita.
- O bloco no CLAUDE.md é fenced (`<!-- studiolocal:start -->` ... `<!-- studiolocal:end -->`) — se já existe, é substituído por completo, preservando edições manuais fora do bloco.
- Em modo standalone, lembre o user de preencher o `.env` do root global com a chave do provider que ele vai usar (`GEMINI_API_MKAIS_WORKBENCH`, `FAL_KEY`, `HF_API_KEY` + `HF_API_SECRET`). `studiolocal models` mostra quais providers já têm credencial aqui.
- Instalação antiga por pasta (`<pasta>/.studiolocal/`): o `install` adota sozinho quando há um candidato só. Com dois ou mais ele para e pede `studiolocal db adopt --primary <caminho>`, porque escolher sozinho é escolher em qual banco o dinheiro dos outros fica registrado.
- Migration pendente é aplicada no primeiro comando seguinte, com backup do banco antes. Não existe passo manual de migração depois de um `studiolocal update`.