Add /orient skill for agent onboarding
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
ltadeu6
parent
16b393099a
commit
616f435fcb
1 changed files with 230 additions and 0 deletions
230
.claude/commands/orient.md
Normal file
230
.claude/commands/orient.md
Normal file
|
|
@ -0,0 +1,230 @@
|
|||
# /orient — Guia operacional do nixos-config
|
||||
|
||||
Você está trabalhando no repositório NixOS pessoal de `ltadeu6`. Este guia cobre tudo o que você precisa para operar, modificar e depurar este sistema. **Leia com atenção antes de fazer qualquer mudança.**
|
||||
|
||||
---
|
||||
|
||||
## 1. Fonte de verdade primária
|
||||
|
||||
O arquivo **`AGENTS.md`** na raiz do repo é a documentação canônica e deve ser consultado sempre. Este skill é um complemento de orientação rápida — se houver conflito, o `AGENTS.md` prevalece.
|
||||
|
||||
Se tiver dúvidas adicionais que não estejam aqui nem no `AGENTS.md`, **inspecione o código diretamente**:
|
||||
- `hosts/Nixos/configuration.nix` — sistema local
|
||||
- `hosts/NixOracle/configuration.nix` — VPS Oracle
|
||||
- `home/ltadeu6.nix` — Home Manager
|
||||
- `flake.nix` — entrypoint, inputs, overlays
|
||||
- `secrets/secrets.nix` — mapa de todos os secrets
|
||||
|
||||
Use `rg -n 'termo'` para buscar definições. Leia os arquivos antes de assumir qualquer coisa.
|
||||
|
||||
---
|
||||
|
||||
## 2. Dois sistemas neste flake
|
||||
|
||||
| Sistema | Host | Onde fica | Como fazer deploy |
|
||||
|---------|------|-----------|-------------------|
|
||||
| `Nixos` | máquina local x86_64 | `hosts/Nixos/` | `sudo nixos-rebuild switch --flake .#Nixos` |
|
||||
| `NixOracle` | VPS Oracle Cloud (`tadix.dev`) | `hosts/NixOracle/` | `./deploy-oracle.sh` |
|
||||
|
||||
**Nunca confunda os dois.** Secrets, serviços e hardware são completamente diferentes.
|
||||
|
||||
---
|
||||
|
||||
## 3. Deploy do NixOracle (VPS)
|
||||
|
||||
Sempre use o script de deploy — ele cria uma snapshot antes de cada rebuild:
|
||||
|
||||
```bash
|
||||
./deploy-oracle.sh
|
||||
```
|
||||
|
||||
O script:
|
||||
1. Lê credenciais OCI de `~/.oci/` (gerado automaticamente pelo Home Manager)
|
||||
2. Localiza a instância e o boot volume via API
|
||||
3. Apaga snapshots antigas se houver mais de 4
|
||||
4. Cria nova snapshot incremental
|
||||
5. Roda `nixos-rebuild switch --flake .#NixOracle --target-host root@tadix.dev`
|
||||
|
||||
Se `~/.oci/` não existir, rode um `sudo nixos-rebuild switch --flake .#Nixos` para ativar o `home.activation.ociCredentials`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Secrets e credenciais
|
||||
|
||||
### Como funciona
|
||||
|
||||
- Secrets ficam em `secrets/*.age`, criptografados com `age` usando a chave SSH do usuário.
|
||||
- O `agenix` descriptografa em `/run/agenix/<nome>` na ativação do sistema.
|
||||
- A identidade usada é `~/.ssh/id_ed25519`.
|
||||
- Para adicionar um secret: criptografe com `age`, adicione em `secrets/secrets.nix`, declare em `age.secrets` no `configuration.nix`.
|
||||
|
||||
### Secrets disponíveis hoje
|
||||
|
||||
| Arquivo `.age` | Onde é usado |
|
||||
|---------------|--------------|
|
||||
| `openai_api_key` | `OPENAI_API_KEY` no ambiente (fish + profile.d) |
|
||||
| `openclaw_gateway_token` | `OPENCLAW_GATEWAY_TOKEN` + `~/.config/openclaw/gateway.env` |
|
||||
| `forgejo_api_token` | `FORGEJO_API_TOKEN` no ambiente |
|
||||
| `android_release_keystore` | keystore para assinar APKs |
|
||||
| `android_release_store_password` | senha do keystore |
|
||||
| `android_release_key_password` | senha da chave dentro do keystore |
|
||||
| `matrix_android_firebase_service_account` | `.secrets/firebase-service-account.json` no projeto |
|
||||
| `matrix_android_google_services` | `app/google-services.json` no projeto |
|
||||
| `matrix_android_commander_credentials` | `.mc/credentials.json` no projeto |
|
||||
| `cloudflare_worker_api_token` | deploy de Workers |
|
||||
| `cloudflare_dns_api_token` | leitura de DNS/Zone |
|
||||
| `minecraft_rcon_password` | servidor Minecraft |
|
||||
| `oci_key` | chave privada OCI API → `~/.oci/key.pem` |
|
||||
| `oci_config` | config OCI → `~/.oci/config` |
|
||||
|
||||
### Nunca imprima conteúdo de `/run/agenix/*` ou arquivos `.age`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Como buildar um APK Android
|
||||
|
||||
O projeto Android relevante é o `matrix-android`. O processo exige três coisas:
|
||||
|
||||
### 5a. Credenciais de assinatura
|
||||
|
||||
```bash
|
||||
# Exporta variáveis de ambiente para o processo filho apenas
|
||||
android-signing-env ./gradlew assembleRelease
|
||||
# ou
|
||||
android-signing-env ./gradlew bundleRelease
|
||||
```
|
||||
|
||||
O helper `android-signing-env` expõe:
|
||||
- `ANDROID_KEYSTORE_PATH` → `/run/agenix/android_release_keystore`
|
||||
- `ANDROID_KEYSTORE_TYPE`, `ANDROID_KEY_ALIAS`, `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_PASSWORD`
|
||||
- `PUSH_GATEWAY_URL` → `https://matrix-push-gateway.ltadeu6.workers.dev`
|
||||
|
||||
### 5b. Secrets do projeto (Firebase, google-services, credenciais)
|
||||
|
||||
```bash
|
||||
# No diretório raiz do projeto matrix-android:
|
||||
matrix-android-secrets .
|
||||
```
|
||||
|
||||
Isso cria symlinks de `/run/agenix/` para os paths esperados pelo projeto.
|
||||
|
||||
### 5c. Se faltar alguma ferramenta (Gradle, JDK, etc.)
|
||||
|
||||
Use `nix develop` — veja a seção 8.
|
||||
|
||||
---
|
||||
|
||||
## 6. OCI CLI (Oracle Cloud)
|
||||
|
||||
Para operações na Oracle Cloud:
|
||||
|
||||
```bash
|
||||
nix-shell -p oci-cli --run "oci <comando> --auth api_key"
|
||||
```
|
||||
|
||||
As credenciais ficam em `~/.oci/config` e `~/.oci/key.pem` (symlinks para `/run/agenix/`). Se não existirem, recrie com:
|
||||
|
||||
```bash
|
||||
sudo nixos-rebuild switch --flake .#Nixos
|
||||
```
|
||||
|
||||
Operações comuns:
|
||||
```bash
|
||||
# Listar instâncias
|
||||
nix-shell -p oci-cli --run "oci compute instance list --compartment-id $(awk -F= '/^tenancy/{gsub(/ /,"",$2);print $2}' ~/.oci/config) --auth api_key"
|
||||
|
||||
# Criar snapshot manual
|
||||
nix-shell -p oci-cli --run "oci bv boot-volume-backup create --boot-volume-id <id> --display-name 'manual-backup' --type INCREMENTAL --auth api_key"
|
||||
```
|
||||
|
||||
Limite free tier: **5 snapshots**. Apague antigas antes de criar novas.
|
||||
|
||||
---
|
||||
|
||||
## 7. Serviços no NixOracle (VPS)
|
||||
|
||||
| Serviço | URL | Porta interna |
|
||||
|---------|-----|---------------|
|
||||
| homepage | `tadix.dev` | — |
|
||||
| Forgejo | `git.tadix.dev` | 3000 |
|
||||
| Nextcloud 32 | `nextcloud.tadix.dev` | — |
|
||||
| JupyterLab | `jupyter.tadix.dev` | 8888 |
|
||||
| BioLab (site estático) | `biolab.tadix.dev` | — |
|
||||
|
||||
- SSH: `root@tadix.dev` ou via Tailscale `root@100.64.0.1`
|
||||
- IP público: `204.216.130.111`
|
||||
- Deploy: **sempre via `./deploy-oracle.sh`**
|
||||
|
||||
---
|
||||
|
||||
## 8. Software ausente — use `nix develop` ou `nix-shell`
|
||||
|
||||
Se qualquer ferramenta não estiver disponível no ambiente atual, **não tente instalar globalmente**. Use:
|
||||
|
||||
```bash
|
||||
# Ambiente temporário com um pacote
|
||||
nix-shell -p <pacote> --run "<comando>"
|
||||
|
||||
# Ex: OCI CLI
|
||||
nix-shell -p oci-cli --run "oci ..."
|
||||
|
||||
# Ex: ferramentas de build
|
||||
nix-shell -p gradle jdk21 --run "gradle assembleRelease"
|
||||
|
||||
# Ex: Python com pacotes
|
||||
nix-shell -p python3 python3Packages.requests --run "python3 script.py"
|
||||
|
||||
# Se o projeto tem flake.nix ou shell.nix com devShell:
|
||||
nix develop
|
||||
```
|
||||
|
||||
Pacotes instalados via `nix-shell` não persistem — isso é intencional.
|
||||
|
||||
---
|
||||
|
||||
## 9. Home Manager
|
||||
|
||||
O Home Manager está **embutido no módulo NixOS** — não existe `home-manager switch` separado. Para aplicar mudanças em `home/ltadeu6.nix`:
|
||||
|
||||
```bash
|
||||
sudo nixos-rebuild switch --flake .#Nixos
|
||||
```
|
||||
|
||||
Arquivos em `configs/` são a fonte de verdade para apps — o Home Manager os publica em `~/.config/`. Nunca edite os arquivos em `~/.config/` diretamente.
|
||||
|
||||
---
|
||||
|
||||
## 10. Adicionando serviços ou pacotes
|
||||
|
||||
### No sistema local (`Nixos`)
|
||||
- Pacotes do sistema: `environment.systemPackages` em `hosts/Nixos/configuration.nix`
|
||||
- Pacotes do usuário: `home.packages` em `home/ltadeu6.nix`
|
||||
- Serviços: `services.<nome>.enable = true` em `hosts/Nixos/configuration.nix`
|
||||
|
||||
### No VPS (`NixOracle`)
|
||||
- Edite `hosts/NixOracle/configuration.nix`
|
||||
- Deploy com `./deploy-oracle.sh`
|
||||
|
||||
---
|
||||
|
||||
## 11. Validação antes de rebuild
|
||||
|
||||
```bash
|
||||
# Verifica sintaxe Nix
|
||||
nix-instantiate --parse hosts/Nixos/configuration.nix
|
||||
nix-instantiate --parse home/ltadeu6.nix
|
||||
|
||||
# Build completo sem aplicar (mais lento, mais fiel)
|
||||
nix build --print-out-paths '.#nixosConfigurations."Nixos".config.system.build.toplevel' --no-link
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. Regras invioláveis
|
||||
|
||||
- Nunca edite `hardware-configuration.nix` sem pedido explícito.
|
||||
- Nunca imprima conteúdo de `/run/agenix/*` ou `.age`.
|
||||
- Nunca edite arquivos em `/etc`, `/run`, `~/.config` gerados pelo sistema — edite a fonte Nix.
|
||||
- Nunca faça commit de secrets em texto claro.
|
||||
- Sempre use `./deploy-oracle.sh` para o NixOracle — nunca `nixos-rebuild` direto em produção.
|
||||
- Se não encontrar um pacote, use `nix-shell -p <pacote>` antes de qualquer outra alternativa.
|
||||
Loading…
Add table
Add a link
Reference in a new issue