@danhachuel/thunderbolt 0.4.11 → 0.4.13

package/README.md

@@ -46,7 +46,10 @@ A migração é baseada no workflow público [AI Agents A-Z — episódio 35](ht
 
 Em **Pipeline Vídeos > Criação de Vídeos** e **Automação Youtube**, a opção **Pexels/Pixabay** usa a rota stock do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo): as keywords do roteiro são encaminhadas para a pesquisa da fonte seleccionada, os clips são descarregados e reutilizados localmente, e o motor faz a composição com MoviePy/FFmpeg, respeitando proporção, duração máxima, concatenação, transições, correspondência visual ao roteiro, narração, legendas e música de fundo. As API keys de Pexels e Pixabay são exportadas para o `config.toml` do motor e a fonte efectiva é encaminhada por tarefa, sem depender apenas da fonte global guardada nas configurações. Em **Configurações > Configuração API > API Keys > Imagem e Video Montagem/MoviePy**, cada cartão possui o campo **Prioridade**: o menor número aparece primeiro e a ordenação fica guardada no storage local.
 
-A ordem persistida da criação é **Tema → Script → Título → Keywords opcional → Vídeo → Prompt Thumbnail em JSON → Thumbnail → Upload**. O vídeo é materializado antes do prompt e da imagem da thumbnail; uma falha posterior de thumbnail não invalida um MP4 já pronto. **Full IA** é uma rota separada e usa o pool de vídeo configurável com **FAL AI, KIE AI, Agnes AI, Nano Banana, Replicate AI, Pollinations.ai, Hugging Face Inference API, InferencePort Proxy e HeyGen**, respeitando apenas cartões activos que declarem capacidade de vídeo. **Apenas Música** não chama a pipeline de vídeo nem tenta gerar thumbnail: reutiliza o áudio local/Suno já descarregado e deixa-o pronto para a integração de upload musical.
+Quando existem cartões activos de **Pexels** e **Pixabay**, a Pipeline tenta primeiro a fonte seleccionada na tarefa e, se a falha for específica do provider stock, tenta os restantes providers stock configurados por ordem de prioridade. Falhas de LLM, Azure, áudio local ou configuração estrutural não são mascaradas por um fallback de materiais.
+
+A ordem persistida da criação é **Tema → Script → Título → Keywords opcional → Vídeo → Prompt Thumbnail em JSON → Thumbnail → Upload**.
+O vídeo é materializado antes do prompt e da imagem da thumbnail; uma falha posterior de thumbnail não invalida um MP4 já pronto. **Full IA** é uma rota separada e usa o pool de vídeo configurável com **FAL AI, KIE AI, Agnes AI, Nano Banana, Replicate AI, Pollinations.ai, Hugging Face Inference API, InferencePort Proxy e HeyGen**, respeitando apenas cartões activos que declarem capacidade de vídeo. **Apenas Música** não chama a pipeline de vídeo nem tenta gerar thumbnail: reutiliza o áudio local/Suno já descarregado e deixa-o pronto para a integração de upload musical.
 
 Quando uma etapa falha, a tarefa, a notificação e a página **Configurações > Logs** guardam e mostram sempre a coluna **API/Provider**, o serviço, a rota e, quando aplicável, os campos de configuração em falta. No caso do MoneyPrinterTurbo, os marcadores `LLM_PROVIDER`, `MISSING` e `INVALID` são convertidos em attribution legível; por exemplo, um erro pode indicar simultaneamente **OpenAI / NVIDIA NIM API** e **Pexels API**, em vez de apresentar apenas a mensagem genérica de credenciais adicionais. Os timeouts `azure_tts_v1`/`edge_tts` são identificados como **Azure Speech / edge_tts API**. Quando há Azure Speech key e região, o worker encaminha a voz para o SDK Azure Speech V2. Para evitar o limite de 10 minutos da síntese em tempo real documentado pela [Microsoft](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/speech-services-quotas-and-limits), o helper divide o roteiro em segmentos seguros, sintetiza-os sequencialmente com retry e concatena o MP3 antes de o entregar ao MoneyPrinterTurbo como áudio customizado. O erro `1007`/`600000ms` é atribuído explicitamente à **Azure Speech SDK V2 API**. Sem credenciais Azure, o fallback edge_tts usa um timeout interno de 90 segundos. O worker invoca o helper com `--` antes das flags MoneyPrinterTurbo, porque `mpt_agent.py` reserva esses argumentos para a CLI filha. Registos históricos sem metadata são identificados explicitamente como anteriores à attribution estruturada.
 

package/app/main.py

@@ -6752,6 +6752,22 @@ def render_supabase_tutorial():
     st.markdown(tutorial_content, unsafe_allow_html=True)
 
 
+def render_google_oauth_tutorial():
+    """Render the Google OAuth setup guide supplied for Thunderbolt."""
+    tutorial_path = ROOT / "seed" / "references" / "tutorial-oauth-google.md"
+    st.title("Tutorial OAuth do Google")
+    st.caption("Guia completo para configurar a autenticação OAuth do Google e o acesso à YouTube Data API v3.")
+    st.markdown("[Abrir Google Cloud Console](https://console.cloud.google.com/)")
+    try:
+        tutorial_content = tutorial_path.read_text(encoding="utf-8").strip()
+    except OSError:
+        tutorial_content = ""
+    if not tutorial_content:
+        st.error("O conteúdo local do tutorial não está disponível. Consulte a documentação OAuth do Google.")
+        return
+    st.markdown(tutorial_content, unsafe_allow_html=False)
+
+
 def render_youtube_frontend_upload_tutorial():
     """Render the safe operational guide for the YouTube direct-upload workflow."""
     tutorial_path = ROOT / "seed" / "references" / "youtube-video-upload-frontend.md"
@@ -7076,6 +7092,7 @@ def main():
         ("Tutorial Kaggle", ":material/menu_book:", "Tutorial Kaggle"),
         ("Tutorial Apify", ":material/menu_book:", "Tutorial Apify"),
         ("Tutorial YouTube Video-Upload Frontend", ":material/video_library:", "Tutorial YouTube Video-Upload Frontend"),
+        ("Tutorial OAuth do Google", ":material/key:", "Tutorial OAuth do Google"),
     ]
     settings_items = [
         ("MCP", ":material/hub:", "MCP"),
@@ -7130,7 +7147,7 @@ def main():
         "AI Influencers": "/ai-influencers", "Personagens": "/ai-influencers/personagens", "Geração de Conteúdo IA": "/ai-influencers/geracao-conteudo", "Motion Control": "/ai-influencers/motion-control", "UGC Products": "/ai-influencers/ugc-products", "Redes Sociais": "/ai-influencers/redes-sociais",
         "Edição": "/edicao", "Limpador de Metadados": "/edicao/limpador-metadados", "Cortes": "/edicao/cortes", "Editor Python": "/edicao/editor-python", "Download Mídia": "/edicao/download-midia",
         "Growth": "/growth", "Analista Growth Youtube": "/growth/youtube", "Analista Growth Tiktok": "/growth/tiktok", "Analista Growth Instagram": "/growth/instagram", "Analista Facebook Pages": "/growth/facebook-pages", "Analista Bilibili": "/growth/bilibili",
-        "Documentação": "/documentacao", "Tutorial Meta": "/documentacao/meta", "Tutorial Supabase": "/documentacao/supabase", "Tutorial Kaggle": "/documentacao/kaggle", "Tutorial Apify": "/documentacao/apify", "Tutorial YouTube Video-Upload Frontend": "/documentacao/youtube-video-upload-frontend",
+        "Documentação": "/documentacao", "Tutorial Meta": "/documentacao/meta", "Tutorial Supabase": "/documentacao/supabase", "Tutorial Kaggle": "/documentacao/kaggle", "Tutorial Apify": "/documentacao/apify", "Tutorial YouTube Video-Upload Frontend": "/documentacao/youtube-video-upload-frontend", "Tutorial OAuth do Google": "/documentacao/oauth-google",
         "Configurações": "/configuracoes", "MCP": "/configuracoes/mcp", "Notificações": "/configuracoes/notificacoes", "Logs": "/configuracoes/logs", "Configuração API": "/configuracoes/api",
     }
 
@@ -7238,6 +7255,7 @@ def main():
         "Tutorial Meta": render_models_ai_tutorial,
         "Tutorial Supabase": render_supabase_tutorial,
         "Tutorial YouTube Video-Upload Frontend": render_youtube_frontend_upload_tutorial,
+        "Tutorial OAuth do Google": render_google_oauth_tutorial,
         "Configurações": lambda: render_edit_placeholder("Configurações", "Seleccione uma opção no menu expansível."),
         "MCP": render_mcp,
         "Contas Google": render_google_accounts,

package/hermes_ui/pipeline_worker.py

@@ -22,7 +22,7 @@ from hermes_ui.storage import STORAGE, atomic_write, ensure_storage, read_json,
 from hermes_ui.llm_providers import active_llm_card, provider_definition
 from hermes_ui.media_generation import MediaGenerationError, _append_generation_constraints, generate_image_from_pool, generate_video_from_pool
 from hermes_ui.media_providers import FULL_IA_VIDEO_PROVIDER_CODES, media_cards_for_pool, media_provider_definition
-from hermes_ui.material_sources import material_api_keys, selected_material_source
+from hermes_ui.material_sources import material_api_keys, material_source_cards, selected_material_source
 from hermes_ui.thumbnail_generation import ThumbnailGenerationError, generate_thumbnail_image
 
 PIPELINE_LOCK_FILENAME = "pipeline_worker.lock"
@@ -38,9 +38,16 @@ CASCADE_STAGE_ORDER = ("topic", "script", "title", "keywords", "video", "thumbna
 class PipelineError(RuntimeError):
     """Raised when a pipeline stage cannot complete with an actionable error."""
 
-    def __init__(self, message: str, *, failure_metadata: dict[str, Any] | None = None):
+    def __init__(
+        self,
+        message: str,
+        *,
+        failure_metadata: dict[str, Any] | None = None,
+        fallback_eligible: bool = False,
+    ):
         super().__init__(message)
         self.failure_metadata = dict(failure_metadata or {})
+        self.fallback_eligible = bool(fallback_eligible)
 
 
 class PipelineStopped(PipelineError):
@@ -620,6 +627,30 @@ def _normalise_video_route(task: dict[str, Any], settings: dict[str, Any]) -> st
     return raw if raw in {"pexels", "pixabay", "local"} else "pexels"
 
 
+def _material_video_routes(task: dict[str, Any], settings: dict[str, Any]) -> list[str]:
+    """Return stock providers to try, starting with the task's selected source."""
+    route = _normalise_video_route(task, settings)
+    if route not in {"pexels", "pixabay"}:
+        return [route]
+
+    ordered_providers: list[str] = []
+    for card in material_source_cards(settings, enabled_only=True):
+        provider = str(card.get("provider") or "").strip().casefold()
+        if provider not in {"pexels", "pixabay"} or provider in ordered_providers:
+            continue
+        if material_api_keys(settings, provider):
+            ordered_providers.append(provider)
+
+    # A selected source is an explicit preference for this task. The remaining
+    # configured sources follow their persisted priority and are true fallbacks.
+    if route in ordered_providers:
+        ordered_providers.remove(route)
+        ordered_providers.insert(0, route)
+    elif material_api_keys(settings, route):
+        ordered_providers.insert(0, route)
+    return ordered_providers or [route]
+
+
 def _video_timeout_seconds(task: dict[str, Any], settings: dict[str, Any] | None = None) -> int:
     """Reserve extra bounded time only for long stock-video downloads and assembly."""
     effective_settings = settings if isinstance(settings, dict) else _settings()
@@ -633,7 +664,9 @@ def _video_timeout_seconds(task: dict[str, Any], settings: dict[str, Any] | None
 def _task_stale_timeout_seconds(task: dict[str, Any]) -> int:
     """Keep stale-task recovery aligned with the actual execution budget."""
     if str(task.get("stage") or "").strip().casefold() == "video":
-        return _video_timeout_seconds(task) + 5 * 60
+        settings = _settings()
+        attempts = max(1, len(_material_video_routes(task, settings)))
+        return _video_timeout_seconds(task, settings) * attempts + 5 * 60
     return STALE_TASK_SECONDS
 
 
@@ -820,7 +853,12 @@ def _moneyprinter_cli_args(task: dict[str, Any], route: str, settings: dict[str,
     return args
 
 
-def _run_video_helper(task: dict[str, Any]) -> Path:
+def _run_video_helper_once(
+    task: dict[str, Any],
+    *,
+    route_override: str = "",
+    settings: dict[str, Any] | None = None,
+) -> Path:
     helper_dir = Path(__file__).resolve().parents[1] / "seed" / "skills"
     helper = helper_dir / "mpt_agent.py"
     if not helper.is_file():
@@ -828,16 +866,23 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
     subject = str(task.get("topic") or "").strip()
     if not subject:
         raise PipelineError("A etapa Vídeo não recebeu um tema válido.")
-    settings = _settings()
+    settings = settings if isinstance(settings, dict) else _settings()
     configured_root = _configured_moneyprinter_root(settings)
     task_id = str(task.get("id") or "").strip()
     if not task_id:
         raise PipelineError("A tarefa de vídeo não tem um identificador válido.")
     env = os.environ.copy()
+    for key in (
+        "MPT_PEXELS_API_KEY",
+        "MPT_PEXELS_API_KEYS",
+        "MPT_PIXABAY_API_KEY",
+        "MPT_PIXABAY_API_KEYS",
+    ):
+        env.pop(key, None)
     card = active_llm_card(settings)
     provider = str(card.get("provider") or "openai").strip()
     definition = provider_definition(provider)
-    route = _normalise_video_route(task, settings)
+    route = str(route_override or _normalise_video_route(task, settings)).strip().casefold()
     source_keys = material_api_keys(settings, route) if route in {"pexels", "pixabay"} else []
     if route in {"pexels", "pixabay"} and not source_keys:
         source_label = "Pexels" if route == "pexels" else "Pixabay"
@@ -987,7 +1032,11 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
                 _stop_process(process)
                 message = f"A etapa Vídeo excedeu o limite de {timeout_seconds // 60} minutos e foi encerrada."
                 metadata = _failure_attribution(task, settings, "video", error=message)
-                raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
+                raise PipelineError(
+                    _failure_message(message, metadata),
+                    failure_metadata=metadata,
+                    fallback_eligible=True,
+                )
             if time.monotonic() - last_activity_at >= VIDEO_IDLE_TIMEOUT_SECONDS:
                 _stop_process(process)
                 message = (
@@ -995,7 +1044,11 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
                     f"{VIDEO_IDLE_TIMEOUT_SECONDS // 60} minutos e foi encerrada."
                 )
                 metadata = _failure_attribution(task, settings, "video", error=message)
-                raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
+                raise PipelineError(
+                    _failure_message(message, metadata),
+                    failure_metadata=metadata,
+                    fallback_eligible=True,
+                )
     finally:
         reader.join(timeout=2)
         _persist_video_diagnostics(task, "\n".join(output_lines))
@@ -1010,12 +1063,20 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
         message = "A geração de vídeo precisa de credenciais adicionais do MoneyPrinterTurbo"
         if detail:
             message += f". Detalhe do helper: {detail}"
-        raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
+        raise PipelineError(
+            _failure_message(message, metadata),
+            failure_metadata=metadata,
+            fallback_eligible=True,
+        )
     if result_code != 0:
         detail = _terminal_helper_detail(output) or "erro sem detalhes devolvidos pelo helper"
         metadata = _failure_attribution(task, settings, "video", error=detail, output=output)
         message = f"MoneyPrinterTurbo falhou na etapa Vídeo: {detail}"
-        raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
+        raise PipelineError(
+            _failure_message(message, metadata),
+            failure_metadata=metadata,
+            fallback_eligible=True,
+        )
     match = re.search(r"(?m)^VIDEO_FILE=(.+)$", output)
     video_path = Path(match.group(1).strip()).expanduser() if match else None
     if not video_path or not video_path.is_file() or video_path.stat().st_size <= 0:
@@ -1030,10 +1091,66 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
     if not video_path or not video_path.is_file() or video_path.stat().st_size <= 0:
         message = "MoneyPrinterTurbo terminou sem devolver um MP4 válido."
         metadata = _failure_attribution(task, settings, "video", error=message, output=output)
-        raise PipelineError(_failure_message(message, metadata), failure_metadata=metadata)
+        raise PipelineError(
+            _failure_message(message, metadata),
+            failure_metadata=metadata,
+            fallback_eligible=True,
+        )
     return video_path
 
 
+def _stock_fallback_is_eligible(route: str, error: PipelineError) -> bool:
+    """Allow fallback only when the failed attempt points to its stock source."""
+    if route not in {"pexels", "pixabay"} or not getattr(error, "fallback_eligible", False):
+        return False
+    metadata = dict(getattr(error, "failure_metadata", {}) or {})
+    providers = {
+        item.strip().casefold()
+        for item in str(metadata.get("failure_provider") or "").split(",")
+        if item.strip()
+    }
+    if providers and providers - {route}:
+        return False
+    fields = {
+        item.strip().casefold()
+        for item in str(metadata.get("failure_config_fields") or "").split(",")
+        if item.strip()
+    }
+    if fields and fields - {f"{route}_api_key", f"{route}_api_keys"}:
+        return False
+    return True
+
+
+def _run_video_helper(task: dict[str, Any]) -> Path:
+    """Run the stock helper with provider fallback in the configured priority order."""
+    settings = _settings()
+    routes = _material_video_routes(task, settings)
+    if len(routes) <= 1:
+        return _run_video_helper_once(task, route_override=routes[0] if routes else "", settings=settings)
+
+    for index, route in enumerate(routes):
+        attempt_task = dict(task)
+        generation_settings = task.get("generation_settings") if isinstance(task.get("generation_settings"), dict) else {}
+        attempt_task["material_source"] = route
+        attempt_task["generation_settings"] = {**generation_settings, "material_source": route}
+        try:
+            return _run_video_helper_once(attempt_task, route_override=route, settings=settings)
+        except PipelineStopped:
+            raise
+        except PipelineError as exc:
+            if not _stock_fallback_is_eligible(route, exc) or index == len(routes) - 1:
+                metadata = dict(getattr(exc, "failure_metadata", {}) or {})
+                metadata["failure_route"] = route
+                metadata["fallback_attempts"] = " → ".join(_provider_api_label(item) for item in routes[: index + 1])
+                message = (
+                    f"Falha no provider {_provider_api_label(route)} após tentar "
+                    f"{metadata['fallback_attempts']}. Último erro: {exc}"
+                )
+                raise PipelineError(message, failure_metadata=metadata) from exc
+
+    raise PipelineError("Nenhum provider de vídeo stock configurado.")
+
+
 def _read_persisted_script(task: dict[str, Any], channel: dict[str, Any], blueprint: dict[str, Any], topic: str) -> dict[str, Any] | None:
     """Load a previously saved script so retries do not regenerate it."""
     artifacts = task.get("artifacts") if isinstance(task.get("artifacts"), dict) else {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.4.11",
+  "version": "0.4.13",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "license": "MIT",
   "main": "scripts/cli.mjs",

package/seed/references/tutorial-oauth-google.md

@@ -0,0 +1,155 @@
+# Tutorial completo: configurar OAuth do Google para o Thunderbolt
+
+Este tutorial explica como criar um projecto no Google Cloud, activar a YouTube Data API v3, configurar a tela de consentimento OAuth, criar as credenciais e ligá-las ao Thunderbolt.
+
+## Pré-requisitos
+
+Antes de começar, certifique-se de que tem uma conta Google, acesso ao [Google Cloud Console](https://console.cloud.google.com/) e o Thunderbolt instalado e em execução localmente. A aplicação em execução é necessária para confirmar a URI de redireccionamento OAuth utilizada pelo projecto.
+
+## Passo 1 — Aceder ao Google Cloud Console
+
+Abra o [Google Cloud Console](https://console.cloud.google.com/) e faça login com a sua conta Google. Se for a primeira utilização, aceite os Termos de Serviço apresentados.
+
+## Passo 2 — Criar ou seleccionar um projecto
+
+No topo da página, clique no selector de projectos, junto a **Google Cloud**. No diálogo apresentado, seleccione **Novo projecto** e preencha os campos seguintes:
+
+| Campo | Valor sugerido |
+|---|---|
+| Nome do projecto | `Thunderbolt` |
+| Organização | Deixe em branco ou seleccione a organização predefinida |
+
+Clique em **Criar**, aguarde a conclusão e use o selector de projectos para mudar para o projecto criado.
+
+## Passo 3 — Activar a YouTube Data API v3
+
+No menu lateral, abra **APIs e Serviços → Biblioteca**. Pesquise por **YouTube Data API v3**, abra o resultado correspondente e clique em **Activar**.
+
+Se a **Google+ API** ainda aparecer como opção no seu projecto, a sua activação é opcional e pode ser útil para funcionalidades legadas que dependam dela.
+
+## Passo 4 — Configurar a tela de consentimento OAuth
+
+> **Este é um passo obrigatório.** A tela de consentimento é apresentada ao utilizador quando o Thunderbolt solicita autorização para aceder à conta Google/YouTube.
+
+No menu lateral, abra **APIs e Serviços → Tela de consentimento OAuth**. Clique em **Começar** ou **Configurar tela de consentimento**, conforme a opção apresentada.
+
+Em **Tipo de utilizador**, seleccione **Externo** e clique em **Criar**. Na secção **Informações do app**, preencha:
+
+| Campo | Valor sugerido |
+|---|---|
+| Nome do app | `Thunderbolt` ou o nome pretendido |
+| E-mail para suporte do utilizador | O seu e-mail |
+| Logótipo do app | Opcional; pode deixar em branco |
+| Domínio da página inicial | Deixe em branco ou utilize `localhost` para desenvolvimento local |
+| Política de privacidade | Opcional nesta fase |
+| Termos de serviço | Opcional nesta fase |
+
+Clique em **Próxima**. Em **Público**, mantenha a opção **Externo** e avance novamente.
+
+Em **Escopos**, clique em **Adicionar ou remover escopos**, pesquise por `youtube` e seleccione:
+
+| Escopo | Finalidade |
+|---|---|
+| `https://www.googleapis.com/auth/youtube` | Gerir a sua conta do YouTube |
+| `https://www.googleapis.com/auth/youtube.upload` | Gerir os seus vídeos do YouTube e efectuar uploads |
+| `https://www.googleapis.com/auth/youtube.readonly` | Visualizar a sua conta do YouTube; opcional |
+
+Clique em **Actualizar** e depois em **Próxima**. Em **Informações de contacto**, indique o seu e-mail para receber notificações do Google e avance.
+
+Na página **Concluir**, leia a Política de Dados do Utilizador, marque a caixa de concordância e clique em **Continuar** e, depois, em **Criar**.
+
+> **Importante:** depois de criada, a tela de consentimento não pode ser removida, embora possa ser editada posteriormente.
+
+## Passo 5 — Adicionar utilizadores de teste
+
+Enquanto a aplicação estiver com o estado **Não verificado**, o Google exige que os utilizadores de teste sejam adicionados manualmente para permitir o login.
+
+Na página da tela de consentimento OAuth, abra o separador **Público-alvo** e, na área **Utilizadores de teste**, clique em **Adicionar utilizadores**. Introduza o seu e-mail, clique em **Adicionar** e depois em **Guardar**.
+
+## Passo 6 — Criar as credenciais OAuth
+
+No menu lateral, abra **APIs e Serviços → Credenciais** e clique em **+ Criar credenciais → ID do cliente OAuth**. Em **Tipo de aplicativo**, seleccione **Aplicativo da Web** e atribua um nome, por exemplo, `Thunderbolt Web Client`.
+
+### Origens JavaScript autorizadas
+
+Clique em **Adicionar URI** e introduza a origem onde o frontend é executado, por exemplo:
+
+```text
+http://localhost:3000
+```
+
+Se existir um ambiente de produção, adicione também a origem HTTPS correspondente, por exemplo `https://seudominio.com`.
+
+### URIs de redireccionamento autorizadas
+
+Esta é a parte mais crítica. Clique em **Adicionar URI** e introduza a URI exacta utilizada pelo Thunderbolt para o callback OAuth. Exemplos de desenvolvimento local:
+
+```text
+http://localhost:3000/api/auth/google/callback
+http://localhost:5173/oauth2callback
+```
+
+> **A URI tem de ser exactamente igual à configurada no código do Thunderbolt.** Uma barra final diferente, o uso de `http` em vez de `https` ou uma porta diferente causa o erro `redirect_uri_mismatch`.
+
+Se não souber qual é a URI utilizada, consulte a configuração ou o ficheiro de ambiente do Thunderbolt e confirme também os logs da aplicação.
+
+Clique em **Criar**. Na janela apresentada, copie o **ID do cliente (Client ID)** e a **Chave secreta do cliente (Client Secret)** e guarde-os num local seguro.
+
+> **Nunca partilhe o Client Secret nem o envie para o controlo de versão Git.**
+
+## Passo 7 — Configurar o Thunderbolt
+
+O projecto utiliza variáveis de ambiente para as credenciais OAuth. Localize o ficheiro de ambiente do Thunderbolt, normalmente `.env`, `.env.local` ou o ficheiro de configuração equivalente, e adicione:
+
+```env
+GOOGLE_CLIENT_ID=seu_client_id_aqui
+GOOGLE_CLIENT_SECRET=sua_client_secret_aqui
+GOOGLE_REDIRECT_URI=http://localhost:3000/api/auth/google/callback
+```
+
+Substitua `seu_client_id_aqui` e `sua_client_secret_aqui` pelos valores copiados no passo anterior. Confirme que `GOOGLE_REDIRECT_URI` é exactamente igual à URI registada no Google Cloud Console.
+
+## Passo 8 — Testar a autenticação
+
+Reinicie o servidor do Thunderbolt para carregar as novas variáveis de ambiente. Abra a interface e tente iniciar sessão com o Google.
+
+O fluxo esperado é:
+
+1. O Google apresenta a tela de consentimento com o nome do app e os escopos solicitados.
+2. O utilizador autoriza o acesso.
+3. O Google redirecciona para a URI de callback do Thunderbolt.
+4. A autenticação é concluída com sucesso na aplicação.
+
+## Solução de problemas
+
+### Erro `redirect_uri_mismatch`
+
+Este erro significa que a URI enviada pelo Thunderbolt não corresponde exactamente à URI registada no Google Cloud Console.
+
+Verifique a URI utilizada nos logs ou no código do Thunderbolt. Depois, abra **Credenciais**, seleccione o ID do cliente e adicione a URI exacta em **URIs de redireccionamento autorizadas**. Aguarde um a dois minutos para a configuração se propagar, limpe o cache do navegador e tente novamente.
+
+### Erro `invalid_request` ou `access_denied`
+
+Confirme se o seu e-mail foi adicionado como utilizador de teste no passo 5. Verifique também se os escopos necessários estão activos, especialmente `youtube.upload`.
+
+### Mensagem “Acesso bloqueado: solicitação inválida”
+
+Na maioria dos casos, esta mensagem está relacionada com uma URI de redireccionamento incorrecta. Reveja cuidadosamente os passos 6 e 7, verificando protocolo, domínio, porta, caminho e barras finais.
+
+## Escopos importantes para o YouTube
+
+Para efectuar uploads de vídeos, o Thunderbolt utiliza principalmente os seguintes escopos OAuth:
+
+| Escopo | Descrição |
+|---|---|
+| `https://www.googleapis.com/auth/youtube` | Gerir a sua conta do YouTube |
+| `https://www.googleapis.com/auth/youtube.upload` | Gerir os seus vídeos do YouTube e efectuar uploads |
+| `https://www.googleapis.com/auth/youtube.readonly` | Visualizar a sua conta do YouTube; opcional |
+
+> **Boa prática de segurança:** mantenha o Client Secret fora do código, dos ficheiros versionados e de mensagens públicas. Use variáveis de ambiente e restrinja o acesso às credenciais.
+
+## Referências
+
+- [Google Cloud Console](https://console.cloud.google.com/)
+- [YouTube Data API v3](https://developers.google.com/youtube/v3)
+- [Documentação OAuth 2.0 do Google](https://developers.google.com/identity/protocols/oauth2)