@danhachuel/thunderbolt 0.2.13

package/MANUAL-INSTALACAO.md

@@ -0,0 +1,513 @@
+# Manual de Instalação — Thunderbolt UI
+
+Este manual descreve a instalação local da UI Thunderbolt, baseada no MoneyPrinterTurbo, utilizando o pacote npm `@danhachuel/thunderbolt`. O fluxo recomendado instala automaticamente o ambiente Python, as dependências da aplicação, as dependências do MoneyPrinterTurbo, o Streamlit e o suporte FFmpeg através de `imageio-ffmpeg`.
+
+> **Versão deste manual:** 0.2.13
+> **Pacote npm:** `@danhachuel/thunderbolt`
+> **Porta padrão da UI:** `localhost:3030`  
+> **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
+
+## 1. O que será instalado
+
+A instalação assistida cria um ambiente local separado para evitar misturar as dependências do Thunderbolt com outros projectos Python.
+
+| Componente | Local ou comportamento padrão |
+|---|---|
+| Python | Python 3.11 ou superior já instalado no sistema |
+| Ambiente virtual | `~/.thunderbolt/.venv` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\\.venv`) |
+| MoneyPrinterTurbo | `~/.thunderbolt/MoneyPrinterTurbo` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\\MoneyPrinterTurbo`) |
+| Storage Thunderbolt | `~/.thunderbolt/storage` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\\storage`) |
+| Dependências Thunderbolt | Instaladas a partir do `requirements.txt` incluído no pacote |
+| Dependências MoneyPrinterTurbo | Instaladas a partir do `requirements.txt` do repositório oficial |
+| Streamlit | Instalado como dependência Python |
+| FFmpeg | Disponibilizado pelo pacote Python `imageio-ffmpeg` |
+| Porta da aplicação | `3030`, configurável com `THUNDERBOLT_PORT` |
+
+A aplicação não instala drivers de GPU, Docker, modelos Whisper ou credenciais externas. As chaves de API do MoneyPrinterTurbo são configuradas na aba **Configurações** e sincronizadas com o `config.toml` do clone local.
+
+O MoneyPrinterTurbo declara Python 3.11 ou superior como requisito e documenta a instalação com `uv` ou com `venv + pip`. A aplicação segue o mesmo princípio e adiciona um instalador assistido próprio.[1]
+
+## 2. Pré-requisitos
+
+Instale os seguintes componentes antes de executar o instalador:
+
+| Pré-requisito | Necessário | Observação |
+|---|---:|---|
+| Python 3.11+ | Sim | No Windows, o instalador tenta instalar automaticamente via winget; noutros sistemas deve estar instalado |
+| npm | Sim | Normalmente vem incluído com Node.js |
+| Node.js 18+ | Sim | Necessário para executar o pacote via `npx` |
+| Git | Sim para instalação automática do MoneyPrinterTurbo | Pode ser evitado usando `--skip-moneyprinter` ou `MONEYPRINTER_PATH` |
+| winget | Recomendado no Windows | Permite ao instalador instalar Python 3.11 automaticamente; vem normalmente com Windows 10/11 actualizado |
+| Internet | Sim durante a instalação | Necessária para npm, GitHub e PyPI |
+| Espaço em disco | Recomendado 5 GB ou mais | Dependências, caches, modelos e artefactos podem ocupar espaço adicional |
+
+A instalação local do MoneyPrinterTurbo recomenda Windows 10+, macOS 11+ ou uma distribuição Linux corrente. Python 3.11 é a opção de referência do projecto base.[1]
+
+### 2.1 Windows: PowerShell bloqueia npx.ps1
+
+Em algumas instalações Windows, o PowerShell bloqueia o wrapper `npx.ps1` por causa da política de execução de scripts. Nesse caso, use `npx.cmd`, que executa o mesmo npm/npx sem depender do wrapper PowerShell:
+
+```powershell
+npx.cmd --yes @danhachuel/thunderbolt install
+npx.cmd --yes @danhachuel/thunderbolt doctor
+npx.cmd --yes @danhachuel/thunderbolt
+```
+
+Se preferir corrigir a política para o seu utilizador:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+Para permitir apenas durante a sessão actual:
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+```
+
+Não é necessário usar `Unrestricted`. Se estiver num terminal MobaXterm ou CMD, também pode executar:
+
+```cmd
+cmd /c npx.cmd --yes @danhachuel/thunderbolt install
+```
+
+### 2.2 Confirmar versões
+
+Linux ou macOS:
+
+```bash
+node --version
+npm --version
+python3 --version
+git --version
+```
+
+Windows PowerShell:
+
+```powershell
+node --version
+npm --version
+py --version
+git --version
+```
+
+O Python deve apresentar a versão `3.11` ou superior. Se estiver no Windows sem Python, o instalador tenta executar automaticamente `winget install --exact --id Python.Python.3.11`. Se `winget` não estiver disponível, instale o App Installer/Microsoft Store ou Python a partir de [python.org](https://www.python.org/downloads/windows/) e repita a instalação. Em macOS/Linux, o instalador não assume permissões administrativas para instalar Python no sistema; instale-o pelo gestor de pacotes ou use `THUNDERBOLT_PYTHON`.
+
+## 3. Instalação recomendada via npx
+
+Execute:
+
+Windows PowerShell ou MobaXterm:
+
+```powershell
+npx.cmd --yes @danhachuel/thunderbolt@0.2.13 install
+```
+
+Linux/macOS:
+
+```bash
+npx --yes @danhachuel/thunderbolt@0.2.13 install
+```
+
+A instalação normal é **segura para actualizações**: preserva `storage`, Blueprints, Brandings, configurações e artefactos do utilizador. Remove apenas `.venv`, o clone técnico do MoneyPrinterTurbo e dependências que serão recriadas. Uma pasta antiga sem dados do utilizador, como `C:\Users\<utilizador>\AppData\Local\hermes` da tentativa incompleta, pode ser removida; uma pasta antiga que contenha Blueprints, Brandings ou storage é preservada e apenas avisada no terminal. Feche processos Python, Node, Streamlit e MobaXterm que estejam a usar as pastas antes de executar.
+
+Se quiser apagar absolutamente tudo de forma intencional, use o comando destrutivo separado:
+
+```powershell
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@VERSAO install --purge-data
+```
+
+O parâmetro `--purge-data` apaga Blueprints, Brandings, configurações, storage e artefactos locais. Não o use numa actualização normal.
+
+No Windows, a instalação cria automaticamente `C:\\Users\\danha\\AppData\\Local\\THUNDERBOLT\\storage` quando executada pela conta `danha`; para outras contas, `%LOCALAPPDATA%\\THUNDERBOLT\\storage` aponta para a pasta equivalente do utilizador.
+
+O instalador irá:
+
+1. procurar Python 3.11 ou superior;
+2. se estiver no Windows e Python não existir, instalar Python 3.11 automaticamente pelo `winget`;
+3. criar o ambiente virtual `~/.thunderbolt/.venv` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\\.venv`);
+4. clonar o repositório oficial MoneyPrinterTurbo para `~/.thunderbolt/MoneyPrinterTurbo` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\\MoneyPrinterTurbo`);
+5. instalar as dependências do Thunderbolt;
+6. instalar as dependências Python do MoneyPrinterTurbo;
+7. instalar `imageio-ffmpeg` para disponibilizar FFmpeg no ambiente Python;
+8. criar `~/.thunderbolt/storage/state/settings.json` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\storage\state\settings.json`);
+9. registar o caminho local do MoneyPrinterTurbo;
+10. deixar o ambiente pronto para o comando de arranque.
+
+No Windows, o caminho padrão é construído a partir de `USERPROFILE`, `HOMEDRIVE/HOMEPATH` ou, em último recurso, `HOME`. O instalador remove o redireccionamento de MobaXterm (`AppData\Local\hermes` ou `AppData\Roaming\MobaXterm\home`) e usa `%LOCALAPPDATA%\\THUNDERBOLT`, salvo se `THUNDERBOLT_HOME` for definido explicitamente. A pasta `AppData\Local\npm-cache\_npx` é apenas cache temporária do npm e não é a pasta de instalação final. O fluxo normal preserva os dados; somente `--purge-data` activa a limpeza destrutiva.
+
+A instalação pode demorar alguns minutos, especialmente durante a instalação de `faster-whisper` e de bibliotecas de processamento de vídeo. O caminho do pacote dentro de `AppData\Local\npm-cache\_npx` que aparece no log é temporário; o launcher usa esse pacote apenas para executar o instalador e os ficheiros finais ficam em `%LOCALAPPDATA%\\THUNDERBOLT`.
+
+### 3.1 Usar o instalador com uma cópia existente do MoneyPrinterTurbo
+
+Se já possui o MoneyPrinterTurbo clonado, indique o caminho.
+
+Linux ou macOS:
+
+```bash
+MONEYPRINTER_PATH=/caminho/para/MoneyPrinterTurbo \
+  npx --yes @danhachuel/thunderbolt install
+```
+
+Windows PowerShell:
+
+```powershell
+$env:MONEYPRINTER_PATH="C:\caminho\MoneyPrinterTurbo"
+npx --yes @danhachuel/thunderbolt install
+```
+
+O instalador reutiliza a pasta existente e instala as suas dependências no ambiente virtual do Thunderbolt.
+
+### 3.2 Instalar apenas a UI
+
+Se pretende testar a interface sem clonar o MoneyPrinterTurbo:
+
+```bash
+npx --yes @danhachuel/thunderbolt install --skip-moneyprinter
+```
+
+Este modo instala o ambiente Python e as dependências da UI, mas não instala o conjunto de dependências do MoneyPrinterTurbo nem configura a integração local com ele.
+
+### 3.3 Controlar os caminhos de instalação
+
+É possível alterar o directório principal e o ambiente Python:
+
+Linux ou macOS:
+
+```bash
+THUNDERBOLT_HOME=/caminho/thunderbolt \
+MONEYPRINTER_PATH=/caminho/MoneyPrinterTurbo \
+THUNDERBOLT_VENV=/caminho/thunderbolt/.venv \
+npx --yes @danhachuel/thunderbolt install
+```
+
+Windows PowerShell:
+
+```powershell
+$env:THUNDERBOLT_HOME="C:\ContentHermes"
+$env:MONEYPRINTER_PATH="C:\MoneyPrinterTurbo"
+$env:THUNDERBOLT_VENV="C:\ContentHermes\.venv"
+npx --yes @danhachuel/thunderbolt install
+```
+
+## 4. Diagnóstico antes de iniciar
+
+Depois da instalação, execute:
+
+```bash
+npx --yes @danhachuel/thunderbolt doctor
+```
+
+Também é possível usar:
+
+```bash
+npx --yes --package=@danhachuel/thunderbolt thunderbolt --check
+```
+
+Uma saída saudável apresenta versões de Python e Streamlit e um caminho de FFmpeg. Por exemplo:
+
+```text
+Ambiente OK. Python: 3.11.x; Streamlit: 1.x.x; FFmpeg: /.../ffmpeg
+```
+
+Se o diagnóstico indicar que FFmpeg não foi detectado, execute novamente a instalação ou verifique se `imageio-ffmpeg` está presente no ambiente virtual.
+
+## 5. Iniciar a aplicação
+
+Depois de instalar e diagnosticar:
+
+```bash
+npx --yes @danhachuel/thunderbolt
+```
+
+Abra no navegador:
+
+```text
+http://localhost:3030
+```
+
+O launcher usa o ambiente virtual em `~/.thunderbolt/.venv` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\\.venv`) quando ele existe. Se for necessário executar numa porta diferente:
+
+Linux ou macOS:
+
+```bash
+THUNDERBOLT_PORT=3040 npx --yes @danhachuel/thunderbolt
+```
+
+Windows PowerShell:
+
+```powershell
+$env:THUNDERBOLT_PORT="3040"
+npx --yes @danhachuel/thunderbolt
+```
+
+Para parar a aplicação, volte ao terminal e pressione `Ctrl+C`.
+
+## 6. Instalação global via npm
+
+Como alternativa ao `npx`, instale o comando globalmente:
+
+```bash
+npm install --global @danhachuel/thunderbolt
+```
+
+Depois execute:
+
+```bash
+thunderbolt
+```
+
+Diagnóstico:
+
+```bash
+thunderbolt doctor
+```
+
+Instalação assistida:
+
+```bash
+thunderbolt install
+```
+
+A instalação global controla apenas o launcher Node.js. O ambiente Python continua a ser criado em `~/.thunderbolt/.venv` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\\.venv`).
+
+## 7. Instalação manual para desenvolvimento
+
+Use esta opção quando quiser trabalhar directamente a partir do repositório GitHub.
+
+```bash
+git clone https://github.com/DanHachuel/thunderbolt.git
+cd thunderbolt
+```
+
+### 7.1 Linux ou macOS
+
+```bash
+python3.11 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+```
+
+Para instalar também o MoneyPrinterTurbo:
+
+```bash
+git clone https://github.com/harry0703/MoneyPrinterTurbo.git
+python -m pip install -r MoneyPrinterTurbo/requirements.txt
+```
+
+Inicie a UI:
+
+```bash
+python -m streamlit run app/main.py --server.port 3030
+```
+
+Ou use o launcher local:
+
+```bash
+node scripts/cli.mjs --check
+node scripts/cli.mjs
+```
+
+### 7.2 Windows PowerShell
+
+```powershell
+py -3.11 -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -r requirements.txt
+```
+
+Para instalar também o MoneyPrinterTurbo:
+
+```powershell
+git clone https://github.com/harry0703/MoneyPrinterTurbo.git
+python -m pip install -r MoneyPrinterTurbo\requirements.txt
+```
+
+Inicie a UI:
+
+```powershell
+python -m streamlit run app/main.py --server.port 3030
+```
+
+Se o PowerShell bloquear a activação do ambiente virtual, execute uma vez, com uma política adequada ao seu utilizador:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
+```
+
+## 8. Configuração inicial da UI
+
+Na primeira execução, abra **Configurações** e reveja:
+
+| Configuração | Finalidade |
+|---|---|
+| Porta Streamlit | Definir a porta local da UI |
+| Pasta MoneyPrinterTurbo | Indicar o clone local que será sincronizado com `config.toml` |
+| YouTube Data API key | Permitir importar nome, handle e métricas de canais |
+| TikTok Client ID/Secret | Credenciais da aplicação; Redirect URI, scopes e autorização ficam no TikTok for Developers Playground |
+
+As chaves devem ser inseridas apenas na configuração local. Não as coloque no GitHub, no `package.json`, em blueprints ou em ficheiros de estado versionados.
+
+## 9. Testar as áreas principais
+
+Após iniciar a aplicação, valide o seguinte percurso:
+
+1. **Dashboard:** confirme que a UI abre e mostra o estado local.
+2. **Blueprints:** coloque um JSON em `~/.thunderbolt/storage/blueprints/importados/` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT\storage\blueprints\importados\`) ou use o carregador da interface.
+3. **Brandings:** abra a subaba **Brandings** e confirme a listagem dos ficheiros JSON.
+4. **Canais:** cadastre um canal manualmente ou importe-o depois de configurar a YouTube Data API.
+5. **Novo vídeo:** teste primeiro o modo **Canal específico** e depois os modos de lote.
+6. **Vídeos:** verifique o estado `to_do` e os botões **Iniciar** e **Parar**.
+7. **Upload:** confirme os destinos configurados e os estados de pré-requisito.
+8. **Limpador de metadado:** suba um vídeo de terceiro, preencha título, preview, links, timestamps e tags, aplique a limpeza e descarregue a cópia limpa e o manifesto JSON. O original fica preservado e vídeos da aba Novo vídeo não são aceites nesta área.
+9. **Configurações:** confirme que os caminhos e credenciais estão locais e não aparecem no Git.
+
+## 10. Limpador de metadado
+
+A aba **Limpador de metadado** recebe somente vídeos externos já prontos. O ficheiro enviado é copiado para `storage/metadata_cleaner/originals/`; a aplicação não altera o original. Ao aplicar a operação, o FFmpeg remove os metadados existentes do contentor e cria uma nova versão em `storage/metadata_cleaner/outputs/` com o título, descrição, tags, idioma e outros campos preenchidos.
+
+A descrição combina **Preview**, **Links** e **Timestamps**, seguindo a estrutura do workflow `YTBMetadataGenerator.json`. O preview recomendado tem entre 100 e 200 caracteres; os capítulos devem começar por `00:00`. O manifesto JSON descarregado contém os campos para um fluxo posterior de upload. Esta adaptação local não faz scraping automático via RSS/Apify nem publica directamente no YouTube.
+
+Se a limpeza falhar, confirme a disponibilidade do FFmpeg em **Configurações > Caminho FFmpeg** ou execute `doctor`. O processo usa `-map_metadata -1` para remover os metadados existentes e `-c copy` para evitar uma re-encodificação desnecessária sempre que o contentor permitir.
+
+## 11. Problemas frequentes
+
+### Python não encontrado
+
+Mensagem típica:
+
+```text
+Python 3.11 ou superior não foi encontrado.
+```
+
+Instale Python 3.11+ e confirme:
+
+```bash
+python3 --version
+```
+
+Se houver várias versões instaladas, indique explicitamente:
+
+```bash
+THUNDERBOLT_PYTHON=/caminho/para/python3.11 npx --yes @danhachuel/thunderbolt install
+```
+
+No Windows PowerShell:
+
+```powershell
+$env:THUNDERBOLT_PYTHON="C:\Python311\python.exe"
+npx --yes @danhachuel/thunderbolt install
+```
+
+### Git não encontrado
+
+Instale Git a partir de [git-scm.com](https://git-scm.com/downloads), ou forneça uma cópia existente do MoneyPrinterTurbo através de `MONEYPRINTER_PATH`.
+
+### Streamlit não está instalado
+
+Execute:
+
+```bash
+npx --yes @danhachuel/thunderbolt install
+npx --yes @danhachuel/thunderbolt doctor
+```
+
+Em instalação manual:
+
+```bash
+python -m pip install -r requirements.txt
+```
+
+### FFmpeg não detectado
+
+Tente reinstalar o suporte Python:
+
+```bash
+python -m pip install --upgrade imageio-ffmpeg
+```
+
+Depois confirme:
+
+```bash
+npx --yes @danhachuel/thunderbolt doctor
+```
+
+O MoneyPrinterTurbo também permite indicar um caminho manual para FFmpeg na configuração local quando a detecção automática não funcionar.[1]
+
+### A porta 3030 está ocupada
+
+Use outra porta:
+
+```bash
+THUNDERBOLT_PORT=3040 npx --yes @danhachuel/thunderbolt
+```
+
+### O MoneyPrinterTurbo não aparece na UI
+
+Confirme o caminho na aba **Configurações** ou execute:
+
+```bash
+MONEYPRINTER_PATH=/caminho/MoneyPrinterTurbo npx --yes @danhachuel/thunderbolt install --skip-python-deps
+```
+
+Depois reinicie a aplicação.
+
+### Dependências Python falham durante a instalação
+
+Actualize pip e tente novamente:
+
+```bash
+npx --yes @danhachuel/thunderbolt install
+```
+
+Se uma dependência específica falhar, guarde o log completo e verifique a compatibilidade da versão Python. Python 3.11 é a opção mais conservadora para o MoneyPrinterTurbo.
+
+### Modelos Whisper não estão disponíveis
+
+A instalação das dependências não baixa necessariamente todos os modelos grandes. O MoneyPrinterTurbo pode descarregar o modelo Whisper na primeira utilização, dependendo da configuração escolhida. Para ambientes sem acesso de rede, siga as instruções do projecto base para descarregar e colocar o modelo localmente.[1]
+
+## 12. Desinstalação
+
+Para remover o pacote global:
+
+```bash
+npm uninstall --global @danhachuel/thunderbolt
+```
+
+Para remover o ambiente e os dados locais:
+
+Linux ou macOS:
+
+```bash
+rm -rf ~/.thunderbolt
+```
+
+Windows PowerShell:
+
+```powershell
+Remove-Item -Recurse -Force "$HOME\\THUNDERBOLT"
+```
+
+> A remoção de `~/.thunderbolt` (Windows: `%LOCALAPPDATA%\\THUNDERBOLT`) apaga estado JSON, blueprints, configurações e artefactos locais. Faça uma cópia de segurança antes de executar o comando.
+
+## 13. Segurança
+
+Nunca publique ou envie por chat:
+
+- tokens npm;
+- chaves YouTube, TikTok ou outros serviços;
+- cookies e tokens OAuth;
+- ficheiros de configuração com segredos;
+- artefactos privados de canais.
+
+Use secrets do GitHub Actions apenas para publicação do pacote. Para execução local, mantenha credenciais fora do repositório e use a área de configurações local ou variáveis de ambiente.
+
+## 14. Referências
+
+[1]: https://github.com/harry0703/MoneyPrinterTurbo/blob/main/README-en.md — MoneyPrinterTurbo: requisitos, instalação, dependências, Streamlit e FFmpeg.
+
+[2]: https://www.npmjs.com/package/@danhachuel/thunderbolt — Pacote npm publicado.
+
+[3]: https://github.com/DanHachuel/thunderbolt — Repositório GitHub do Thunderbolt UI.

package/README.md

@@ -0,0 +1,173 @@
+# Thunderbolt UI
+
+> Consulte o [Manual completo de instalação](MANUAL-INSTALACAO.md) antes do primeiro teste local.
+
+Thunderbolt — UI web local da Fase 3, baseada no fluxo Streamlit do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo). A aplicação organiza canais, blueprints, lotes de vídeos, filas, artefactos e upload em armazenamento local JSON.
+
+## Estado actual
+
+A primeira versão implementa a camada UI independente com:
+
+| Área | Incluído |
+|---|---|
+| Dashboard | Resumo de canais, tarefas, backlog, execução e falhas |
+| Pipeline | Filas por etapa |
+| Blueprints | Leitura da pasta `storage/blueprints/`, upload/validação de JSON e criação a partir de link YouTube |
+| Brandings | Subaba própria dentro de Blueprints, upload/listagem de Brandings e criação conjunta com Blueprint |
+| Canais | Cadastro manual, importação via YouTube Data API quando configurada e edição de dados importados |
+| Novo vídeo | Canal específico, lote no mesmo canal e lote geral |
+| Vídeos | Filtro por estado e controlos iniciar/parar |
+| Upload | Destinos YouTube/TikTok e diagnóstico do TikTok |
+| Limpador de metadado | Upload isolado de vídeos terceiros, limpeza FFmpeg, edição de título/descrição/tags e manifesto JSON |
+| Configurações | Provedores LLM, TTS/voz, materiais, Whisper, FFmpeg, YouTube, TikTok Client ID/Secret e Upload-Post |
+| Launcher | Execução via `npx`, instalação assistida, diagnóstico e preparação para distribuição |
+
+Os adaptadores do MoneyPrinterTurbo e de publicação nas plataformas são ligados pelas configurações locais e pelos pontos de integração em `integrations/`. A UI não inventa dados quando um serviço externo ou credencial não está disponível.
+
+## Instalação
+
+Recomenda-se Python 3.11 ou superior e Node.js 18 ou superior.
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -r requirements.txt
+```
+
+No Windows PowerShell:
+
+```powershell
+py -m venv .venv
+.venv\\Scripts\\Activate.ps1
+python -m pip install -r requirements.txt
+```
+
+## Execução
+
+A porta da aplicação é `3030`:
+
+```bash
+python -m streamlit run app/main.py --server.port 3030
+```
+
+Ou através do launcher Node:
+
+```bash
+node scripts/cli.mjs --check
+node scripts/cli.mjs
+```
+
+O pacote está publicado no npm como `@danhachuel/thunderbolt` e pode ser executado directamente via `npx`:
+
+```bash
+npx --yes @danhachuel/thunderbolt
+```
+
+Para instalar automaticamente o ambiente completo — Python 3.11+, ambiente virtual, dependências Python do Thunderbolt, dependências Python do MoneyPrinterTurbo, Streamlit e `imageio-ffmpeg` — execute:
+
+```bash
+npx --yes @danhachuel/thunderbolt install
+```
+
+Por defeito, o instalador cria automaticamente a pasta `~/.thunderbolt` — no Windows, `%LOCALAPPDATA%\\THUNDERBOLT` —, clona o MoneyPrinterTurbo para `THUNDERBOLT/MoneyPrinterTurbo`, cria o ambiente em `THUNDERBOLT/.venv` e guarda o estado em `THUNDERBOLT/storage`. No Windows, se Python 3.11+ não estiver instalado, o instalador tenta instalá-lo automaticamente através do `winget`. A instalação normal é segura para actualizações: preserva `storage`, Blueprints, Brandings, configurações e artefactos, removendo apenas `.venv` e o clone técnico do MoneyPrinterTurbo para os recriar. A antiga pasta sem dados do utilizador em `C:\Users\<utilizador>\AppData\Local\hermes` pode ser removida. O caminho `AppData\Local\npm-cache\_npx` é apenas cache temporária do npm, não é a pasta de instalação final. Para apagar dados intencionalmente, use o parâmetro explícito `--purge-data`; nunca o use numa actualização normal. Para usar uma cópia existente do MoneyPrinterTurbo:
+
+```bash
+MONEYPRINTER_PATH=/caminho/MoneyPrinterTurbo npx --yes @danhachuel/thunderbolt install
+```
+
+Para instalar apenas a UI sem clonar o MoneyPrinterTurbo:
+
+```bash
+npx --yes @danhachuel/thunderbolt install --skip-moneyprinter
+```
+
+Para verificar o ambiente sem iniciar a aplicação:
+
+```bash
+npx --yes @danhachuel/thunderbolt doctor
+```
+
+Para executar apenas o diagnóstico do ambiente:
+
+```bash
+npx --yes --package=@danhachuel/thunderbolt thunderbolt --check
+```
+
+Para instalar globalmente e disponibilizar o comando `thunderbolt`:
+
+```bash
+npm install --global @danhachuel/thunderbolt
+thunderbolt
+```
+
+No Windows PowerShell, se `npx` for bloqueado por `npx.ps1`, use directamente `npx.cmd`:
+
+```powershell
+npx.cmd --yes @danhachuel/thunderbolt@0.2.13 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.13 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.2.13
+```
+
+Como alternativa, pode permitir scripts para o seu utilizador:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+Ou apenas para a sessão actual:
+
+```powershell
+Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
+```
+
+Após `install`, o launcher usa o ambiente virtual instalado em `~/.thunderbolt/.venv` — no Windows, `%LOCALAPPDATA%\\THUNDERBOLT\\.venv` — e inicia a UI em `localhost:3030`. No Windows, a raiz é `%LOCALAPPDATA%\\THUNDERBOLT`; no computador indicado, o caminho será `C:\\Users\\danha\\AppData\\Local\\THUNDERBOLT`. Isto evita a redirecção de `HOME` que pode ocorrer no MobaXterm.
+ O instalador não instala drivers de GPU, Docker, chaves de API, modelos Whisper ou credenciais de plataformas; esses componentes continuam dependentes do sistema e da configuração do utilizador. Para desenvolvimento a partir do clone, continue a usar `node scripts/cli.mjs`.
+
+## Armazenamento local
+
+O sistema cria automaticamente:
+
+```text
+storage/
+├── blueprints/       # blueprints JSON lidos pela aba Blueprints
+├── state/
+│   ├── channels.json
+│   ├── tasks.json
+│   ├── queues.json
+│   ├── batches.json
+│   ├── uploads.json
+│   ├── metadata_edits.json
+│   └── settings.json
+├── metadata_cleaner/
+│   ├── originals/    # cópias dos vídeos terceiros enviados
+│   └── outputs/      # versões com metadados limpos
+└── artifacts/        # ficheiros produzidos e caminhos referenciados
+```
+
+Para usar outro local, defina `THUNDERBOLT_STORAGE_DIR`. O estado é escrito de forma atómica e ficheiros JSON inválidos são preservados com cópia `.corrupt-*` antes de serem recriados.
+
+## Blueprints e Brandings
+
+Coloque ficheiros `.json` em `storage/blueprints/canais`, `storage/blueprints/nichos` ou `storage/blueprints/importados`. A aba **Blueprints** relê a pasta e mostra o conteúdo estruturado. A instalação já inclui 13 Blueprints seed, copiados apenas quando o ficheiro ainda não existe; actualizações não substituem Blueprints locais. Também é possível importar através do carregador da própria interface.
+
+A mesma aba possui a subaba **Brandings**. No formulário **Criar blueprint a partir de link**, cole um link de canal, handle ou vídeo do YouTube, informe o nicho e o idioma e escolha entre **Apenas Blueprint** ou **Blueprint + Branding completo**. O primeiro modo grava o blueprint forense local; o segundo grava também um ficheiro de Branding com identidade do canal, handle, descrição, hashtags, keywords, prompts de imagem de perfil e banner, direcção visual de thumbnails, assets e checklist de revisão.
+
+O fluxo foi modelado a partir do blueprint de clonagem com Branding anexado, incluindo a distinção entre entrada de canal/vídeo, normalização do link, metadados de nicho/idioma, perfil do canal, estratégia de conteúdo, pesquisa, identidade visual e brand pack. Placeholders de serviços externos são tratados como configuração local; chaves presentes em workflows importados não devem ser commitadas.
+
+## Limpador de metadado
+
+A aba **Limpador de metadado** foi adaptada do workflow `YTBMetadataGenerator.json`. Ela recebe apenas um vídeo externo já pronto, guarda uma cópia original separada, remove os metadados do contentor com FFmpeg e grava uma nova cópia com título, descrição, links, timestamps, tags e outros campos opcionais. O original nunca é alterado e os vídeos produzidos pela aba **Novo vídeo** não aparecem nesta área.
+
+A descrição segue a composição do workflow de referência: preview, secção de links e capítulos/timestamps. O resultado inclui um manifesto JSON para utilizar os metadados num fluxo posterior de upload. A versão local não usa o trigger RSS, o Apify ou a actualização automática de um vídeo YouTube; em vez disso, o utilizador fornece directamente o vídeo terceiro e controla a edição antes de publicar.
+
+## Canais YouTube
+
+Sem chave, o cadastro manual continua disponível. Para importar nome, handle e estatísticas através da API oficial do YouTube Data API, configure `youtube_api_key` na aba **Configurações** ou em `YOUTUBE_API_KEY`.
+
+## TikTok
+
+A aba **Configurações** contém apenas o TikTok Client ID e o TikTok Client Secret. Redirect URI, scopes, autorização OAuth e tokens são geridos no TikTok for Developers Playground. O adaptador rejeita o upload quando faltam credenciais ou OAuth, em vez de indicar sucesso falso.
+
+## Segurança
+
+Não coloque chaves, cookies, tokens YouTube ou segredos TikTok no Git. Use a configuração local, variáveis de ambiente ou um ficheiro fora do repositório. O `.gitignore` exclui o storage de estado real, ambientes virtuais e ficheiros de segredo.