Agency Docs Updater
Execute TODAS as etapas automaticamente em sequência. Pause apenas se uma etapa falhar e não puder ser recuperada. Leia references/learnings.md antes de começar para armadilhas conhecidas.
Configuração: os caminhos são lidos do arquivo .env na raiz da skill (veja .env.example). Os padrões funcionam para a configuração padrão. Variáveis de ambiente principais: VAULT_DIR, DOCS_SITE_DIR, YOUTUBE_UPLOADER_DIR, PRESENTATIONS_DIR, SKILLS_REPO_DIR, SKILLS_LOCAL_DIR, ZOOM_CREDENTIALS_DIR, GITHUB_REPO, SITE_DOMAIN.
Dependências (verifique se existem antes de executar):
- zoom — Download de gravações do Zoom (
scripts/zoom_meetings.py) - fathom — Fallback de vídeo Fathom (
scripts/download_video.py) - nano-banana — Geração de sobreposição de thumbnail (
scripts/generate_image.sh) - calendar-sync — apenas local, sincronização de eventos de calendário (
sync.sh) - youtube-uploader — processamento de vídeo, upload e autenticação da API do YouTube
Etapa 0: Analisar Argumentos e Carregar Config
Carregue .env da raiz da skill. Em seguida, divida args por espaços em branco:
- Token de 8 dígitos (
YYYYMMDD) →DATE - "yesterday" →
DATE = $(date -v-1d +%Y%m%d) - "today" ou ausente →
DATE = $(date +%Y%m%d) - Token de 2 dígitos (
NN) oulab-NN→LAB_FILTER
Expanda as variáveis de ambiente para caminhos usados nas etapas subsequentes:
VAULT_DIR="${VAULT_DIR:-$HOME/Brains/brain}"
DOCS_SITE_DIR="${DOCS_SITE_DIR:-$HOME/Sites/agency-docs}"
YOUTUBE_UPLOADER_DIR="${YOUTUBE_UPLOADER_DIR:-$HOME/ai_projects/youtube-uploader}"
SKILLS_REPO_DIR="${SKILLS_REPO_DIR:-$HOME/ai_projects/claude-skills}"
SKILLS_LOCAL_DIR="${SKILLS_LOCAL_DIR:-$HOME/.claude/skills}"
ZOOM_CREDENTIALS_DIR="${ZOOM_CREDENTIALS_DIR:-$HOME/.zoom_credentials}"
PRESENTATIONS_DIR="${PRESENTATIONS_DIR:-$HOME/ai_projects/claude-code-lab}"
GITHUB_REPO="${GITHUB_REPO:-glebis/agency-docs}"
SITE_DOMAIN="${SITE_DOMAIN:-agency-lab.glebkalinin.com}"
Etapa 1: Encontrar Transcrição do Fathom
Se LAB_FILTER estiver definido: ${VAULT_DIR}/${DATE}-claude-code-lab-${LAB_FILTER}.md
Se vazio: glob ${VAULT_DIR}/${DATE}-claude-code-lab-*.md (escolha o mais recente por mtime).
Se estiver faltando: execute ${SKILLS_LOCAL_DIR}/calendar-sync/sync.sh, verifique novamente, pare se ainda estiver faltando.
Extraia do frontmatter YAML e armazene:
FATHOM_FILE,SHARE_URL,MEETING_TITLE,DATE,LAB_NUMBERVIDEO_NAME=${DATE}-claude-code-lab-${LAB_NUMBER}TRANSCRIPT_LANG= detectar automaticamente das primeiras ~50 linhas (proporção de cirílico > 0.3 →ru, senãoen)
Determinar MEETING_NUMBER: verifique arquivos MDX existentes em ${DOCS_SITE_DIR}/content/docs/claude-code-internal-${LAB_NUMBER}/meetings/ para um placeholder com a data de hoje. Se encontrado, use esse número. Caso contrário, verifique os tamanhos de conteúdo do arquivo para encontrar o próximo slot vazio. Armazene como string de dois dígitos com zero à esquerda (ex.: 04). Esta variável é usada nas Etapas 3b, 4b, 5, 6 e 8.
Etapa 2: Baixar Vídeo
Pule se ${VAULT_DIR}/${VIDEO_NAME}.mp4 existir e for maior que 1 MB.
Nota: As gravações do Zoom podem levar ~15 minutos para processar após o término de uma reunião. Se a API do Zoom não retornar gravações, aguarde e tente novamente antes de recorrer ao Fathom.
Principal — Zoom:
python3 ${SKILLS_REPO_DIR}/zoom/scripts/zoom_meetings.py recordings \
--start ${DATE:0:4}-${DATE:4:2}-${DATE:6:2} \
--end $(date -j -v+1d -f %Y%m%d ${DATE} +%Y-%m-%d) \
--show-downloads 2>&1
Encontre a URL MP4, então:
TOK=$(python3 -c "import json,pathlib; print(json.load(open(pathlib.Path('${ZOOM_CREDENTIALS_DIR}')/'oauth_token.json'))['access_token'])")
curl -L -H "Authorization: Bearer ${TOK}" -o ${VAULT_DIR}/${VIDEO_NAME}.mp4 "${MP4_DOWNLOAD_URL}"
Fallback — Fathom (se não houver gravação do Zoom):
cd ${VAULT_DIR} && python3 ${SKILLS_LOCAL_DIR}/fathom/scripts/download_video.py \
"${SHARE_URL}" --output-name "${VIDEO_NAME}"
Etapa 3: Enviar para o YouTube
cd ${YOUTUBE_UPLOADER_DIR} && \
python3 process_video.py \
--video ${VAULT_DIR}/${VIDEO_NAME}.mp4 \
--fathom-transcript ${FATHOM_FILE} \
--title "${MEETING_TITLE}" \
--upload
Execute com run_in_background: true (10-30 min). Em caso de falha: --resume-from upload.
Extraia YOUTUBE_URL da saída padrão (✓ YouTube video: ...) ou processed/metadata/${VIDEO_NAME}.json.
Extraia VIDEO_ID da URL (a parte após ?v= ou o último segmento do caminho).
Etapa 3a: Verificar Upload (OBRIGATÓRIO)
Após extrair VIDEO_ID, verifique se o vídeo realmente existe no YouTube antes de prosseguir. Vídeos podem falhar silenciosamente no processamento ou ser excluídos automaticamente pela revisão de conteúdo do YouTube.
cd ${YOUTUBE_UPLOADER_DIR} && PYTHONPATH=. python3 -c "
from auth import get_authenticated_service
import sys, time
youtube = get_authenticated_service()
video_id = '${VIDEO_ID}'
# Poll up to 5 minutes for video to become available
for attempt in range(10):
resp = youtube.videos().list(part='status,processingDetails', id=video_id).execute()
if not resp['items']:
if attempt < 9:
print(f'Video not yet available (attempt {attempt+1}/10), waiting 30s...')
time.sleep(30)
continue
print(f'FATAL: Video {video_id} not found after 5 minutes. Upload may have failed.')
sys.exit(1)
status = resp['items'][0]['status']
processing = resp['items'][0].get('processingDetails', {})
upload_status = status.get('uploadStatus', 'unknown')
privacy = status.get('privacyStatus', 'unknown')
rejection = status.get('rejectionReason', None)
print(f'Upload status: {upload_status}, Privacy: {privacy}')
if rejection:
print(f'REJECTED: {rejection}')
sys.exit(1)
if upload_status in ('processed', 'uploaded'):
print(f'✓ Video {video_id} verified OK')
sys.exit(0)
if upload_status == 'failed':
print(f'FATAL: Upload failed — {status.get(\"failureReason\", \"unknown\")}')
sys.exit(1)
print(f'Status: {upload_status}, waiting 30s...')
time.sleep(30)
print('FATAL: Video not ready after 5 minutes')
sys.exit(1)
"
Se a verificação falhar: exclua os metadados do vídeo com falha (rm processed/metadata/${VIDEO_NAME}.json), reenvie com --resume-from upload e verifique novamente. NÃO prossiga para as etapas MDX ou thumbnail com um VIDEO_ID não verificado.
Inicie a Etapa 4 em paralelo — o resumo não depende da URL do YouTube.
Etapa 3b: Thumbnail no Estilo do Laboratório (OBRIGATÓRIO)
Sempre execute esta etapa — ela substitui a thumbnail genérica do process_video.py pelo modelo de laboratório com marca. A thumbnail genérica NÃO é aceitável para publicação.
Pré-requisitos: VIDEO_ID deve ser conhecido (aguarde a conclusão da Etapa 3, se necessário).
Siga references/thumbnail-guide.md para o fluxo de trabalho completo:
- Gere imagem de sobreposição Nano Banana (prompt específico do tópico dos padrões de prompt do guia)
- Leia/inspecione a imagem bruta para confirmar a cor de fundo e, em seguida, recolorir as linhas para laranja (#e85d04)
- Escreva um arquivo HTML temporário (ex.:
/tmp/lab-meeting-${MEETING_NUMBER}.html) com base em${YOUTUBE_UPLOADER_DIR}/templates/images/lab-meeting.html— atualize o número da reunião, texto hero do tópico, descrições dos marcadores, data. Não edite o template original diretamente. - Renderize com Playwright em 1280×720 →
${YOUTUBE_UPLOADER_DIR}/processed/thumbnails/${VIDEO_NAME}.jpg - Leia/inspecione a thumbnail renderizada para verificar o layout antes de enviar
- Envie para o YouTube: use
VIDEO_IDextraído da Etapa 3
NÃO pule esta etapa ou confie na thumbnail do process_video.py.
Etapa 4: Gerar Resumo Verificado por Fatos
Leia ${FATHOM_FILE}. Gere um resumo estruturado em ${TRANSCRIPT_LANG}:
- Cabeçalhos de seção
##, marcadores, exemplos de código quando relevante - Termos técnicos em inglês (MCP, Skills, Claude Code, etc.)
- Exclua detalhes pessoais de agendamento
- Sanitize para MDX: escape caracteres
<,>e{nus que quebrariam a compilação MDX
Verifique as alegações de recursos do Claude Code usando o subagente claude-code-guide (se disponível; pule a verificação se o agente não estiver acessível). Salve o resumo corrigido no scratchpad como summary.md.
Etapa 4b: Atualizar Metadados do YouTube
Após a conclusão das Etapas 3 e 4. VIDEO_ID, MEETING_NUMBER e LAB_NUMBER devem estar todos determinados antes desta etapa. Leia references/youtube-api.md para o formato da descrição e trechos da API.
Gere a descrição do YouTube a partir do resumo. Use o template apropriado para o idioma:
- Se
TRANSCRIPT_LANG=en: Rótulos em inglês ("In this video:", "Course materials and session notes:") - Se
TRANSCRIPT_LANG=ru: Rótulos em russo ("В этом видео:", "Материалы и конспект занятия:")
NÃO misture idiomas em uma única descrição.
URL da página da reunião: https://${SITE_DOMAIN}/claude-code-lab-${LAB_NUMBER}/meetings/${MEETING_NUMBER}
Atualize título, descrição, tags via API do YouTube e, em seguida, adicione o vídeo à playlist "Claude Code Lab ${LAB_NUMBER}" (criada automaticamente se não existir).
Etapa 5: Gerar MDX
python3 ${SKILLS_LOCAL_DIR}/agency-docs-updater/scripts/update_meeting_doc.py \
${FATHOM_FILE} "${YOUTUBE_URL}" ${SCRATCHPAD}/summary.md
Antes de executar: verifique se já existe um MDX placeholder para a data de hoje (grep -l em meetings/). Se sim, use -n ${MEETING_NUMBER} --update para direcioná-lo.
Após executar:
- Remova o conteúdo Marp anexado (tudo após o
---de fechamento do resumo antes de<!-- _class: lead -->) — MDX quebra em comentários HTML (<!-- -->),<sem escape e caracteres{nus - Verifique o arquivo de apresentação: procure em
${PRESENTATIONS_DIR}/presentations/lab-${LAB_NUMBER}/e${PRESENTATIONS_DIR}/lesson-generator/por arquivos correspondentes a${DATE}. Se encontrado, copie para${DOCS_SITE_DIR}/public/${DATE}-claude-code-lab-${LAB_NUMBER}.htmle adicione link no MDX - Substitua placeholders do frontmatter (
[Название встречи],[Краткое описание встречи],[Дата встречи]) - Se
TRANSCRIPT_LANG=en, reescreva o MDX inteiramente com rótulos em inglês — o script usa russo por padrão e o fallback de tradução produz saída corrompida com idiomas misturados - Verifique:
cd ${DOCS_SITE_DIR} && npm run build 2>&1 | tail -5
Etapa 6: Commit e Push
Apenas prepare os arquivos do pipeline — nunca git add .:
cd ${DOCS_SITE_DIR}
git fetch origin main
BEHIND=$(git rev-list --count HEAD..origin/main)
if [ "$BEHIND" -gt 0 ]; then
git stash push -m "agency-docs-updater: temp stash"
git pull --rebase origin main
git stash pop || true
fi
git add content/docs/claude-code-internal-${LAB_NUMBER}/meetings/${MEETING_NUMBER}.mdx
# Only stage presentation HTML if it was copied
[ -f public/${DATE}-claude-code-lab-${LAB_NUMBER}.html ] && git add public/${DATE}-claude-code-lab-${LAB_NUMBER}.html
git commit -m "Add Lab ${LAB_NUMBER} Meeting ${MEETING_NUMBER}"
git push
Armazene COMMIT_HASH=$(git rev-parse HEAD) para a Etapa 7.
Etapa 7: Aguardar Implantação Vercel
TIMEOUT=300; ELAPSED=0
until [ "$(gh api repos/${GITHUB_REPO}/commits/${COMMIT_HASH}/status --jq '.state' 2>/dev/null || echo 'pending')" != "pending" ]; do
sleep 15; ELAPSED=$((ELAPSED+15))
[ "$ELAPSED" -ge "$TIMEOUT" ] && echo "Deploy timeout after ${TIMEOUT}s" && break
done
DEPLOY_STATE=$(gh api repos/${GITHUB_REPO}/commits/${COMMIT_HASH}/status --jq '.state')
echo "Deploy state: ${DEPLOY_STATE}"
Execute com run_in_background: true. Se o estado for failure ou error: verifique os logs do Vercel (vercel logs), corrija localmente, faça push novamente e reinicie esta etapa.
Etapa 8: Verificar no Navegador
Abra https://${SITE_DOMAIN}/claude-code-lab-${LAB_NUMBER}/meetings/${MEETING_NUMBER} em um navegador (via ferramentas de automação Chrome ou manualmente). Verifique se o embed do YouTube está visível. Se não: verifique o VIDEO_ID, aguarde o processamento do YouTube ou reenvie.
Relatório do Pipeline
Após a conclusão, relate: caminho do Fathom, caminho do vídeo, URL do YouTube, caminho MDX, hash do commit, status do deploy, verificação do embed.