@danhachuel/thunderbolt 0.2.28 → 0.2.30

package/MANUAL-INSTALACAO.md

@@ -2,7 +2,7 @@
 
 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.28
+> **Versão deste manual:** 0.2.30
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -100,13 +100,13 @@ Execute:
 Windows PowerShell ou MobaXterm:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.28 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.30 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.2.28 install
+npx --yes @danhachuel/thunderbolt@0.2.30 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.
@@ -362,18 +362,29 @@ Após iniciar a aplicação, valide o seguinte percurso:
 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:** em **Importar do YouTube**, use o método **Página pública — sem API Key** com um URL `/channel/UC...`, um handle ou uma subpágina `/videos`; o parser resolve o ID, consulta a página pública e tenta o RSS quando necessário. Confirme que o resultado abre o formulário de revisão sem Data API Key. Se o canal não existir ou não fornecer metadados, confirme a mensagem clara e que o formulário de uma pesquisa anterior desaparece. A Data API é opcional e fica separada; em **Cadastro manual**, preencha os dados sem qualquer consulta externa.
-5. **Pipeline > Criação de Vídeos:** teste primeiro o modo **Canal específico** e depois os modos de lote.
-6. **Criação de Vídeos > Vídeos:** verifique o estado `to_do` e os botões **Iniciar** e **Parar** dentro da subaba. Confirme também que **Criação de Músicas** mostra o mesmo fluxo com título próprio.
-7. **Upload:** configure o OAuth Client ID e Secret, autorize primeiro o **youtube-automation-agent** na própria aba, confirme o estado **pronto para publicar**, preencha título/descrição/tags e publique um MP4 real. O botão **Autorizar fallback OAuth** existe apenas para redundância; a Data API Key, se configurada, é exclusivamente para consultas oficiais públicas e nunca substitui OAuth.
-8. **Pipeline > Limpador de Metadados:** 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 das páginas de criação não são aceites nesta área.
-9. **Configurações > Configurações Técnicas:** confirme que os caminhos e credenciais estão locais e não aparecem no Git.
-10. **Criação de Vídeos:** confirme que `Pexels/Pixabay` substitui o label antigo, que `Estilo IA` aparece apenas em `full_ia` e que `Apenas Música` exige áudio e guarda `background_mode=none`.
-11. **Automação:** no cartão de cada canal, escolha o **Blueprint padrão** e a **Voz padrão**, clique em `Guardar` e confirme que o resumo do cartão se actualiza. Configure também **Automação ON** e um horário `HH:MM`; confirme a lista de vídeos cadastrados. Os mesmos defaults aparecem em **Canais** e são usados em novas tarefas. A UI não inicia jobs em segundo plano nesta entrega.
-12. **Configurações > Configurações Técnicas > Teste de vozes:** teste Edge/Azure ou provider configurado e confirme reprodução/download sem criação de tarefa.
-13. **Upload directo:** configure manualmente cookies, sessionInfo e INNERTUBE_API_KEY, atribua o `DELEGATED_SESSION_ID` no canal e teste apenas com um vídeo de validação. O método envia chunks de 256 KiB e não extrai cookies do navegador.
-14. **Configurações > MCP > Client MCP:** confirme que Short Video Maker, AutoVio, OpenMontage e OpenCut aparecem com as portas padrão editáveis. O estado **Activo** é uma preferência local; a detecção deve indicar **Não detectado** quando os serviços externos não estiverem instalados ou iniciados.
-15. **Configurações > MCP > Servidor MCP:** abra a subaba, mantenha o host `127.0.0.1`, active **Servidor MCP ON** e clique em **Guardar e iniciar Servidor MCP**. Confirme o endpoint `/mcp` e o health endpoint `/health`. Mantenha **Permitir ferramentas de escrita** desactivado até precisar que um agente crie lotes.
-16. **Configurações > MCP > Skill:** clique em **Guardar skill localmente** e confirme o ficheiro em `storage/skills/moneyprinterturbo-video.md`; opcionalmente use **Descarregar skill .md** para obter a cópia através do navegador.
+5. **Niche Finder:** abra a página na sidebar e aguarde a preparação automática. Confirme que não aparece upload de CSV, botão de download de dataset ou selector de ficheiros. A análise inicial deve carregar directamente métricas, clusters, gráfico Plotly, regras de associação e dados analisados. Altere país, engagement, datas e tags e confirme que **Analisar Nichos** recalcula os resultados.
+6. **Pipeline > Criação de Vídeos:** teste primeiro o modo **Canal específico** e depois os modos de lote.
+7. **Criação de Vídeos > Vídeos:** verifique o estado `to_do` e os botões **Iniciar** e **Parar** dentro da subaba. Confirme também que **Criação de Músicas** mostra o mesmo fluxo com título próprio.
+8. **Upload:** configure o OAuth Client ID e Secret, autorize primeiro o **youtube-automation-agent** na própria aba, confirme o estado **pronto para publicar**, preencha título/descrição/tags e publique um MP4 real. O botão **Autorizar fallback OAuth** existe apenas para redundância; a Data API Key, se configurada, é exclusivamente para consultas oficiais públicas e nunca substitui OAuth.
+9. **Pipeline > Limpador de Metadados:** 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 das páginas de criação não são aceites nesta área.
+10. **Configurações > Configurações Técnicas:** confirme que os caminhos e credenciais estão locais e não aparecem no Git.
+11. **Criação de Vídeos:** confirme que `Pexels/Pixabay` substitui o label antigo, que `Estilo IA` aparece apenas em `full_ia` e que `Apenas Música` exige áudio e guarda `background_mode=none`.
+12. **Automação:** no cartão de cada canal, escolha o **Blueprint padrão** e a **Voz padrão**, clique em `Guardar` e confirme que o resumo do cartão se actualiza. Configure também **Automação ON** e um horário `HH:MM`; confirme a lista de vídeos cadastrados. Os mesmos defaults aparecem em **Canais** e são usados em novas tarefas. A UI não inicia jobs em segundo plano nesta entrega.
+13. **Configurações > Configurações Técnicas > Teste de vozes:** teste Edge/Azure ou provider configurado e confirme reprodução/download sem criação de tarefa.
+14. **Upload directo:** configure manualmente cookies, sessionInfo e INNERTUBE_API_KEY, atribua o `DELEGATED_SESSION_ID` no canal e teste apenas com um vídeo de validação. O método envia chunks de 256 KiB e não extrai cookies do navegador.
+15. **Configurações > MCP > Client MCP:** confirme que Short Video Maker, AutoVio, OpenMontage e OpenCut aparecem com as portas padrão editáveis. O estado **Activo** é uma preferência local; a detecção deve indicar **Não detectado** quando os serviços externos não estiverem instalados ou iniciados.
+16. **Configurações > MCP > Servidor MCP:** abra a subaba, mantenha o host `127.0.0.1`, active **Servidor MCP ON** e clique em **Guardar e iniciar Servidor MCP**. Confirme o endpoint `/mcp` e o health endpoint `/health`. Mantenha **Permitir ferramentas de escrita** desactivado até precisar que um agente crie lotes.
+17. **Configurações > MCP > Skill:** clique em **Guardar skill localmente** e confirme o ficheiro em `storage/skills/moneyprinterturbo-video.md`; opcionalmente use **Descarregar skill .md** para obter a cópia através do navegador.
+
+## Niche Finder
+
+A página **Niche Finder** integra a lógica adaptada do projecto open source [johanfortus/Niche-Finder](https://github.com/johanfortus/Niche-Finder), cujo projecto original usa K-Means e FP-Growth sobre o dataset público [Trending Youtube Video Statistics (113 Countries)](https://www.kaggle.com/datasets/asaniczka/trending-youtube-videos-113-countries). No Thunderbolt não existe Flask, rota HTTP adicional, template HTML, JavaScript D3 ou segundo processo; toda a análise é síncrona no Streamlit.
+
+Ao abrir a página, o Thunderbolt prepara automaticamente os dados públicos através do KaggleHub e inicia a análise. O utilizador não precisa de baixar datasets, carregar CSVs, preparar planilhas ou escolher ficheiros. A interface apresenta directamente os parâmetros da busca e os resultados.
+
+Os parâmetros da UI são número de clusters entre 2 e 10, suporte mínimo entre 0,01 e 0,50, país, engagement, intervalo de datas e tags. O núcleo normaliza os dados, calcula engagement, aplica filtros, faz transformação logarítmica e standardização, executa K-Means e calcula itemsets/regras com FP-Growth. A análise inicial é automática; o botão **Analisar Nichos** recalcula os resultados depois de alterar os filtros. Os resultados são DataFrames de clusters, itemsets frequentes, regras de associação e dados analisados; o gráfico de dispersão é criado nativamente com Plotly.
+
+As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.2.30 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ## Pipeline: Criação de Vídeos, Criação de Músicas e Automação
 

package/README.md

@@ -17,6 +17,7 @@ A primeira versão implementa a camada UI independente com:
 | Canais | Subabas de importação pública sem API Key, Data API opcional e cadastro manual independente |
 | Criação de Vídeos / Criação de Músicas | Subabas Criar vídeo e Vídeos; lotes; 51 rótulos de idioma; Pexels/Pixabay, full IA com Estilo IA e Apenas Música com agente musical; a segunda página reutiliza o mesmo fluxo com título próprio |
 | Automação | Lista de vídeos e canais, selectores editáveis de Blueprint/voz padrão, Automação ON e horário diário HH:MM; UI configurável sem worker em segundo plano |
+| Niche Finder | Preparação e análise automáticas, filtros, K-Means, FP-Growth, regras de associação, clusters e gráfico Plotly nativo |
 | Upload | YouTube via `youtube-automation-agent` adaptado internamente, OAuth directo de redundância, Upload directo experimental, TikTok, Instagram e Facebook Pages no front end |
 | MCP | Catálogo local opcional de Short Video Maker, AutoVio, OpenMontage e OpenCut, com portas editáveis e activação |
 | Limpador de Metadados | Upload isolado de vídeos terceiros, limpeza FFmpeg, edição de título/descrição/tags e manifesto JSON |
@@ -25,9 +26,9 @@ A primeira versão implementa a camada UI independente com:
 
 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.
 
-## Navegação da UI 0.2.28
+## Navegação da UI 0.2.30
 
-A barra lateral mantém apenas os cinco níveis principais, nesta ordem: **Início**, **Pipeline**, **Automação**, **Niche Finder** e **Configurações**. **Pipeline** é expansível e contém **Criação de Vídeos**, **Criação de Músicas**, **Upload** e **Limpador de Metadados**. **Configurações** é expansível e contém **Canais**, **Blueprints**, **MCP** e **Configurações Técnicas**. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas. Niche Finder permanece como placeholder vazio nesta versão.
+A barra lateral mantém apenas os cinco níveis principais, nesta ordem: **Início**, **Pipeline**, **Automação**, **Niche Finder** e **Configurações**. **Pipeline** é expansível e contém **Criação de Vídeos**, **Criação de Músicas**, **Upload** e **Limpador de Metadados**. **Configurações** é expansível e contém **Canais**, **Blueprints**, **MCP** e **Configurações Técnicas**. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
 
 ## Instalação
 
@@ -108,9 +109,9 @@ thunderbolt
 No Windows PowerShell, se `npx` for bloqueado por `npx.ps1`, use directamente `npx.cmd`:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.2.28 install
-npx.cmd --yes @danhachuel/thunderbolt@0.2.28 doctor
-npx.cmd --yes @danhachuel/thunderbolt@0.2.28
+npx.cmd --yes @danhachuel/thunderbolt@0.2.30 install
+npx.cmd --yes @danhachuel/thunderbolt@0.2.30 doctor
+npx.cmd --yes @danhachuel/thunderbolt@0.2.30
 ```
 
 Como alternativa, pode permitir scripts para o seu utilizador:
@@ -128,6 +129,14 @@ 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`.
 
+## Niche Finder
+
+A página **Niche Finder** integra a lógica do projecto open source [johanfortus/Niche-Finder](https://github.com/johanfortus/Niche-Finder) directamente no processo Streamlit. O Thunderbolt não inicia Flask, não abre uma porta adicional e não copia templates HTML ou D3. Ao abrir a página, o próprio Thunderbolt prepara automaticamente os dados públicos necessários através do KaggleHub, guarda a cache localmente e executa a análise; o utilizador não precisa de baixar datasets, carregar CSVs ou preparar planilhas.
+
+A interface apresenta directamente os parâmetros da busca: número de clusters entre 2 e 10, suporte mínimo entre 0,01 e 0,50, país, categoria de engagement, intervalo de datas e tags. A análise inicial é executada automaticamente e **Analisar Nichos** permite recalcular os resultados depois de alterar os filtros. O núcleo aplica normalização, filtros, `log1p`, `StandardScaler`, K-Means e FP-Growth. Os resultados aparecem em DataFrames para clusters, itemsets frequentes, regras de associação e dados analisados, acompanhados por uma visualização Plotly nativa e pesquisa de palavras nos clusters.
+
+As dependências adicionais são instaladas pelo fluxo normal do pacote: `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub`. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.2.30 install`; o instalador detecta e reutiliza componentes já válidos.
+
 ## Armazenamento local
 
 O sistema cria automaticamente:
@@ -146,6 +155,8 @@ storage/
 │   └── settings.json
 ├── music/             # músicas locais para o modo Apenas Música
 ├── voice_previews/    # amostras isoladas do teste de vozes
+├── data/
+│   └── niches/        # dados automáticos cacheados para o Niche Finder
 ├── skills/            # skill MoneyPrinterTurbo guardada pelo utilizador
 ├── metadata_cleaner/
 │   ├── originals/    # cópias dos vídeos terceiros enviados

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+## Niche-Finder
+
+Thunderbolt adapts the data-analysis ideas and parts of the clustering/tag-association logic from [johanfortus/Niche-Finder](https://github.com/johanfortus/Niche-Finder), Copyright (c) 2024 Johan Fortus and Vincent Milland. The original project is licensed under the MIT License. Thunderbolt does not include the original Flask server, HTML templates, JavaScript/D3 visualizations or route layer; the functionality was adapted to the existing Streamlit process.
+
+> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/app/main.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import re
+from datetime import date
 import sys
 from pathlib import Path
 
@@ -18,6 +19,8 @@ except (OSError, json.JSONDecodeError):
 
 from hermes_ui.domain import STAGES, create_batch, create_channel, create_tasks_for_batch, delete_channel, pipeline_summary, set_channel_defaults, transition_task, update_channel
 from hermes_ui.storage import BLUEPRINTS, ensure_storage, list_blueprint_files, load_blueprint_file, now, read_json, write_json
+from app.modules.niche_finder.core import NicheAnalysisError, run_niche_analysis
+from app.modules.niche_finder.data_loader import DatasetError, download_kaggle_dataset, load_dataframe
 from hermes_ui.blueprints import create_blueprint_from_link, list_branding_files, save_generated_blueprint
 from hermes_ui.metadata_cleaner import build_description, clean_video_metadata, list_edit_records, metadata_manifest, normalize_tags, save_edit_record, store_external_video
 from hermes_ui.mcp import detect_local_service, install_skill_locally, load_integrations, load_server_config, read_packaged_skill, save_server_config, update_integration
@@ -626,9 +629,132 @@ def render_music_creation():
     render_new_video(page_title="Criação de Músicas")
 
 
+@st.cache_data(show_spinner=False)
+def _cached_niche_dataset(path_str: str, modified_ns: int):
+    return load_dataframe(path_str)
+
+
+@st.cache_data(show_spinner=False)
+def _cached_niche_download():
+    return str(download_kaggle_dataset())
+
+
+def _load_automatic_niche_dataset():
+    dataset_path = _cached_niche_download()
+    path = Path(dataset_path)
+    return dataset_path, _cached_niche_dataset(dataset_path, path.stat().st_mtime_ns)
+
+
+def _niche_tag_options(frame) -> list[str]:
+    tags: set[str] = set()
+    for value in frame.get("video_tags", []):
+        text = str(value or "").replace('"', "").replace("'", "")
+        for tag in re.split(r"[|,]", text.strip("[]")):
+            tag = re.sub(r"\s+", " ", tag).strip().lower()
+            if tag and tag not in {"nan", "none", "null"}:
+                tags.add(tag)
+    return sorted(tags)
+
+
+def _niche_date_bounds(frame):
+    dates = frame["publish_date"].dropna().astype(str)
+    if dates.empty:
+        return None, None
+    return dates.min(), dates.max()
+
+
 def render_niche_finder():
     st.title("Niche Finder")
-    st.info("Esta área está reservada para o Niche Finder e será implementada numa próxima etapa.")
+    st.caption("Busca automática de padrões, nichos e tags para orientar canais faceless.")
+    st.info("O Thunderbolt prepara e analisa automaticamente os dados necessários. Não é necessária configuração manual.")
+
+    try:
+        with st.spinner("A preparar automaticamente o Niche Finder…"):
+            dataset_path, frame = _load_automatic_niche_dataset()
+    except (DatasetError, OSError) as exc:
+        st.error("Não foi possível preparar automaticamente o Niche Finder neste momento. Verifique a ligação à Internet e tente novamente.")
+        with st.expander("Detalhes técnicos"):
+            st.caption(str(exc))
+        return
+
+    signature = f"{dataset_path}:{Path(dataset_path).stat().st_mtime_ns}"
+    if st.session_state.get("niche_results_signature") != signature:
+        st.session_state.pop("niche_results", None)
+        st.session_state["niche_results_signature"] = signature
+
+    min_date, max_date = _niche_date_bounds(frame)
+    countries = ["Todos"] + sorted(str(value) for value in frame["country"].dropna().unique())
+    tag_options = _niche_tag_options(frame)
+    with st.sidebar:
+        st.subheader("Parâmetros da busca")
+        n_clusters = st.slider("Número de Clusters", 2, 10, 5, key="niche_n_clusters")
+        min_support = st.slider("Suporte Mínimo", 0.01, 0.5, 0.05, 0.01, format="%.2f", key="niche_min_support")
+        country = st.selectbox("País", countries, key="niche_country")
+        engagement = st.selectbox("Engagement", ["Todos", "High", "Moderate", "Low"], key="niche_engagement")
+        start_date = st.date_input("Data inicial", value=date.fromisoformat(min_date), min_value=date.fromisoformat(min_date), max_value=date.fromisoformat(max_date), key="niche_start_date") if min_date else None
+        end_date = st.date_input("Data final", value=date.fromisoformat(max_date), min_value=date.fromisoformat(min_date), max_value=date.fromisoformat(max_date), key="niche_end_date") if max_date else None
+        selected_tags = st.multiselect("Tags opcionais", tag_options, key="niche_tags")
+        analyse = st.button("Analisar Nichos", type="primary", use_container_width=True, key="niche_analyse")
+
+    results = st.session_state.get("niche_results")
+    if results is None or analyse:
+        try:
+            if start_date and end_date and start_date > end_date:
+                raise NicheAnalysisError("A data inicial não pode ser posterior à data final.")
+            with st.spinner("A analisar nichos automaticamente…"):
+                results = run_niche_analysis(
+                    str(dataset_path),
+                    n_clusters=n_clusters,
+                    min_support=min_support,
+                    start_date=start_date.isoformat() if start_date else None,
+                    end_date=end_date.isoformat() if end_date else None,
+                    country=country,
+                    engagement=engagement,
+                    tags=selected_tags,
+                )
+            st.session_state["niche_results"] = results
+        except (NicheAnalysisError, DatasetError, OSError) as exc:
+            st.error("Não foi possível concluir a análise automática com os filtros actuais.")
+            with st.expander("Detalhes técnicos"):
+                st.caption(str(exc))
+            return
+
+    summary = results.get("summary", {})
+    metric_cols = st.columns(4)
+    for col, (label, value) in zip(metric_cols, [("Registos analisados", summary.get("rows_filtered", 0)), ("Clusters", summary.get("cluster_count", 0)), ("Itemsets frequentes", summary.get("frequent_item_count", 0)), ("Regras de associação", summary.get("association_rule_count", 0))]):
+        with col:
+            card(label, value)
+
+    cluster_table = results["clusters"]
+    rules_table = results["association_rules"]
+    items_table = results["frequent_items"]
+    points = results["cluster_points"].copy()
+    keyword = st.text_input("Filtrar palavras-chave nos clusters", key="niche_cluster_keyword", placeholder="Ex.: música, gaming, receitas")
+    if keyword.strip():
+        cluster_table = cluster_table[cluster_table["palavras"].str.contains(keyword.strip(), case=False, na=False)]
+    tab_clusters, tab_rules, tab_data = st.tabs(["Clusters encontrados", "Regras de associação", "Dados analisados"])
+    with tab_clusters:
+        st.dataframe(cluster_table, use_container_width=True, hide_index=True)
+        if not points.empty:
+            try:
+                import plotly.express as px
+                points["cluster"] = points["cluster_id"].astype(str)
+                hover = [column for column in ["title", "channel_name", "country", "view_count", "engagement_rate"] if column in points.columns]
+                figure = px.scatter(points, x="x", y="y", color="cluster", hover_data=hover, title="Distribuição dos clusters")
+                figure.update_layout(legend_title_text="Cluster")
+                st.plotly_chart(figure, use_container_width=True)
+            except ImportError:
+                st.error("A visualização da análise não está disponível nesta instalação.")
+    with tab_rules:
+        if rules_table.empty:
+            st.info("Não foram encontradas regras com os filtros actuais. Reduza o suporte mínimo ou escolha outro filtro.")
+        else:
+            st.dataframe(rules_table, use_container_width=True, hide_index=True)
+        if not items_table.empty:
+            st.subheader("Itemsets frequentes")
+            st.dataframe(items_table, use_container_width=True, hide_index=True)
+    with tab_data:
+        st.dataframe(results["raw_data"], use_container_width=True, hide_index=True)
 
 
 def render_videos():

package/app/modules/__init__.py

@@ -0,0 +1 @@
+"""Reusable Streamlit modules bundled with Thunderbolt."""

package/app/modules/niche_finder/__init__.py

@@ -0,0 +1,12 @@
+"""Streamlit-native Niche Finder integration for Thunderbolt."""
+
+from .core import NicheAnalysisError, run_niche_analysis
+from .data_loader import DATA_DIR, DatasetError, download_kaggle_dataset
+
+__all__ = [
+    "DATA_DIR",
+    "DatasetError",
+    "NicheAnalysisError",
+    "download_kaggle_dataset",
+    "run_niche_analysis",
+]

package/app/modules/niche_finder/core.py

@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import ast
+import json
+import re
+from collections import Counter
+from typing import Any, Iterable
+
+import numpy as np
+import pandas as pd
+
+from .data_loader import DatasetError, download_kaggle_dataset, load_dataframe
+from .models import NicheAnalysisResult
+
+
+EMPTY_CLUSTER_COLUMNS = [
+    "cluster_id",
+    "palavras",
+    "tamanho",
+    "media_visualizacoes",
+    "media_engagement",
+]
+EMPTY_ITEM_COLUMNS = ["itemsets", "support", "item_count"]
+EMPTY_RULE_COLUMNS = ["antecedents", "consequents", "support", "confidence", "lift"]
+
+
+class NicheAnalysisError(ValueError):
+    """Raised when a valid dataset cannot produce a meaningful analysis."""
+
+
+def _parse_tags(value: Any) -> list[str]:
+    if value is None or (isinstance(value, float) and np.isnan(value)):
+        return []
+    if isinstance(value, (list, tuple, set)):
+        raw_items = value
+    else:
+        text = str(value).strip()
+        if not text or text.lower() in {"nan", "none", "null", "[]"}:
+            return []
+        raw_items: Iterable[Any]
+        if text.startswith("[") and text.endswith("]"):
+            try:
+                parsed = json.loads(text)
+            except json.JSONDecodeError:
+                try:
+                    parsed = ast.literal_eval(text)
+                except (ValueError, SyntaxError):
+                    parsed = None
+            raw_items = parsed if isinstance(parsed, (list, tuple, set)) else re.split(r"[|,]", text.strip("[]"))
+        else:
+            raw_items = re.split(r"[|,]", text)
+    tags: list[str] = []
+    for item in raw_items:
+        tag = re.sub(r"\s+", " ", str(item).replace('"', "").replace("'", "")).strip().lower()
+        if tag and tag not in {"nan", "none", "null"}:
+            tags.append(tag)
+    return list(dict.fromkeys(tags))
+
+
+def _engagement_label(value: str | int | None) -> str:
+    if value is None or str(value).strip().lower() in {"", "todos", "all"}:
+        return "Todos"
+    if isinstance(value, str) and value in {"High", "Moderate", "Low"}:
+        return value
+    try:
+        numeric = int(value)
+    except (TypeError, ValueError):
+        return "Todos"
+    if numeric >= 67:
+        return "High"
+    if numeric >= 33:
+        return "Moderate"
+    return "Low"
+
+
+def _filter_frame(
+    frame: pd.DataFrame,
+    *,
+    start_date: str | None,
+    end_date: str | None,
+    country: str | None,
+    engagement: str | int | None,
+    tags: Iterable[str] | None,
+) -> pd.DataFrame:
+    filtered = frame.copy()
+    if start_date:
+        filtered = filtered[filtered["publish_date"] >= str(start_date)]
+    if end_date:
+        filtered = filtered[filtered["publish_date"] <= str(end_date)]
+    if country and str(country).strip().lower() not in {"", "todos", "all"}:
+        filtered = filtered[filtered["country"].str.casefold() == str(country).strip().casefold()]
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        filtered["engagement_rate"] = np.where(
+            filtered["view_count"] > 0,
+            ((filtered["like_count"] + filtered["comment_count"]) / filtered["view_count"]) * 100,
+            0.0,
+        )
+    filtered["engagement_rate"] = filtered["engagement_rate"].replace([np.inf, -np.inf], np.nan).fillna(0.0)
+    label = _engagement_label(engagement)
+    if label == "High":
+        filtered = filtered[filtered["engagement_rate"] >= 7]
+    elif label == "Moderate":
+        filtered = filtered[(filtered["engagement_rate"] >= 3) & (filtered["engagement_rate"] < 7)]
+    elif label == "Low":
+        filtered = filtered[filtered["engagement_rate"] < 3]
+
+    selected_tags = {str(tag).strip().casefold() for tag in (tags or []) if str(tag).strip()}
+    if selected_tags:
+        filtered = filtered[filtered["video_tags"].map(lambda value: bool(selected_tags.intersection(_parse_tags(value))))]
+    return filtered.drop_duplicates(subset="title", keep="first").reset_index(drop=True)
+
+
+def _empty_frame(columns: list[str]) -> pd.DataFrame:
+    return pd.DataFrame(columns=columns)
+
+
+def _cluster_analysis(frame: pd.DataFrame, requested_clusters: int) -> tuple[pd.DataFrame, pd.DataFrame]:
+    if frame.empty:
+        return _empty_frame(EMPTY_CLUSTER_COLUMNS), pd.DataFrame()
+    from sklearn.cluster import KMeans
+    from sklearn.decomposition import PCA
+    from sklearn.preprocessing import StandardScaler
+
+    features = frame[["view_count", "like_count"]].clip(lower=0).astype(float)
+    transformed = np.log1p(features)
+    scaled = StandardScaler().fit_transform(transformed)
+    n_clusters = max(1, min(int(requested_clusters), len(frame)))
+    if n_clusters == 1:
+        labels = np.zeros(len(frame), dtype=int)
+    else:
+        labels = KMeans(n_clusters=n_clusters, random_state=42, n_init=10).fit_predict(scaled)
+    points = frame.copy()
+    points["cluster_id"] = labels.astype(int)
+    if len(points) >= 2:
+        coordinates = PCA(n_components=2, random_state=42).fit_transform(scaled)
+    else:
+        coordinates = np.column_stack([scaled[:, 0], np.zeros(len(points))])
+    points["x"] = coordinates[:, 0]
+    points["y"] = coordinates[:, 1]
+
+    summaries: list[dict[str, Any]] = []
+    for cluster_id, group in points.groupby("cluster_id", sort=True):
+        counter = Counter(tag for value in group["video_tags"] for tag in _parse_tags(value))
+        words = ", ".join(tag for tag, _ in counter.most_common(8))
+        summaries.append(
+            {
+                "cluster_id": int(cluster_id),
+                "palavras": words,
+                "tamanho": int(len(group)),
+                "media_visualizacoes": round(float(group["view_count"].mean()), 2),
+                "media_engagement": round(float(group["engagement_rate"].mean()), 2),
+            }
+        )
+    return pd.DataFrame(summaries, columns=EMPTY_CLUSTER_COLUMNS), points
+
+
+def _frequent_item_analysis(frame: pd.DataFrame, min_support: float) -> tuple[pd.DataFrame, pd.DataFrame]:
+    if frame.empty:
+        return _empty_frame(EMPTY_ITEM_COLUMNS), _empty_frame(EMPTY_RULE_COLUMNS)
+    from mlxtend.frequent_patterns import association_rules, fpgrowth
+
+    tag_lists = frame["video_tags"].map(_parse_tags)
+    tag_counts = Counter(tag for tags in tag_lists for tag in tags)
+    if not tag_counts:
+        return _empty_frame(EMPTY_ITEM_COLUMNS), _empty_frame(EMPTY_RULE_COLUMNS)
+    frequent_tags = {tag for tag, count in tag_counts.items() if count > len(frame) * 0.5}
+    tag_lists = tag_lists.map(lambda tags: [tag for tag in tags if tag not in frequent_tags])
+    all_tags = sorted({tag for tags in tag_lists for tag in tags})
+    if not all_tags:
+        return _empty_frame(EMPTY_ITEM_COLUMNS), _empty_frame(EMPTY_RULE_COLUMNS)
+    matrix = pd.DataFrame(
+        [{tag: tag in tags for tag in all_tags} for tags in tag_lists],
+        columns=all_tags,
+    ).astype(bool)
+    itemsets = fpgrowth(matrix, min_support=float(min_support), use_colnames=True, max_len=3)
+    if itemsets.empty:
+        return _empty_frame(EMPTY_ITEM_COLUMNS), _empty_frame(EMPTY_RULE_COLUMNS)
+    itemsets = itemsets.copy()
+    itemsets["item_count"] = itemsets["itemsets"].map(len)
+    itemsets["itemsets"] = itemsets["itemsets"].map(lambda values: ", ".join(sorted(values)))
+    itemsets = itemsets[["itemsets", "support", "item_count"]].sort_values(["support", "item_count"], ascending=[False, True]).reset_index(drop=True)
+
+    raw_itemsets = fpgrowth(matrix, min_support=float(min_support), use_colnames=True, max_len=3)
+    try:
+        rules = association_rules(raw_itemsets, metric="confidence", min_threshold=0.5)
+    except TypeError:  # mlxtend compatibility across versions
+        rules = association_rules(raw_itemsets, num_itemsets=len(matrix), metric="confidence", min_threshold=0.5)
+    if rules.empty:
+        return itemsets, _empty_frame(EMPTY_RULE_COLUMNS)
+    rules = rules[rules["lift"] > 1.0].copy()
+    if rules.empty:
+        return itemsets, _empty_frame(EMPTY_RULE_COLUMNS)
+    for column in ("antecedents", "consequents"):
+        rules[column] = rules[column].map(lambda values: ", ".join(sorted(values)))
+    wanted = [column for column in EMPTY_RULE_COLUMNS if column in rules.columns]
+    rules = rules[wanted].sort_values(["lift", "confidence"], ascending=False).reset_index(drop=True)
+    return itemsets, rules
+
+
+def run_niche_analysis(
+    dataset_path: str | None = None,
+    n_clusters: int = 5,
+    min_support: float = 0.01,
+    *,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    country: str | None = None,
+    engagement: str | int | None = None,
+    tags: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Run the adapted Niche-Finder analysis synchronously in the caller process.
+
+    The first three parameters preserve the integration contract described in
+    ``exemplo.md``. Additional keyword-only filters retain the original project's
+    date, country, engagement and tag controls for the Thunderbolt UI.
+    """
+    if not 2 <= int(n_clusters) <= 10:
+        raise NicheAnalysisError("O número de clusters deve estar entre 2 e 10.")
+    if not 0.001 <= float(min_support) <= 0.5:
+        raise NicheAnalysisError("O suporte mínimo deve estar entre 0,001 e 0,5.")
+    path = download_kaggle_dataset() if dataset_path is None else dataset_path
+    try:
+        frame = load_dataframe(path)
+    except DatasetError as exc:
+        raise NicheAnalysisError(str(exc)) from exc
+    filtered = _filter_frame(
+        frame,
+        start_date=start_date,
+        end_date=end_date,
+        country=country,
+        engagement=engagement,
+        tags=tags,
+    )
+    if filtered.empty:
+        raise NicheAnalysisError("Nenhum vídeo corresponde aos filtros seleccionados.")
+    clusters, points = _cluster_analysis(filtered, int(n_clusters))
+    frequent_items, rules = _frequent_item_analysis(filtered, float(min_support))
+    result = NicheAnalysisResult(
+        clusters=clusters,
+        frequent_items=frequent_items,
+        association_rules=rules,
+        raw_data=filtered,
+        cluster_points=points,
+        summary={
+            "rows_input": int(len(frame)),
+            "rows_filtered": int(len(filtered)),
+            "cluster_count": int(len(clusters)),
+            "frequent_item_count": int(len(frequent_items)),
+            "association_rule_count": int(len(rules)),
+            "top_tags": [str(value) for value in frequent_items["itemsets"].head(10).tolist()] if not frequent_items.empty else [],
+        },
+    )
+    return result.as_dict()

package/app/modules/niche_finder/data_loader.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import pandas as pd
+
+from hermes_ui.storage import STORAGE
+
+try:
+    import kagglehub
+except ImportError:  # pragma: no cover - exercised in installations before the extra dependency is installed
+    kagglehub = None
+
+
+DATA_DIR = STORAGE / "data" / "niches"
+DEFAULT_DATASET_SLUG = "asaniczka/trending-youtube-videos-113-countries"
+DEFAULT_DATASET_FILENAME = "trending_yt_videos_113_countries.csv"
+DEFAULT_DATASET_PATH = DATA_DIR / DEFAULT_DATASET_FILENAME
+
+REQUIRED_COLUMNS = (
+    "title",
+    "publish_date",
+    "country",
+    "view_count",
+    "like_count",
+    "comment_count",
+)
+OPTIONAL_COLUMNS = (
+    "video_tags",
+    "channel_name",
+    "thumbnail_url",
+    "video_id",
+    "channel_id",
+)
+
+
+class DatasetError(RuntimeError):
+    """Raised when the automatic Niche Finder dataset cannot be read or validated."""
+
+
+def ensure_data_dir() -> Path:
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    return DATA_DIR
+
+
+def _find_csv(root: Path) -> Path | None:
+    candidates = sorted(root.rglob("*.csv"))
+    if not candidates:
+        return None
+    for candidate in candidates:
+        if candidate.name.lower() == DEFAULT_DATASET_FILENAME.lower():
+            return candidate
+    return candidates[0]
+
+
+def _copy_csv(source: Path, destination: Path) -> Path:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if source.resolve() != destination.resolve():
+        shutil.copy2(source, destination)
+    return destination
+
+
+def _download_with_kagglehub() -> Path | None:
+    if kagglehub is None:
+        return None
+    data_dir = ensure_data_dir()
+    try:
+        downloaded = kagglehub.dataset_download(DEFAULT_DATASET_SLUG, output_dir=str(data_dir))
+    except TypeError:
+        downloaded = kagglehub.dataset_download(DEFAULT_DATASET_SLUG)
+    except Exception as exc:  # pragma: no cover - depends on network/provider state
+        raise DatasetError(f"O Thunderbolt não conseguiu preparar os dados automáticos: {exc}") from exc
+    source = _find_csv(Path(downloaded))
+    if source is None:
+        raise DatasetError("A preparação automática terminou sem encontrar dados compatíveis.")
+    return _copy_csv(source, DEFAULT_DATASET_PATH)
+
+
+def download_kaggle_dataset() -> Path:
+    """Prepare and cache the public Niche-Finder dataset without user interaction."""
+    ensure_data_dir()
+    if DEFAULT_DATASET_PATH.exists() and DEFAULT_DATASET_PATH.stat().st_size > 0:
+        return DEFAULT_DATASET_PATH
+    if kagglehub is None:
+        raise DatasetError("O componente automático de dados não está disponível nesta instalação.")
+    downloaded = _download_with_kagglehub()
+    if downloaded is None:
+        raise DatasetError("O componente automático de dados não devolveu um caminho válido.")
+    return downloaded
+
+
+def validate_dataset(frame: pd.DataFrame) -> pd.DataFrame:
+    """Validate the internal dataset schema and return a normalised copy."""
+    if frame is None or frame.empty:
+        raise DatasetError("A fonte automática de dados não contém registos.")
+    cleaned = frame.copy()
+    cleaned.columns = [str(column).strip() for column in cleaned.columns]
+    missing = [column for column in REQUIRED_COLUMNS if column not in cleaned.columns]
+    if missing:
+        raise DatasetError("A fonte automática não contém as colunas necessárias: " + ", ".join(missing) + ".")
+    if "video_tags" not in cleaned.columns:
+        cleaned["video_tags"] = ""
+    for column in ("view_count", "like_count", "comment_count"):
+        cleaned[column] = pd.to_numeric(cleaned[column], errors="coerce")
+    cleaned["publish_date"] = pd.to_datetime(cleaned["publish_date"], errors="coerce").dt.strftime("%Y-%m-%d")
+    cleaned["country"] = cleaned["country"].astype("string").str.strip()
+    cleaned["title"] = cleaned["title"].astype("string").fillna("").str.strip()
+    cleaned = cleaned.dropna(subset=["publish_date", "view_count", "like_count", "comment_count"])
+    cleaned = cleaned[cleaned["title"] != ""].copy()
+    if cleaned.empty:
+        raise DatasetError("A fonte automática não contém registos válidos depois da normalização.")
+    return cleaned.reset_index(drop=True)
+
+
+def load_dataframe(path: str | Path) -> pd.DataFrame:
+    try:
+        frame = pd.read_csv(path)
+    except (OSError, UnicodeDecodeError, pd.errors.ParserError, pd.errors.EmptyDataError) as exc:
+        raise DatasetError(f"Não foi possível ler a fonte automática de dados: {exc}") from exc
+    return validate_dataset(frame)

package/app/modules/niche_finder/models.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+
+@dataclass(frozen=True)
+class DatasetInfo:
+    """Metadata about a cached or uploaded Niche Finder dataset."""
+
+    path: Path
+    source: str
+    rows: int
+    columns: tuple[str, ...]
+
+
+@dataclass
+class NicheAnalysisResult:
+    """Structured result returned by ``run_niche_analysis``.
+
+    The dictionaries are intentionally DataFrame-based so the Streamlit renderer
+    can display, filter and export each result without depending on Flask or HTML.
+    """
+
+    clusters: pd.DataFrame
+    frequent_items: pd.DataFrame
+    association_rules: pd.DataFrame
+    raw_data: pd.DataFrame
+    cluster_points: pd.DataFrame
+    summary: dict[str, Any]
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "clusters": self.clusters,
+            "frequent_items": self.frequent_items,
+            "association_rules": self.association_rules,
+            "raw_data": self.raw_data,
+            "cluster_points": self.cluster_points,
+            "summary": self.summary,
+        }

package/hermes_ui/storage.py

@@ -12,6 +12,7 @@ ROOT = Path(__file__).resolve().parents[1]
 STORAGE = Path(os.getenv("THUNDERBOLT_STORAGE_DIR") or ROOT / "storage")
 STATE = STORAGE / "state"
 BLUEPRINTS = STORAGE / "blueprints"
+NICHES_DATA = STORAGE / "data" / "niches"
 SEED_BLUEPRINTS = ROOT / "seed" / "blueprints"
 
 DEFAULTS: dict[str, Any] = {
@@ -218,7 +219,7 @@ def seed_blueprints() -> None:
 
 
 def ensure_storage() -> None:
-    for path in [STATE, BLUEPRINTS / "canais", BLUEPRINTS / "nichos", BLUEPRINTS / "importados", BLUEPRINTS / "brandings", STORAGE / "brand", STORAGE / "scripts", STORAGE / "thumbnails", STORAGE / "videos", STORAGE / "artifacts", STORAGE / "skills", STORAGE / "metadata_cleaner", STORAGE / "metadata_cleaner" / "outputs", STORAGE / "music", STORAGE / "voice_previews"]:
+    for path in [STATE, BLUEPRINTS / "canais", BLUEPRINTS / "nichos", BLUEPRINTS / "importados", BLUEPRINTS / "brandings", STORAGE / "brand", STORAGE / "scripts", STORAGE / "thumbnails", STORAGE / "videos", STORAGE / "artifacts", STORAGE / "skills", STORAGE / "metadata_cleaner", STORAGE / "metadata_cleaner" / "outputs", STORAGE / "music", STORAGE / "voice_previews", NICHES_DATA]:
         path.mkdir(parents=True, exist_ok=True)
     seed_blueprints()
     for filename, default in DEFAULTS.items():

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.2.28",
+  "version": "0.2.30",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "main": "scripts/cli.mjs",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "app/main.py",
+    "app/modules/**/*.py",
     "hermes_ui/*.py",
     "integrations/*.py",
     "integrations/data/*.json",
@@ -18,6 +19,7 @@
     "seed/skills/*.md",
     "README.md",
     "MANUAL-INSTALACAO.md",
+    "THIRD-PARTY-NOTICES.md",
     "requirements.txt",
     "package.json"
   ],

package/requirements.txt

@@ -7,3 +7,9 @@ google-auth>=2.29,<3
 google-auth-oauthlib>=1.2,<2
 google-api-python-client>=2.120,<3
 edge-tts>=7.0,<8
+scikit-learn>=1.3,<2
+mlxtend>=0.23,<1
+plotly>=5.18,<7
+seaborn>=0.13,<1
+matplotlib>=3.7,<4
+kagglehub>=0.3,<1

package/scripts/cli.mjs

@@ -79,6 +79,8 @@ function ensureRuntimeStorage() {
     join(storageRoot, "skills"),
     join(storageRoot, "music"),
     join(storageRoot, "voice_previews"),
+    join(storageRoot, "data"),
+    join(storageRoot, "data", "niches"),
   ];
   for (const directory of directories) mkdirSync(directory, { recursive: true });
   const seedRoot = resolve(root, "seed", "blueprints");
@@ -98,7 +100,7 @@ function check() {
     console.error(`Python não encontrado. Execute: npx.cmd --yes @danhachuel/thunderbolt install`);
     process.exit(1);
   }
-  const requiredModules = ["streamlit", "requests", "pandas", "toml", "imageio_ffmpeg", "edge_tts"];
+  const requiredModules = ["streamlit", "requests", "pandas", "toml", "imageio_ffmpeg", "edge_tts", "sklearn", "mlxtend", "plotly", "seaborn", "kagglehub"];
   const missing = requiredModules.filter((moduleName) => !moduleAvailable(moduleName));
   const ffmpeg = moduleAvailable("imageio_ffmpeg");
   const mptPath = configuredMoneyPrinterPath();

package/scripts/install.mjs

@@ -110,6 +110,8 @@ function ensureDirs() {
     join(storageRoot, "skills"),
     join(storageRoot, "music"),
     join(storageRoot, "voice_previews"),
+    join(storageRoot, "data"),
+    join(storageRoot, "data", "niches"),
   ];
   for (const directory of directories) mkdirSync(directory, { recursive: true });
   copySeedBlueprints(storageRoot);