> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.fpt.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução e Conceitos

> fp-appimage-updater é uma ferramenta CLI rápida e em um único binário para gerenciar AppImages declarativamente por meio de receitas YAML.

fp-appimage-updater é uma ferramenta de CLI escrita em Rust que permite gerenciar, atualizar e integrar AppImages ao desktop inteiramente por meio de arquivos de configuração YAML fornecidos pelo usuário. Ela opera estritamente em espaço de usuário, não requer GUI e é pequena o suficiente para viver ao lado dos seus dotfiles em qualquer sistema Linux - incluindo distribuições imutáveis e atômicas.

## Principais recursos

<CardGroup cols={2}>
  <Card title="Receitas declarativas baseadas em YAML" icon="file-code">
    Defina cada app e sua estratégia de atualização em um arquivo YAML simples. Adicione, remova ou compartilhe apps editando arquivos - sem assistente necessário.
  </Card>

  <Card title="Suporte Multi-plataforma a Forges" icon="git-fork">
    Busque atualizações em releases do **GitHub, GitLab, Gitea ou Forgejo**. Ele detecta automaticamente instâncias auto-hospedadas e suporta substituições de URL de API/web personalizadas.
  </Card>

  <Card title="Links Diretos e Resolvidores de Script" icon="link">
    Busque atualizações via URLs estáticas usando cabeçalhos **ETag/Last-Modified**, ou use **scripts bash** personalizados para cenários complexos de resolução de versão.
  </Card>

  <Card title="Extração Automática de Zip" icon="file-zipper">
    Detecta automaticamente assets `.zip`, extrai a AppImage usando heurísticas integradas (magic bytes ELF ou nome de arquivo) e limpa o arquivo.
  </Card>

  <Card title="Downloads delta via zsync" icon="bolt">
    Quando uma receita de app habilita `zsync`, o atualizador usa seu backend integrado `zsync-rs` para baixar apenas os bytes que mudaram - economizando largura de banda em AppImages grandes.
  </Card>

  <Card title="Operações em Paralelo" icon="arrows-split-up-and-left">
    Os comandos `check` e `update` executam múltiplos apps simultaneamente com limites cientes do provedor para manter lotes grandes rápidos sem atingir rate limits.
  </Card>

  <Card title="Downloads HTTP range segmentados" icon="arrow-down-to-line">
    Arquivos grandes são divididos em requisições HTTP range paralelas quando o servidor oferece suporte. Habilitado por padrão e configurável por app.
  </Card>

  <Card title="Integração de desktop" icon="desktop">
    Extrai manifests `.desktop` exatos e ícones diretamente de cada AppImage e os instala em `~/.local/share/applications`.
  </Card>

  <Card title="Automação em segundo plano com systemd" icon="clock">
    O script de instalação configura um timer systemd que executa verificações e atualizações automaticamente em segundo plano sem intervenção do usuário.
  </Card>

  <Card title="Tokens e proxies da API do GitHub" icon="shield-check">
    Contorne limites de taxa usando tokens de acesso pessoal ou `secrets.yml`. Suporte opcional a proxy de metadados também está disponível para requisições não autenticadas.
  </Card>

  <Card title="Verificações de Saúde Locais (Doctor)" icon="stethoscope">
    O comando `doctor` valida sua configuração local, diretórios necessários, locks de processo e a saúde do seu setup para garantir que tudo esteja rodando sem problemas.
  </Card>

  <Card title="Saída JSON para Scripts" icon="code">
    Cada comando principal suporta uma flag `--json`, fornecendo uma saída estável e legível por máquina para integração em seus próprios scripts ou painéis.
  </Card>
</CardGroup>

## Filosofia de design

fp-appimage-updater é intencionalmente estreito em escopo. Ele é executado inteiramente em espaço de usuário - nenhum acesso root é necessário para uma instalação padrão. A configuração vive em `~/.config/fp-appimage-updater/`, o que o torna uma escolha natural para repositórios de dotfiles. Não há GUI, nem um registro central de receitas, nem um banco de dados: o estado é conduzido puramente por arquivos em disco. Você escreve suas próprias receitas, as mantém onde quiser e a ferramenta fica fora do seu caminho.

<Note>
  O projeto nunca incluirá um repositório de receitas. Espera-se que você escreva e seja dono das suas próprias receitas de app. Para inspiração, confira os [exemplos oficiais](https://gitlab.com/fpsys/fp-appimage-updater/-/tree/main/examples/apps).
</Note>