Nixos-Config/AGENTS.md

# AGENTS.md

Guia operacional para agentes trabalhando neste repositorio.

Este arquivo deve refletir o estado atual do repo. Se a estrutura mudar, atualize este documento junto.

## Objetivo do repo

- Este repo contem a configuracao pessoal de NixOS e Home Manager da maquina `Nixos`.
- O setup e especifico para o usuario `ltadeu6` e para os hosts versionados neste repo; nao trate este repo como template generico sem adaptar usuario, host, mounts, rede e segredos.
- O flake principal gera `nixosConfigurations.Nixos` e `nixosConfigurations.NixOracle`.
- O Home Manager esta embutido no modulo NixOS; nao existe fluxo separado de `home-manager switch`.

## Regras gerais para agentes

- Priorize mudancas pequenas, simples e revisaveis.
- Nao edite `hosts/Nixos/hardware-configuration.nix` sem pedido explicito.
- Nao imprima segredos, tokens, chaves, conteudo de arquivos `.age` ou valores vindos de `/run/agenix/*`.
- Prefira editar a fonte de verdade declarativa, nao o arquivo gerado em `~/.config`, `/etc` ou `/run`.
- Se um comportamento e gerado por Home Manager ou NixOS, altere o modulo que gera o arquivo, nao o arquivo final.
- Ao adicionar servicos, habilite apenas o necessario e documente dependencias novas neste arquivo.
- Antes de remover um arquivo de `configs/`, confirme se ele ainda e referenciado por `home/ltadeu6.nix` ou `hosts/Nixos/configuration.nix`.

## Mapa rapido do repo

- `flake.nix`: entrada principal do flake, inputs e wiring dos modulos.
- `flake.lock`: lockfile dos inputs do flake.
- `hosts/Nixos/configuration.nix`: modulo principal do sistema.
- `hosts/Nixos/hardware-configuration.nix`: hardware, filesystem e driver de video; gerado pelo NixOS.
- `hosts/NixOracle/configuration.nix`: modulo minimo do VPS `NixOracle`.
- `hosts/NixOracle/hardware-configuration.nix`: placeholder para o hardware do VPS; substitua pelo gerado no host.
- `home/ltadeu6.nix`: modulo principal do Home Manager do usuario.
- `home/openclaw.nix`: modulo opcional do OpenClaw; so entra se `enableOpenClaw = true` em `flake.nix`.
- `configs/hypr/`: fontes de verdade do Hyprland e asset do wallpaper.
- `configs/waybar/`: configs e scripts do Waybar.
- `configs/doom/`: configuracao do Doom Emacs versionada no repo.
- `configs/home-assistant/`: scripts auxiliares consumidos por servicos do host para alimentar o Home Assistant.
  - `configs/home-assistant/codex_status.py`: exportador do status web do Codex/ChatGPT para o Home Assistant, com fallback para logs locais.
  - `configs/home-assistant/ui-lovelace.yaml`: dashboard principal do Home Assistant em YAML.
- `configs/wofi/`: configuracao e tema do launcher Wofi.
- `hosts/Nixos/libvirt/`: XMLs versionados de VMs locais usadas no host `Nixos`.
- `secrets/secrets.nix`: regras do agenix.
- `secrets/*.age`: segredos criptografados.
- `deploy-oracle.sh`: script de deploy do NixOracle com snapshot automatica pre-deploy.
- `openclaw/documents/`: documentos consumidos pelo modulo opcional do OpenClaw.
- `.codex/`: metadata local de ferramentas/agentes; nao faz parte da configuracao do sistema.
- `README.md`: resumo humano do repo; o `AGENTS.md` deve ser mais preciso para trabalho automatizado.

## Inputs do flake e dependencias externas

### Inputs declarados em `flake.nix`

- `nixpkgs`: canal principal `nixos-25.11`.
- `nixpkgs-unstable`: canal `nixos-unstable`, exposto via overlay como `pkgs.unstable`.
- `home-manager`: `release-25.11`, seguindo o `nixpkgs` principal.
- `agenix`: gerenciamento de segredos.
- `nix-openclaw`: overlay e modulo opcional do OpenClaw.

### Como o flake e montado hoje

- O sistema alvo e `x86_64-linux`.
- A flag local `enableOpenClaw` esta `false` em `flake.nix`.
- Mesmo com `home/openclaw.nix` e `openclaw/documents/` no repo, eles nao entram na avaliacao enquanto `enableOpenClaw` continuar `false`.
- O overlay injeta:
  - `nix-openclaw.overlays.default`
  - override em `openclaw`
  - override em `openclaw-gateway`
  - `pkgs.unstable`

## Fonte de verdade por area

### Sistema

- Fonte principal: `hosts/Nixos/configuration.nix`
- Nao edite arquivos em `/etc`, `/run/current-system`, `/run/agenix` ou servicos gerados; todos sao outputs.

### Hardware

- Fonte principal: `hosts/Nixos/hardware-configuration.nix`
- Este arquivo contem mounts e driver de video. Caminhos absolutos ali sao esperados e nao devem ser "corrigidos" sem pedido explicito.

### Home Manager

- Fonte principal: `home/ltadeu6.nix`
- O Home Manager publica arquivos em `~/.config` a partir de `configs/` ou gera alguns deles inline.

### Libvirt / GNOME Boxes

- `hosts/Nixos/libvirt/win11-3.xml` registra a VM Windows 11 usada pelo GNOME Boxes.
- A VM deve permanecer em `qemu:///session`; migrar para `qemu:///system` faz ela sair do fluxo normal do GNOME Boxes.
- A interface de rede da VM usa `type='bridge'` com `source bridge='virbr0'` para dar IP em `192.168.122.0/24` e permitir SSH direto do host.
- Nao reintroduza `passt` ou `portForward` nesse XML sem um motivo explicito; a configuracao atual depende de `qemu-bridge-helper` e de `/etc/qemu/bridge.conf` permitindo `virbr0`.
- Para aplicar alteracoes nesse XML: `virsh --connect qemu:///session define hosts/Nixos/libvirt/win11-3.xml`.

### Hyprland / wallpaper

- `configs/hypr/hyprland.conf` e a fonte de verdade do Hyprland.
- `configs/hypr/nixos.png` e o asset versionado do wallpaper.
- `~/.config/hypr/hyprpaper.conf` NAO existe no repo; ele e gerado inline por `home/ltadeu6.nix`.
- `~/.config/hypr/nixos.png` tambem e publicado pelo Home Manager a partir de `configs/hypr/nixos.png`.
- `~/.config/hypr/scripts/screenshot-active-window.sh` e gerado inline por `home/ltadeu6.nix`.
- O comentario de cabecalho "AUTOGENERATED HYPR CONFIG" em `configs/hypr/hyprland.conf` e legado; apesar disso, o arquivo versionado no repo e a fonte real.

### Waybar

- Fontes de verdade:
  - `configs/waybar/config`
  - `configs/waybar/style.css`
  - `configs/waybar/dracula.css`
  - `configs/waybar/air_control.py`
  - `configs/waybar/launch.sh`
  - `configs/waybar/switch_sink.sh`
  - `configs/waybar/spotify_status.sh`
- Esses arquivos sao publicados em `~/.config/waybar/` pelo Home Manager.

### Doom Emacs

- Fontes de verdade:
  - `configs/doom/config.el`
  - `configs/doom/init.el`
  - `configs/doom/packages.el`
- Nao existe `configs/doom/config.org` no estado atual do repo.
- `configs/doom/custom.el` nao e versionado; trate customizacoes locais geradas pelo Emacs como fora do escopo do repo.

### Wofi

- Fontes de verdade:
  - `configs/wofi/config`
  - `configs/wofi/style.css`
  - `configs/wofi/menu`
  - `configs/wofi/menu.css`

### OpenClaw

- `home/openclaw.nix` e a fonte do modulo Home Manager do OpenClaw.
- `openclaw/documents/` so importa quando `enableOpenClaw = true`.
- Nao altere `openclaw/documents/` achando que isso afetara o sistema atual sem antes verificar se o modulo esta habilitado.

### Ollama / modelos locais

- Fonte principal: `services.ollama` em `hosts/Nixos/configuration.nix`.
- Modelos sincronizados hoje:
  - `gemma4:e4b`
  - `gpt-oss:20b`
  - `qwen2.5-coder:7b`
- `gpt-oss:20b` e o candidato preferido para testar agentes executores locais.
- `qwen2.5-coder:7b` pode funcionar para chat/codigo, mas mostrou baixa confiabilidade para tool-calling em agentes.

## Estrutura funcional atual

### `hosts/Nixos/configuration.nix`

Este modulo concentra:

- Variaveis locais do host:
  - `username = "ltadeu6"`
  - `homeDir = "/home/${username}"`
- `agenix`:
  - identidade em `${homeDir}/.ssh/id_ed25519`
  - segredos opcionais via `builtins.pathExists`
- `nix.settings`:
  - `nix-command`
  - `flakes`
  - `auto-optimise-store`
  - cache CUDA extra
- boot:
  - `systemd-boot`
  - Plymouth
  - kernel params silenciosos
  - `vhba`
- rede:
  - host `Nixos`
  - `networkmanager`
  - firewall desabilitado
  - IP estatico em `enp4s0`
  - gateway e DNS fixos
  - `extraHosts` com alias `vps`
  - bloco WireGuard comentado
- locale:
  - timezone `America/Sao_Paulo`
  - locale `pt_BR.UTF-8`
  - keymap `br-abnt2`
- programas habilitados:
  - `cdemu`
  - `gamescope`
  - `virt-manager`
  - `gnupg.agent`
  - `nautilus-open-any-terminal`
  - `fish`
  - `hyprland`
  - `neovim`
  - `nix-ld`
  - `dconf`
  - `kdeconnect`
  - `steam`
  - `starship`
  - `java`
  - `htop`
  - `git`
  - `gamemode`
  - `firefox`
  - `adb`
- servicos habilitados:
  - `fstrim`
  - `home-assistant`
  - `dbus`
  - `displayManager.gdm`
  - `gvfs`
  - `gnome.gnome-keyring`
  - `udisks2`
  - `flatpak`
  - `openssh`
  - `emacs`
  - `printing`
  - `pipewire`
- servicos atualmente declarados mas desabilitados:
  - `mysql`
  - `terraria`
  - `minecraft-server`
  - `jupyterhub`
- audio e input:
  - `services.pulseaudio.enable = false`
  - `pipewire` com ALSA, Pulse e JACK
  - `security.rtkit.enable = true`
  - `hardware.uinput.enable = true`
  - `hardware.bluetooth.enable = true`
- automacoes do sistema:
  - perfil `/etc/profile.d/openai.sh`
  - perfil `/etc/profile.d/openclaw.sh`
  - `nix-flake-update` timer/service
  - `flatpak-update` timer/service
  - `nix.gc` semanal
- usuario:
  - `users.users.ltadeu6`
  - grupos: `terraria`, `mysql`, `networkmanager`, `wheel`, `storage`
  - shell `fish`
- virtualizacao:
  - `libvirtd.enable = true`
  - `docker = false`
  - `waydroid = false`
- desktop infra:
  - fontes Nerd Fonts
  - `xdg.portal` com portal GTK
  - `allowUnfree = true`

### Notas importantes sobre `configuration.nix`

- `services.transmission` e `services.syncthing` foram removidos; nao reintroduza sem pedido explicito.
- Os segredos do Syncthing tambem foram removidos do repo.
- O servico `nix-flake-update` nao depende mais de path absoluto fixo do checkout; ele busca um repo sob `$HOME` contendo `hosts/Nixos/configuration.nix`.
- `nix-flake-update` faz:
  - `nix flake update --commit-lock-file`
  - `nixos-rebuild switch --flake "$repo_dir#Nixos"`
  - somente se o repo estiver limpo exceto por `flake.lock`

## Estrutura do Home Manager (`home/ltadeu6.nix`)

Este modulo concentra:

- identidade do usuario:
  - `home.username = "ltadeu6"`
  - `home.homeDirectory = "/home/ltadeu6"`
  - `home.stateVersion = "25.11"`
- programas/configs gerenciados:
  - `kitty`
  - `dunst`
  - `gtk`
  - cursor `Breeze`
  - `xdg.mimeApps`
  - `xdg.userDirs`
  - `spotifyd`
  - `programs.home-manager.enable = true`
- session variables:
  - `MANPAGER`
  - `HYPRCURSOR_THEME`
  - `HYPRCURSOR_SIZE`
  - `QT_QPA_PLATFORMTHEME`
- ativacao custom:
  - `home.activation.ociCredentials`
  - cria `~/.oci/` e symlinks `key.pem` e `config` para `/run/agenix/oci_key` e `/run/agenix/oci_config`
  - `home.activation.openclawGatewayEnv`
  - gera `~/.config/openclaw/gateway.env` a partir de `/run/agenix/openclaw_gateway_token`

### Arquivos publicados/gerados pelo Home Manager

- Hypr:
  - publica `configs/hypr/hyprland.conf`
  - gera `~/.config/hypr/hyprpaper.conf`
  - publica `configs/hypr/nixos.png`
  - gera `~/.config/hypr/scripts/screenshot-active-window.sh`
- Hyfetch:
  - gera `~/.config/hyfetch.json`
- Waybar:
  - publica `config`, `style.css`, `dracula.css`
  - publica `air_control.py`
  - publica `spotify_status.sh`
  - publica `launch.sh`
  - publica `switch_sink.sh`
- Doom:
  - publica `config.el`, `init.el`, `packages.el`
- Wofi:
  - publica `config`, `style.css`, `menu`, `menu.css`

### Dependencias de `home.packages`

Nao replique toda a lista daqui em outras docs; a fonte de verdade e `home/ltadeu6.nix`.

Pacotes de sessao e desktop usados diretamente pelos configs:

- `waybar`
- `hyprpaper`
- `wofi`
- `pavucontrol`
- `playerctl`
- `jq`
- `grim`
- `slurp`
- `wl-clipboard`
- `networkmanager`
- `hyprpicker`
- `papirus-icon-theme`
- `mpv`
- `evince`
- `ripgrep`

Pacotes relevantes para trabalho/dev presentes no estado atual:

- `unstable.codex`
- `opencode` empacotado via Home Manager com `libstdc++.so.6` no `LD_LIBRARY_PATH`
- `vscode`
- `clang-tools`
- `nodejs`
- `stylelint`
- `html-tidy`
- `shfmt`
- `shellcheck`
- `black`
- `isort`
- `pipenv`
- `nixfmt-classic`
- `fd`
- `tmux`
- `texlab`

Pacotes de uso geral e apps pesados presentes:

- `tor-browser`
- `libreoffice`
- `gimp`
- `inkscape`
- `blender`
- `discord-ptb`
- `android-studio`
- `gnome-boxes`
- `prismlauncher`
- `sageWithDoc`

Para lista completa, consulte diretamente `home.packages`.

## Arquivos e comportamento por aplicacao

### Hyprland

Arquivo principal:

- `configs/hypr/hyprland.conf`

Comportamentos importantes:

- Define dois monitores por descricao:
  - LG ultrawide em alta taxa de refresh
  - monitor lateral `STD Computer Inc LED`
- Autostart:
  - `waybar`
  - `hyprpaper`
  - `dbus-launch kdeconnect-indicator`
  - `antimicrox` com perfil em `/etc/antimicrox/controller-mouse.amgp`
  - shell snippet que usa `hyprctl`, `jq` e `xrandr` para forcar monitor primario
- Launcher:
  - usa `wofi --show drun`
- Screenshots:
  - area via `grim` + `slurp`
  - tela inteira via `grim`
  - janela ativa via script gerado pelo Home Manager
- Workspaces:
  - workspaces `1..9` no monitor ultrawide
  - workspace `10` no monitor lateral
- Regras especiais:
  - Steam e jogos Proton na workspace 4
  - Emacs na workspace 2
- Multimedia keys:
  - dependem de `playerctl`

Cuidados:

- O autostart assume disponibilidade de `dbus-launch`, `kdeconnect-indicator`, `hyprctl`, `jq` e `xrandr`.
- Se alterar nomes/descricoes de monitor, ajuste tanto os `monitor = ...` quanto o snippet que detecta a saida primaria.

### Hyprpaper

- O wallpaper e controlado por `home/ltadeu6.nix`, nao por um arquivo `configs/hypr/hyprpaper.conf`.
- O runtime usa `~/.config/hypr/nixos.png`, publicado a partir de `configs/hypr/nixos.png`.
- Se trocar a imagem do wallpaper, prefira substituir `configs/hypr/nixos.png` ou ajustar o source em `home/ltadeu6.nix`.

### Waybar

Arquivos principais:

- `configs/waybar/config`
- `configs/waybar/style.css`
- `configs/waybar/dracula.css`
- `configs/waybar/air_control.py`
- `configs/waybar/launch.sh`
- `configs/waybar/switch_sink.sh`
- `configs/waybar/spotify_status.sh`

Modulos relevantes:

- `hyprland/workspaces`
- `cava`
- `custom/ac`
- `clock`
- `custom/spotify`
- `network`
- `bluetooth`
- `pulseaudio`
- `backlight`
- `battery`
- `custom/poweroff`

Dependencias e assumptions do Waybar:

- `custom/spotify` depende de `spotifyd` e `playerctl`.
- `pulseaudio` usa `pavucontrol` e `pactl`.
- `bluetooth` chama `bluetoothctl`.
- `custom/ac` executa `~/.config/waybar/air_control.py`.
- Os botoes de lock chamam `hyprlock`.

Cuidados:

- `configs/waybar/config` referencia `hyprlock`, `bluetoothctl` e o modulo `cava`.
- Nem toda dependencia usada no runtime aparece perto do arquivo que a consome; verifique `home.packages`, `environment.systemPackages` e os servicos do sistema antes de alterar comandos.

### Waybar AC / Home Assistant

Arquivo principal:

- `configs/waybar/air_control.py`

Regras atuais:

- Usa apenas stdlib Python:
  - `urllib`
  - `json`
  - `fcntl`
  - etc.
- Nao depende de `requests`, apesar de `python3Packages.requests` existir em `home.packages`.
- Fala com Home Assistant em `http://localhost:8123`.
- Controla a entidade `climate.ar`.
- Le token em `~/.config/secrets/ha_token`.
- Usa debounce e estado local em `~/.cache`.
- Arquivos de cache:
  - `~/.cache/waybar_air_state.json`
  - `~/.cache/waybar_air_state.lock`
- Regras de UX:
  - alteracoes de setpoint/modo/fan aparecem primeiro na UI
  - envio real e atrasado por debounce
  - `fan_only` e `dry` mostram temperatura atual do ambiente
  - fan speed aparece como indicador pequeno/subscrito

### Spotify no Waybar

Arquivo principal:

- `configs/waybar/spotify_status.sh`

Regras atuais:

- Descobre o player com `playerctl -l | rg '^spotifyd\.instance'`.
- Mostra artista + titulo.
- Usa um icone para `Playing` e outro para `Paused`.
- So faz sentido se `services.spotifyd.enable = true`, o que esta habilitado hoje em `home/ltadeu6.nix`.

### Doom Emacs

Arquivos principais:

- `configs/doom/init.el`
- `configs/doom/config.el`
- `configs/doom/packages.el`

Estado atual:

- `init.el` habilita uma lista longa de modulos Doom, incluindo:
  - `vertico`
  - `corfu`
  - `treemacs`
  - `vterm`
  - `lsp`
  - linguagens como `cc`, `ess`, `gdscript`, `json`, `java`, `javascript`, `kotlin`, `latex`, `nix`, `org`, `python`, `qt`, `rust`, `sh`, `web`, `yaml`
- `packages.el` adiciona:
  - `org-ref`
  - `vue-mode`
  - `kivy-mode`
  - `treemacs-all-the-icons`
- `config.el` contem:
  - identidade do usuario
  - tema Dracula
  - fontes FiraCode Nerd Font Mono
  - ajustes de LSP/clangd
  - integracao com `org-ref`
  - configuracao de PDF tools
  - classe `abntex2` para LaTeX
  - dashboard customizado

Cuidados:

- Se alterar modulos ou `packages.el`, normalmente e preciso rodar `doom sync` fora do fluxo Nix.
- Nao documente `config.org` ou `custom.el` como fonte de verdade; esses arquivos nao sao parte ativa do repo atual.

### Wofi

Arquivos principais:

- `configs/wofi/config`
- `configs/wofi/style.css`
- `configs/wofi/menu`
- `configs/wofi/menu.css`

Estado atual:

- `config` define um launcher `drun` centralizado com prompt `Buscar...`.
- `menu` parece ser config auxiliar para `wofi-wifi-menu`.
- Tema usa Fira Code Nerd Font e paleta no estilo Dracula.

### OpenClaw

Arquivo principal:

- `home/openclaw.nix`

Estado atual:

- O modulo esta presente, mas desligado pelo gate `enableOpenClaw = false` em `flake.nix`.
- Quando habilitado, ele:
  - liga `programs.openclaw`
  - usa `../openclaw/documents`
  - configura gateway local
  - busca token em `OPENCLAW_GATEWAY_TOKEN`
  - aponta o provider Ollama para `http://127.0.0.1:11434`
  - usa modelo `ollama/gemma4:e4b`

## Secrets e variaveis de ambiente

### Segredos versionados hoje

- `secrets/openai_api_key.age`
- `secrets/openclaw_gateway_token.age`
- `secrets/forgejo_api_token.age`
- `secrets/android_release_keystore.age`
- `secrets/android_release_store_password.age`
- `secrets/android_release_key_password.age`
- `secrets/matrix_android_firebase_service_account.age`
- `secrets/matrix_android_google_services.age`
- `secrets/matrix_android_commander_credentials.age`
- `secrets/cloudflare_worker_api_token.age`
- `secrets/cloudflare_dns_api_token.age`
- `secrets/minecraft_rcon_password.age`
- `secrets/wireguard_private_key.age`
- `secrets/oci_key.age`
- `secrets/oci_config.age`

### Regras do agenix

- Fonte de verdade: `secrets/secrets.nix`
- Nunca grave segredo em texto puro no repo.
- Se adicionar novo `.age`, atualize `secrets/secrets.nix` e o consumo correspondente no modulo Nix.

### Exposicao em runtime

- `fish.shellInit` exporta:
  - `OPENAI_API_KEY`
  - `OPENCLAW_GATEWAY_TOKEN`
  - `FORGEJO_API_TOKEN`
- `/etc/profile.d/openai.sh`, `/etc/profile.d/openclaw.sh` e `/etc/profile.d/forgejo.sh` fazem o mesmo para shells de login.
- O token do Home Assistant do Waybar AC NAO esta sob agenix neste repo; ele e lido diretamente de `~/.config/secrets/ha_token`.

### Android signing

- A chave de assinatura Android para distribuicao fora da Play Store fica em `secrets/android_release_keystore.age`.
- As senhas ficam em `secrets/android_release_store_password.age` e `secrets/android_release_key_password.age`.
- O alias padrao da chave e `release`.
- O helper `android-signing-env` exporta `ANDROID_KEYSTORE_PATH`, `ANDROID_KEYSTORE_TYPE`, `ANDROID_KEY_ALIAS`, `ANDROID_KEYSTORE_PASSWORD`, `ANDROID_KEY_PASSWORD` e `PUSH_GATEWAY_URL` apenas para o comando filho.
- `PUSH_GATEWAY_URL` aponta para `https://matrix-push-gateway.ltadeu6.workers.dev`.
- Use `android-signing-env ./gradlew assembleRelease` ou `android-signing-env ./gradlew bundleRelease`; nao exporte essas senhas globalmente.
- Secrets locais do projeto `matrix-android` tambem ficam sob agenix:
  - `matrix_android_firebase_service_account` materializa `.secrets/firebase-service-account.json`.
  - `matrix_android_google_services` materializa `app/google-services.json`.
  - `matrix_android_commander_credentials` materializa `.mc/credentials.json`.
- O helper `matrix-android-secrets [project-dir]` cria symlinks desses tres arquivos para `/run/agenix`; por default usa o diretorio atual.
- Nao migre `local.properties`, debug keystores, `.gradle`, `.wrangler` ou caches locais do `matrix-android` para este repo sem um motivo explicito.

### Cloudflare

- `secrets/cloudflare_worker_api_token.age` contem um token para deploy de Workers no account local.
- `secrets/cloudflare_dns_api_token.age` contem um token para DNS/Zone Read.
- `cloudflare-worker-env <comando>` exporta `CLOUDFLARE_API_TOKEN` apenas para o comando filho usando o token de Workers.
- `cloudflare-dns-env <comando>` exporta `CLOUDFLARE_API_TOKEN` apenas para o comando filho usando o token de DNS.
- O token bootstrap usado para criar outros tokens foi temporario; nao reintroduza `cloudflare_bootstrap_api_token.age` no repo. Se outro bootstrap for criado, use apenas para emitir tokens menores, revogue em seguida e remova o `.age` local.

## Dependencias implicitas e pontos de atencao

Itens que um agente deve verificar antes de mexer:

- `hyprlock` e chamado pelo Waybar, mas nao aparece explicitamente perto do modulo que o consome.
- `xrandr` e chamado por `configs/hypr/hyprland.conf`; confirme disponibilidade antes de trocar esse fluxo.
- `dbus-launch` e `kdeconnect-indicator` sao usados no autostart do Hyprland.
- `bluetoothctl` e usado por Waybar.
- `playerctl` e usado tanto no Hyprland quanto no Waybar.
- `pactl` e necessario para `configs/waybar/switch_sink.sh`.
- `Home Assistant` local e `~/.config/secrets/ha_token` sao dependencias externas do controle de ar.
- `open-webui` depende do `ollama` configurado no host.
- `OLLAMA_CONTEXT_LENGTH` esta em `64000`; reduzir para 8k quebra prompts grandes de agentes com schemas de ferramentas.

### Home Assistant / Codex status

Arquivo principal:

- `configs/home-assistant/codex_status.py`

Estado atual:

- O host exporta preferencialmente o status web do Codex/ChatGPT a partir da sessao autenticada do navegador em `~/.zen/.../cookies.sqlite`, usando o container pessoal (`userContextId=1`) para buscar `/api/auth/session` e `/backend-api/wham/usage`.
- Se a sessao web nao estiver disponivel, o exporter faz fallback para `~/.codex/sessions/.../*.jsonl`.
- O export e feito pelo timer `codex-status-export`, que gera `/var/lib/hass/codex_status.json`.
- O Home Assistant le esse JSON via sensores `command_line`.
- Sensores expostos hoje:
  - `sensor.codex_5h_left`
  - `sensor.codex_5h_reset`
  - `sensor.codex_5h_reset_formatted`
  - `sensor.codex_weekly_left`
  - `sensor.codex_weekly_reset`
  - `sensor.codex_weekly_reset_formatted`

Cuidados:

- Nao tente obter esses dados via API de billing da OpenAI sem necessidade; o estado atual usa a sessao web do ChatGPT/Codex e mantem fallback local.
- Se mudar de perfil/container no Zen, ajuste `CHATGPT_COOKIE_DB` ou `CHATGPT_COOKIE_CONTEXT_PREFIX` no exporter antes de assumir que a coleta web continuara funcionando.
- Se mover a origem dos logs do Codex, ajuste `CODEX_SESSION_ROOT` no servico `codex-status-export`.
- O dashboard do Home Assistant continua em storage mode; a fonte declarativa aqui cobre os sensores, nao os cards da UI.

### Home Assistant / secagem de roupas

Fonte principal:

- `services.home-assistant.config` em `hosts/Nixos/configuration.nix`

Estado atual:

- O helper `input_boolean.secar_roupas` e declarado pelo repo.
- A automacao `secar_roupas_start` inicia o script ao ligar o helper.
- A automacao `secar_roupas_stop` desliga `climate.ar` ao desligar o helper.
- O script `script.secar_roupas_com_ar_condicionado` usa `climate.ar`.
- As dashboards `ui-lovelace.yaml` e `ui-overview.yaml` exibem um botao para alternar `input_boolean.secar_roupas`.
- A temperatura vem de `state_attr('climate.ar', 'current_temperature')`; nao ha sensor de umidade dedicado.
- A estrategia alterna aquecimento moderado para evaporar agua das roupas e `cool`/`dry` para condensar e drenar a umidade.
- No inicio, se a sala estiver abaixo de 24 C, o script usa `heat` com setpoint 25 C ate chegar em 25 C, segura ate 5 minutos se ainda estiver abaixo de 27 C, e tem timeout maximo de 15 minutos.
- Durante o loop, abaixo de 21 C o script usa `heat` com setpoint 24 C ate chegar em 24 C, segura ate 5 minutos se ainda estiver abaixo de 26 C, e tem timeout maximo de 20 minutos.
- Entre 23 C e 28 C, o script usa pulsos planejados de `cool` com setpoint 22 C por ate 15 minutos, depois volta para `dry` por ate 40 minutos.
- Acima de 28 C, o script nunca aquece; usa `cool` com setpoint 23 C por ate 20 minutos e depois `dry`.
- O tempo maximo de execucao e 6 horas; ao expirar, o script desliga `climate.ar` e desliga `input_boolean.secar_roupas`.
- Fan mode e definido apenas se o valor existir em `state_attr('climate.ar', 'fan_modes')`; a integracao atual aceita niveis numericos `1..5`.
- O script usa fan `3` no `dry`, fan `4` no `cool` e fan `5` no `heat`, sempre com fallback para um nivel abaixo.
- Apos trocar `hvac_mode`, o script espera 10 segundos antes de setpoint/fan para evitar comandos rejeitados durante `POWER_ON`.

Cuidados:

- Se trocar a entidade do ar, atualize `haAirConditioner` no `let` de `hosts/Nixos/configuration.nix`.
- Se trocar o helper, atualize `haLaundryDryingToggle` no mesmo `let`.
- Nao mova essa logica para arquivos em `/var/lib/hass` ou pela UI sem refletir a mudanca no repo.

### Home Assistant / dashboard do Codex

Arquivo principal:

- `configs/home-assistant/ui-lovelace.yaml`
- `configs/home-assistant/ui-overview.yaml`

Estado atual:

- A dashboard principal `Home` e declarativa e vem de `ui-lovelace.yaml`.
- Os recursos custom do Lovelace sao declarados em `services.home-assistant.config.lovelace.resources`.
- O painel do Codex existe na dashboard principal `Home` e tambem na dashboard extra `Visão Geral`.
- O painel escolhido para o Codex e o minimalista.

Dependencias visuais atuais:

- `lovelace-mushroom`
- `button-card`

Cuidados:

- Se algum desses recursos nao estiver instalado no HACS, a dashboard pode abrir com erro de `custom element doesn't exist`.
- Mudancas pela UI na dashboard principal nao sao a fonte de verdade; o repo sobrescreve `ui-lovelace.yaml`.
- Recursos Lovelace relevantes devem ser mantidos na configuracao declarativa, nao apenas pela UI.

## Arquivos gerados que NAO devem ser editados diretamente

- `~/.config/hypr/hyprpaper.conf`
- `~/.config/hypr/nixos.png`
- `~/.config/hypr/scripts/screenshot-active-window.sh`
- `~/.config/hyfetch.json`
- `~/.config/openclaw/gateway.env`
- `~/.oci/config` (symlink para `/run/agenix/oci_config`)
- `~/.oci/key.pem` (symlink para `/run/agenix/oci_key`)
- `/etc/antimicrox/controller-mouse.amgp`
- `/etc/antimicrox/player-toggle.sh`
- `/etc/antimicrox/disable-controller.sh`
- `/etc/profile.d/openai.sh`
- `/etc/profile.d/openclaw.sh`

## Comandos uteis

### Deploy NixOracle (com snapshot automatica)

- `./deploy-oracle.sh`
- Requer `~/.oci/` configurado (gerado automaticamente pelo Home Manager apos rebuild local).
- Cria snapshot incremental do boot volume antes de cada deploy, mantendo no maximo 4.

### Rebuild / apply

- `sudo nixos-rebuild switch --flake .#Nixos`
- NixOracle: `nixos-rebuild switch --flake .#NixOracle --target-host root@tadix.dev` (ou via `./deploy-oracle.sh`)

### Validacao mais fiel do sistema

- `nix --extra-experimental-features 'nix-command flakes' build --print-out-paths '.#nixosConfigurations."Nixos".config.system.build.toplevel' --no-link`

### Parse basico de sintaxe Nix

- `nix-instantiate --parse hosts/Nixos/configuration.nix`
- `nix-instantiate --parse home/ltadeu6.nix`

### Procura estrutural

- `rg -n 'algum-termo' .`
- `rg --files`

### Doom Emacs

- Se mudar `configs/doom/init.el` ou `configs/doom/packages.el`, pode ser necessario rodar `doom sync`.

## Politica para mudancas

- Mantenha a logica declarativa no arquivo de origem:
  - sistema em `hosts/Nixos/configuration.nix`
  - usuario em `home/ltadeu6.nix`
  - apps em `configs/...`
- Se um arquivo em `configs/` estiver versionado e for publicado por `home.file`, prefira editar esse arquivo.
- Se um arquivo em `~/.config` e gerado via `.text` ou script inline, edite `home/ltadeu6.nix`.
- Nao reintroduza paths absolutos para o checkout do repo; o sistema atual foi limpo para evitar dependencia no local exato do projeto.
- Ao mexer com wallpapers, mantenha o asset dentro do repo ou em caminho controlado pelo Nix/Home Manager.
- Ao mexer com timers/servicos que fazem `git` ou `nix`, considere que o sandbox do agente pode falhar por escrita em cache; isso nao significa que a configuracao Nix esteja errada.

## Estado atual que agentes nao devem contradizer

- `configs/hypr/hyprpaper.conf` nao existe mais no repo como fonte de verdade.
- `Transmission` nao esta configurado no sistema.
- `Syncthing` nao esta configurado no sistema.
- Os secrets do Syncthing foram removidos.
- O OpenClaw continua opcional e desligado por default.
- O wallpaper do Hypr e entregue pelo Home Manager a partir de `configs/hypr/nixos.png`.
- O script `configs/waybar/spotify_status.sh` e a fonte real do status do Spotify no Waybar.

## Commits

- Sempre faca commit das mudancas feitas por agentes antes de encerrar a tarefa, salvo pedido explicito em contrario.
- Use mensagens curtas e descritivas em ingles.
- Se o GPG falhar, prefira desabilitar assinatura naquele commit em vez de bloquear a mudanca.