0053 — Central de ajuda na ordem da jornada¶

Status: RASCUNHO → APROVADA → EM IMPLEMENTAÇÃO → CONCLUÍDA

A spec tem três partes, escritas em ordem, e quatro portões — cada um revisado por um subagente de contexto limpo, em até 3 rodadas. A máquina de revisão é do plugin superpowers; a régua é a rubrica correspondente em .claude/rubrics/. Achados vêm classificados: qualquer Critical reprova, Important em aberto reprova salvo decisão registrada do usuário, e Minor vira pendência aceita.

1. A Parte I diz qual é o problema e como se convive com ele hoje. Revisada na seção 6 (necessidade × jornada de hoje). É o portão mais barato de todos, e o único que pergunta contra que problema isto está sendo construído.
2. A Parte II diz como se usa o que vai existir. Revisada na seção 8 (jornada × viewports).
3. A Parte III diz como se constrói. Revisada na seção 16 (segurança × clareza técnica) — autorização, isolamento, e se sobrou decisão para quem vai codar.
4. A implementação é medida contra as três, na seção 17 (aderência × qualidade × testes) — uma revisão por fase, e uma da branch inteira antes de fechar.

Cada parte só se escreve depois que a anterior passou. Descrever tela sobre problema mal enquadrado, ou detalhar endpoint sobre experiência vaga, é o jeito mais caro de descobrir que era outra coisa.

Parte I — O problema¶

Aqui não entra solução: nem tela, nem endpoint, nem botão. Só o que dói, para quem, e o que se faz hoje. Se você já sabe qual é a tela, guarde para a Parte II.

1. Dor¶

A Ajuda existe para quem ainda não sabe usar o Garantora, e hoje ela pede justamente que a pessoa já saiba onde procurar. O catálogo é pequeno — três tutoriais publicados, em três assuntos —, e mesmo assim quem entra vê um de cada vez: o resto está recolhido sob nomes de assunto que só fazem sentido para quem já conhece o produto.

A dor aparece em dois momentos, e cada um tem a sua consequência:

• Ao chegar, a pessoa não vê o que existe. Quem abre a Ajuda com uma pergunta na cabeça — "como ativo as consultas de crédito?" — não encontra a pergunta em lugar nenhum: encontra nomes de assunto ("Gestão de imobiliárias", "Gestão da garantidora", "Análise de crédito pela imobiliária") e precisa adivinhar em qual deles a resposta mora. Não há como perguntar pelo termo. E nada no que ela vê diz para quem cada tutorial é: dos três, um ensina o lado da imobiliária parceira e dois o da garantidora, e só um dos nomes de assunto deixa isso aparente. Consequência: a garantidora nova — a pessoa para quem a Ajuda é a única tela útil antes de configurar qualquer coisa (RN13a da spec 0042) — pode não achar o tutorial do passo que ela precisa dar primeiro, e passa a depender de perguntar ao time. Isso anula o que a Ajuda existe para dar, que é aprender sem depender de ninguém.
• Ao assistir, o índice e o vídeo não ficam na vista ao mesmo tempo. O roteiro do tutorial (os passos com o tempo de cada um) está inteiro abaixo do vídeo. Quem quer rever um trecho rola até o passo, clica — e o vídeo pula para lá fora da vista; é preciso rolar de volta para vê-lo. E enquanto o vídeo toca sozinho, o roteiro não acompanha: ele só marca o passo que foi clicado, então quem para no meio não sabe em que ponto da lista está. Consequência: o roteiro — que foi feito para servir de índice navegável (spec 0042) — deixa de ser usado como índice, porque usá-lo custa perder o vídeo de vista a cada clique. Rever um passo vira arrastar a barra do player às cegas.

O celular soma um agravante: ali, as duas ações do topo do tutorial ("Ir para a tela" e "Ver o assunto") aparecem só como ícone, sem rótulo — e a primeira é o que leva a pessoa do vídeo à tela onde ela vai fazer o que acabou de aprender.

2. Quem sente¶

Não há operação a medir — produção está no ar sem cliente nenhum (ver CLAUDE.md, Estágio do produto). A dor foi levantada analisando a tela em desktop e celular, não relatada por alguém que se perdeu; o alcance se sustenta pelo desenho do produto:

• ADMIN_TENANT de uma garantidora nova — quem sente primeiro e mais. É o caminho obrigatório de todo cliente: antes de operar, ele configura a garantidora e traz as imobiliárias parceiras, e dois dos três tutoriais ensinam exatamente isso. É também quem mais depende da Ajuda, porque é quem ainda não conhece nenhuma tela.
• AGENCY_USER — o corretor da imobiliária parceira. Tem um tutorial dele ("Abrir uma análise de crédito"), e esse assunto já vem primeiro na lista para quem tem o papel (RN13 da 0045). Sente menos na chegada e o mesmo ao assistir: é o tutorial mais longo (7:09, treze passos), e portanto o de índice mais comprido abaixo do vídeo. É o papel com mais chance de estar no celular.
• Pessoa nova na equipe interna (ANALYST, OPERATOR) — mesma chegada do ADMIN_TENANT, sem tutorial próprio ainda.

É caminho obrigatório, não exceção: todo tutorial é aberto pela mesma lista e assistido pela mesma página, então os dois pontos de quebra valem para qualquer pessoa que use a Ajuda. E pioram com o catálogo: cada tutorial novo entra num assunto recolhido, e cada um mais longo empurra o índice para mais longe do vídeo.

3. A jornada de hoje¶

Os tutoriais chegam a quem precisa pelo item Ajuda do menu — o time não manda link por fora, e por isso não há caminho paralelo por WhatsApp ou e-mail a descrever. O que existe fora do sistema é o desfecho quando a Ajuda não responde: perguntar a alguém.

Garantidora nova, querendo ativar as consultas de crédito (desktop, 1280px)¶

1. Clica em Ajuda no menu. A página abre no primeiro assunto da lista — para o ADMIN_TENANT, "Gestão de imobiliárias", promovido pelo papel — com um único cartão ("Cadastrar uma imobiliária parceira") numa grade com lugar para mais, e o espaço ao lado dele vazio.
2. À direita, a barra de assuntos lista os três nomes; só o assunto aberto mostra os tutoriais de dentro. Aqui quebra: a pergunta dela é "consultas de crédito", e nenhum dos nomes diz isso. O tutorial está em "Gestão da garantidora", que ela precisa abrir para descobrir.
3. Se não abrir — ou abrir o assunto errado primeiro —, volta ao menu e procura a tela por conta própria, ou pergunta ao time. Sem cliente em produção, "o time" hoje é quem escreveu o produto; com o primeiro cliente, é um pedido de ajuda que a Ajuda devia ter evitado.

Qualquer pessoa, revendo um passo do tutorial (desktop, 1280px)¶

1. Abre o tutorial. O vídeo ocupa a largura da coluna de conteúdo, com a barra de assuntos ao lado; o roteiro começa abaixo do vídeo.
2. Assiste. O roteiro não acompanha o que está tocando — nenhum passo fica marcado.
3. Quer rever "O pacote locatício" (passo 6 de 13): rola a página até o roteiro, clica no passo. O vídeo pula — fora da vista. Aqui quebra: rola de volta para cima para ver o trecho que pediu, e para escolher outro passo, desce de novo.
4. O contorno é ignorar o roteiro e arrastar a barra do player até achar o trecho.

Corretor no celular (375px)¶

1. Abre a Ajuda; vê os assuntos numa sanfona, com o dele aberto (fix 0014). Toca no tutorial.
2. O tutorial dele só tem gravação de computador, então o vídeo vem com o aviso "Esta gravação foi feita no computador" — a tela gravada, reduzida a 375px de largura. O roteiro vem embaixo. Tocar num passo pula o vídeo e ele sai da tela, como no desktop — e aqui, onde ler a tela gravada já exige atenção, perder o vídeo de vista custa mais.
3. No topo, dois ícones sem texto. Aqui quebra, de novo: para ir à tela de análise de crédito depois do vídeo, ele precisa saber que a seta é "ir para a tela".

O que já se tentou¶

A Ajuda já foi reorganizada três vezes, e cada vez resolveu um problema real — o que sobrou é o que nenhuma delas mirou:

• Spec 0042 criou a Ajuda como uma grade só de cartões, ordenada por papel. Tudo visível, mas sem agrupamento — e ela previa o catálogo crescendo.
• Spec 0042, na página do tutorial, punha o roteiro ao lado do vídeo, em duas colunas a partir de 1200px.
• Spec 0045 agrupou os tutoriais por assunto, com um navegador à direita, e manteve essa barra aberta dentro do tutorial para o próximo vídeo do assunto ficar à vista. Resolveu o agrupamento; o custo foi passar a mostrar um assunto de cada vez, e empurrar o roteiro para baixo do vídeo, porque três colunas não cabiam.
• Fix 0014 trocou, no celular, a faixa de pílulas de assunto por uma sanfona, porque a faixa escondia metade dos assuntos atrás de uma rolagem lateral que a tela não anunciava.

As duas quebras de hoje foram decisões conscientes da 0045, e as premissas delas não se confirmaram:

• Busca foi cogitada e adiada (0045, seção 5): o agrupamento seria "a resposta escolhida para achar", e somar busca antes de o agrupamento existir seria "desenhar no escuro". O agrupamento existe agora, e olhando a tela o que se vê é que ele responde a quem já sabe o nome do assunto — não a quem chega com a pergunta, que é quem a Ajuda serve primeiro (seção 1).
• O roteiro desceu para baixo do vídeo de propósito (0045, 7.1), com o argumento de que ele "é lido em sequência, e abaixo do vídeo é onde a leitura em sequência começa". Na prática o roteiro serve de índice — é para saltar a um passo que ele tem tempos e é clicável (RN2a da 0042) —, e índice se usa com o vídeo à vista, não depois dele. A premissa da leitura em sequência vale para a primeira vez que se assiste; a dor da seção 1 é a de quem volta para rever.

4. Resultado esperado¶

Três verificações, as três conferíveis olhando a tela:

1. Na chegada, tudo o que existe está à vista. Em 1280×800, os três tutoriais publicados aparecem na primeira tela da Ajuda, sem clique e sem rolagem.
2. O índice e o vídeo ficam juntos. Na página do tutorial, escolher qualquer passo leva o vídeo àquele ponto sem o vídeo sair da vista — no desktop e no celular.
3. Quem chega com um termo, acha. Procurar por "API Full", "corretor" ou "documentos" leva ao tutorial que trata disso, sem a pessoa precisar saber o nome do assunto.

5. Fora de escopo¶

• Tutorial novo ou regravação. O conteúdo são os três tutoriais publicados, como estão; nada é gravado de novo.
• Canal de suporte ("Não achou? Fale com o suporte"). Foi cogitado — a proposta original tinha esse rodapé —, mas o produto não tem hoje canal de suporte nenhum dentro do app, nem e-mail nem WhatsApp, e criar um é decisão de operação, não de tela.
• O diálogo de ajuda por campo (o "?" das telas de cadastro) — é outra ajuda, com outro propósito, e não muda.
• Restringir o que cada papel vê. Continua valendo a RN7 da spec 0042: todo autenticado vê todos os tutoriais. Cogitado e recusado: esconder o que é "do outro lado" não protege nada, e quem aprende costuma querer ver o que o outro lado faz.

6. Revisão do problema¶

Preenchido pelo laço do /spec new, rubrica .claude/rubrics/problema.md. Registrar todas as rodadas, inclusive as reprovadas.

Resultado: aprovada na rodada 1.

Triagem do que a rodada apontou, corrigido antes da Parte II: o Important (a seção 3 dizia que nenhuma tentativa anterior tratou busca nem a distância entre índice e vídeo, quando a 0045 tratou as duas e as decidiu de propósito) virou o confronto explícito com as premissas da 0045; a citação da promoção de assunto passou da RN8 da 0042 para a RN13 da 0045; a jornada do celular ganhou o fato de o tutorial do corretor só ter gravação de computador.

Pendências aceitas:

• Minor — a seção 4 carrega a forma da solução ("sem clique e sem rolagem", "procurar por"). Fica: são os critérios de pronto que o usuário escolheu na entrevista, e a forma verificável deles é o que a Parte III vai transformar em critério de aceite.

Parte II — A experiência¶

Não preencher antes da revisão da seção 6 estar aprovada.

7. Jornada pretendida¶

A Ajuda passa a ser uma página só, lida na ordem em que um cliente usa o produto. Os assuntos que já existem viram as etapas numeradas da jornada de uma garantidora — primeiro configurar, depois trazer as imobiliárias, depois operar —, todos abertos ao mesmo tempo, com uma busca por cima. E a página do tutorial volta a ter o índice ao lado do vídeo, agora acompanhando o que toca.

As três etapas, com o nome e a frase curta que cada uma exibe:

O número é a posição na jornada, e é o mesmo para todo mundo. Ninguém tem etapa promovida por papel: o corretor vê a etapa dele como 3, igual a todos. O que diz "isto é para você" passa a ser a etiqueta de público em cada cartão — "Para a garantidora" ou "Para a imobiliária parceira" — e o filtro por público, que a própria pessoa escolhe. A página sempre abre sem filtro, para qualquer papel: todo autenticado vê todos os tutoriais, como já era (RN7 da 0042).

• Ponto de entrada: o item Ajuda do menu, como hoje (no celular, dentro de "Mais"). E o link de um tutorial, que qualquer pessoa pode copiar da página dele e mandar a outra — os links já compartilhados, nos dois formatos que existem hoje, continuam abrindo o tutorial certo.
• Jornada, caso feliz — a garantidora nova querendo ativar as consultas de crédito:
• Clica em Ajuda. Vê as três etapas lado a lado, cada uma com os tutoriais dela, e reconhece "Ativar as consultas de crédito pela API Full" na etapa 1 sem clicar em nada.
• (Se não reconhecer) digita "consulta" na busca; a página fica só com o que casa, e a etapa 1 continua com o número dela.
• Clica no cartão. Abre o tutorial: vídeo à esquerda, capítulos à direita.
• Dá play. O capítulo que está tocando fica marcado, e os anteriores a ele ficam em tom apagado. Quer rever "O token, que é uma senha": clica no capítulo, e o vídeo pula para lá ali mesmo, à vista.
• Terminado, clica em "Ir para Análise de Créditos" (o nome que o menu dá à tela de configurar as consultas) e cai na tela onde faz o que acabou de ver. Ou segue para o próximo tutorial da jornada pelo cartão "Próximo passo", embaixo do vídeo.
• Voltar para a lista preserva o que a pessoa tinha feito lá: a busca digitada e o filtro escolhido continuam aplicados quando ela volta de um tutorial pelo botão voltar do navegador ou pelo link "← Central de ajuda" do alto da página do tutorial. E a lista abre rolada até a etapa do tutorial de onde ela veio, quando há o que rolar: no celular as etapas são empilhadas e quem volta da etapa 3 não cai no topo; no desktop elas são colunas lado a lado, cabem na primeira dobra e não há rolagem a fazer — só quando as etapas passarem a quebrar em segunda linha isso volta a valer. O filtro vence a rolagem: se o filtro preservado esconde a etapa de onde ela veio (chegou lá pelo "Próximo passo"), a lista abre no topo, com o filtro aplicado à vista na barra. Quem chegou ao tutorial por link compartilhado não tem busca nem filtro a preservar: "← Central de ajuda" abre a lista sem filtro e rolada até a etapa daquele tutorial, como qualquer volta. "Abrir no topo" só acontece no caso da frase anterior — quando o filtro preservado esconde a etapa de destino.
• Custo de uso: nenhum campo obrigatório. Achar é olhar (três etapas visíveis) ou, no máximo, digitar uma palavra. O sistema já sabe o papel de quem entrou e não usa isso para esconder nem reordenar nada — usa só para decidir se o botão "Ir para " está liberado, como já fazia (RN9 a RN10a da 0042). Também já sabe em que aparelho a pessoa está, e escolhe a gravação daquele aparelho sem perguntar (RN15 da 0045).

7.1 Desktop¶

A Central de ajuda (lista).

• O item do menu continua se chamando "Ajuda" — é o nome curto que cabe na barra lateral e na gaveta do celular, e renomeá-lo não entra nesta spec.
• Topo do app: título fixo "Central de ajuda", com o ícone de ajuda, e o subtítulo fixo "Tutoriais em vídeo das telas do Garantora" (o mesmo que a tela vazia usa hoje). Não há mais subtítulo que muda com o assunto — era ele que fazia "Ajuda / Gestão de imobiliárias" parecer uma seção do produto.
• Abertura: uma linha de título, "Como fazer na Garantora". A frase que diria o que é a página já está no subtítulo do topo.
• Barra de filtro, no padrão das listas do app (FilterBar, docs/ui-patterns.md): a busca primeiro, e é o que cresce ("Buscar por etapa, assunto ou tela — ex.: API Full, corretor, documentos"); ao lado, o filtro "Para quem" com três opções — Todos, Para a garantidora, Para a imobiliária parceira —, abrindo em Todos. Na mesma linha, à direita — onde a barra das listas põe a contagem —, "3 tutoriais · 16 min" (singular quando for um). O tempo é a soma das durações das gravações que esta pessoa vai ver, arredondada para o minuto mais próximo — hoje 940 segundos, 15min40s, "16 min". A proposta original desenhava o filtro como três pílulas soltas; ele entra no recipiente que o app já usa, que tem largura constante e o mesmo lugar nas outras listas.
• As etapas lado a lado, uma coluna por etapa, na ordem 1, 2, 3. Cada coluna tem o cabeçalho — o número num círculo, o nome da etapa e a frase curta — e embaixo os cartões dela, empilhados. Em 1280px as três colunas cabem lado a lado, e a primeira dobra (1280×800) mostra os três cartões inteiros, sem rolagem. Quando uma etapa ganhar mais tutoriais, a coluna dela cresce para baixo; quando existirem mais etapas do que colunas cabem (cada uma precisa de uns 280px), a seguinte desce para uma nova linha.
• O cartão — o mesmo de hoje, com a etiqueta de público e o atalho para a tela a mais:
• a miniatura em 16:9 com a duração no canto, da gravação que esta pessoa vai assistir (como hoje, RN15a da 0045);
• o título e a frase do tutorial, cada um com duas linhas reservadas — sobrando, o espaço fica vazio; passando, corta com reticências. É o que faz os cartões de etapas diferentes terminarem na mesma altura: cada etapa é uma coluna independente, e um título que quebra em duas linhas deixaria aquela coluna com o cartão mais alto que as vizinhas;
• a etiqueta de público, em cor da marca para a garantidora e em verde para a imobiliária — o texto diz o público, a cor só reforça. O público vem dos papéis que o tutorial declara servir: papel da imobiliária parceira é "Para a imobiliária parceira"; qualquer papel da equipe da garantidora (administração, análise, operação, consulta) é "Para a garantidora". Tutorial que declara os dois lados leva as duas etiquetas e aparece nas duas opções do filtro;
• o atalho "Ir para →", numa segunda linha do rodapé, reservada mesmo quando ele não aparece — lado a lado com a etiqueta ele quebraria a linha nos públicos de nome longo, e aquele cartão ficaria mais alto que os vizinhos. Ele leva direto à tela sem passar pelo vídeo, para quem já assistiu e só quer voltar lá. Aparece só quando a pessoa pode usar aquela tela; quando não pode, o cartão não mostra atalho nenhum, e o motivo fica dito na página do tutorial, que é onde a ação principal mora (RN10 da 0042). Um atalho desabilitado em cada cartão repetiria a mesma recusa três vezes na lista.
• Clicar em qualquer outro ponto do cartão abre o tutorial.
• Não há mais barra de assuntos à direita, nem sanfona: tudo o que ela escondia está aberto na página.

A página do tutorial.

• Topo do app: o mesmo da lista — "Central de ajuda" e o subtítulo fixo —, sem trilha no topo. A trilha de um nível que o topo do app oferece ("‹ rótulo") repetiria o título logo abaixo dele, que é a duplicação que o próprio padrão recusa.
• A volta, no alto do corpo: o link "← Central de ajuda", seguido, como texto não clicável, de "/ 2 · Trazer imobiliárias parceiras" — o número e o nome da etapa do tutorial, para a pessoa saber onde está na jornada. O link leva à lista com a busca e o filtro que ela tinha deixado lá. Tutorial de assunto provisório (7.3) mostra o nome do assunto, sem número. É o mesmo link nos dois viewports — no celular só a parte da etapa sai, por largura.
• Cabeçalho do tutorial, no corpo da página: o título do tutorial, a frase, e numa linha a duração e a etiqueta de público — a mesma ordem do celular (7.2). À direita, duas ações com rótulo: "Copiar link" (contornada) e "Ir para →" (a principal, preenchida). No desktop a principal fica à direita, encostada na borda do conteúdo, como o app faz com a ação principal; nos modos empilhados e no celular ela vem primeiro entre as duas, no lugar que as ordens de 7.1 e 7.2 dão às ações, porque ali a leitura é de cima para baixo e a principal é o que se procura. Quando a principal está desabilitada, o motivo fica logo abaixo dos dois botões — é o único lugar em que ele aparece, nos dois viewports. Abaixo do motivo, e só quando a cópia falha, o campo com o link (7.3). O nome da tela é o que o menu mostra para aquela tela — "Análise de Créditos", "Imobiliárias", "Análise de Crédito" nos três tutoriais de hoje —, nunca "a tela".

As ações ficam no corpo, e não no topo do app, e isto é desvio consciente do padrão (docs/ui-patterns.md, AppBar): o topo do app transforma toda ação em ícone de 44px no celular, e a decisão desta spec é que "Ir para " tenha rótulo também no celular — é a ponte entre aprender e fazer, e um ícone de seta não diz para onde leva. Pôr as ações no corpo nos dois viewports mantém uma página só, em vez de uma no topo no desktop e outra no corpo no celular. - Duas colunas quando a área de conteúdo — a largura que sobra ao lado do menu lateral — tem pelo menos 880px. A coluna de capítulos tem 340px fixos, e o vídeo fica com o resto: em 1280px com o menu aberto (232px), a área tem cerca de 1000px e o vídeo uns 610px de largura (uns 343px de altura). Com o menu recolhido, as duas colunas aparecem em janelas mais estreitas, porque o corte é da área, não da janela.

O vídeo tem teto, e a régua é uma só: a coluna esquerda inteira cabe na altura útil — "altura útil" é a janela menos o topo do app (744px numa janela de 800). A coluna esquerda é o vídeo mais até 180px — reserva, não espaço fixo: quando o tutorial não tem segunda gravação (é o caso de dois dos três de hoje), a linha do aviso não existe e a coluna fica uns 43px mais curta; o teto do vídeo continua calculado pelos 180px, para o vídeo não mudar de tamanho conforme o tutorial. São: a linha "Agora", a linha do aviso de versão e da oferta da outra gravação — que no desktop mora aqui, logo abaixo de "Agora", uma linha só, como hoje — e os cartões "Antes deste / Próximo passo". Disso saem os limites do vídeo, e vale o menor: - 1100px de largura — a 0042 parava em 880, com o vídeo sozinho na coluna; aqui ele divide a linha com os capítulos e a régua de altura já o limita antes disso na maioria das janelas, então o teto maior só age em tela alta e larga, onde 880 deixava faixa vazia demais; - a largura que sobra ao lado da coluna de capítulos (340px); - a largura correspondente a altura útil menos 180px de altura.

Nas janelas comuns quem manda é a largura disponível: em 1280×800, 610px de largura e 343px de altura, com a coluna esquerda somando 523px dentro dos 744 úteis. Em 1920×970, quem manda é a altura — 734px de altura útil menos os 180 dá um vídeo de ~985px (554px de altura), e a coluna soma 734px — o espaço que sobra fica à direita da coluna de capítulos, com o conteúdo alinhado à esquerda como no resto do app.

A gravação de celular, em pé, no computador (quem abre um link com a versão de celular, ou escolhe "Ver a versão para celular"): mesma régua, e aí quem manda é a altura — o player fica com a altura útil menos os 180px, na proporção dela e centralizado na coluna (uns 564px de altura e 260px de largura numa janela de 800), não dentro de um quadro 16:9. A coluna esquerda continua inteira na janela, como no 16:9.

• À esquerda, o vídeo e o que diz respeito a ele, nesta ordem: o vídeo; a linha "Agora: 2:51 · O pacote locatício" — tempo e nome do capítulo que está tocando, a mesma linha nos três modos, sempre colada ao vídeo e acompanhando-o quando ele fica preso; o aviso de versão e a oferta da outra gravação, quando houver (uma linha só, como hoje, RN16 da 0045); e os cartões "Antes deste" e "Próximo passo", lado a lado.
• Os cartões trazem o tutorial anterior e o seguinte na ordem da jornada (etapa 1 → 2 → 3, e dentro da etapa, a ordem dos cartões), sempre a jornada inteira — o filtro e a busca da lista não recortam esta sequência, porque ela responde "o que vem depois disto no produto", não "o que eu estava procurando". Cada cartão mostra título, duração e público, e abre aquele tutorial.
• Nas pontas, o cartão que existe fica no lugar dele e com a largura de sempre — "Antes deste" à esquerda, "Próximo passo" à direita —, e o outro lado fica vazio; um cartão esticado para o dobro pareceria outra coisa. No último tutorial, "Próximo passo" vira "Voltar para a Central de ajuda — este é o último tutorial da jornada". Com o catálogo de hoje isso é o caso comum, não borda: dos três, o primeiro não tem anterior e o último não tem próximo.
• Tutoriais de assunto provisório (7.3) entram na sequência depois da etapa 3, como na lista.
• À direita, os capítulos — um por passo do roteiro ("Abrir uma análise de crédito" tem treze; "Cadastrar uma imobiliária parceira", oito). Cabeçalho "Capítulos · 13 · clique para pular". Cada linha tem o tempo, o nome do passo e a primeira frase dele, cortada em uma linha — três linhas de texto, uns 62px por capítulo, que é de onde saem as contas de quantos cabem. O capítulo que está tocando fica marcado com fundo e barra à esquerda; os anteriores a ele ficam em tom apagado — "anterior" é posição na lista, não prova de que foi assistido: quem pula para o 10 vê do 1 ao 9 apagados.
• Clicar num capítulo leva o vídeo àquele tempo e dá play.
• A geometria, em 1280×800. Acima das colunas ficam o link de volta e o cabeçalho do tutorial — uns 130px. As duas colunas ficam presas logo abaixo do topo do app quando a página rola, e a lista de capítulos tem a altura da janela menos o topo do app (uns 744px em 800, com o topo de 56px) como altura máxima, não fixa — com sete capítulos a caixa tem a altura deles, e não sobra vão ao lado do vídeo. Rolagem própria só quando os capítulos passam da altura máxima; o curso de rolagem da página é o que a coluna mais alta pedir. O que isso dá, no tutorial de treze capítulos:
• Ao abrir: o vídeo inteiro e os primeiros oito ou nove capítulos estão na primeira dobra; o pé da lista está uns 130px abaixo dela.
• Rolando a página uns 130px — é todo o curso da rolagem, porque nada vem depois das colunas —, o cabeçalho sai de cena e as duas colunas param presas: vídeo, "Agora", "Antes deste / Próximo passo" (uns 480px somados, sem a linha de aviso, que este tutorial não tem) e a caixa de capítulos inteira — onze ou doze linhas de cada vez, rolando por dentro nos tutoriais de treze —, tudo à vista ao mesmo tempo. Com o cabeçalho, sai da vista também "Ir para "; aceito, porque é uma rolagem curta de volta e o cartão "Próximo passo" continua ali.
• O capítulo que está tocando entra sozinho na parte visível da lista conforme o vídeo avança, rolando só a lista, nunca a página. Antes de a página rolar, um capítulo no pé da lista pode estar abaixo da dobra; é o mesmo pé que os 130px de rolagem trazem.
• Área de conteúdo abaixo de 880px (a partir de 600px de janela, que é onde o menu lateral aparece): a página empilha, na mesma ordem do celular (7.2) — o link de volta, o vídeo, "Agora", o cabeçalho do tutorial (título, frase, duração e etiqueta), o aviso de versão, as ações e o motivo quando desabilitadas, os capítulos, "Ir para " repetido depois do último capítulo, e "Antes deste / Próximo passo". Os capítulos rolam com a página, sem rolagem própria — com o vídeo preso, por baixo dele; sem, junto com ele — rolagem dentro de rolagem, embaixo de um vídeo preso, é onde o dedo se perde. Diferente do celular em duas coisas: as ações ficam lado a lado, com a largura do próprio rótulo, a principal primeiro — e quando as duas não cabem numa linha (área abaixo de ~400px, janela de 600 a ~690px com o menu aberto), "Copiar link" desce para a linha de baixo —; e cada capítulo mostra a frase, porque a largura cabe.
• Nos modos empilhados, a página não rola sozinha. O capítulo marcado muda conforme o vídeo avança, mas se ele estiver fora da vista, nada se move: a página rolar debaixo do dedo de quem está lendo outro capítulo é pior que o capítulo marcado ficar fora da tela. Só o desktop largo acompanha, e lá rolando só a caixa de capítulos.
• Quando o vídeo fica preso, nos modos empilhados (esta faixa e o celular), e o que acontece quando não fica. Ele fica preso logo abaixo do topo do app enquanto ocupar no máximo 45% da altura útil; passando disso, rola com a página, e então tocar num capítulo rola a página de volta até o vídeo antes de pular para o trecho. Nos dois casos o capítulo escolhido é visto: num, porque o vídeo nunca saiu; no outro, porque a página o traz de volta.

Onde cada caso cai, com as medidas de hoje: - celular em pé com gravação de computador (193px de 686 úteis): preso; - celular em pé com gravação de celular (em pé, ocupa a altura útil): rola, e o toque traz de volta; - janela de 1100×800 com o menu aberto (área de ~820px, vídeo de ~461px contra 45% de 744, que é 335): rola, e o toque traz de volta; - celular deitado ou tablet baixo (932×430, vídeo de ~370px contra 45% de 374): rola, e o toque traz de volta.

A régua é a mesma em toda a faixa empilhada, e é por isso que ela não precisa de exceção declarada: o que muda é se o vídeo fica parado ou se a página o traz de volta.

• "Copiar link" copia o endereço do tutorial como está na barra do navegador — se ele declarar uma versão, a versão vai junto, porque quem escolheu a versão escolheu para quem recebe (RN17a da 0045). Confirma com o aviso curto que o app já usa para isso, no canto de baixo, que some sozinho em poucos segundos: "Link copiado." No celular ele aparece acima da barra de abas, para não ficar por baixo dela.

Busca e filtro, em detalhe:

• A busca procura no título, na frase, nos nomes dos passos, no nome da etapa — ou, no tutorial de assunto provisório (7.3), no nome do assunto dele — e no nome da tela de destino (o rótulo do menu) de cada tutorial, sem diferenciar maiúscula de minúscula nem acento ("analise" acha "análise"). Filtra enquanto se digita. "documentos" acha "Abrir uma análise de crédito" pelos passos "Os documentos obrigatórios" e "Os documentos opcionais"; "corretor" acha "Cadastrar uma imobiliária parceira" pela frase; "imobiliárias", no plural, acha o mesmo tutorial pelo nome da tela de destino ("Imobiliárias") e pela etapa ("Trazer imobiliárias parceiras"), que é como a pessoa costuma escrever o que procura.
• Busca e filtro se somam: o que aparece casa com os dois.
• Etapa sem nenhum tutorial que case some enquanto o filtro vale; as que ficam mantêm o número delas — o número é a etapa, não a posição na tela. Buscar "corretor" mostra só a etapa 2, com o número 2.
• A contagem passa a dizer o resultado, com o tempo do resultado: "1 tutorial · 4 min".
• Com busca ou filtro aplicado, a barra mostra a segunda linha que ela já tem nas outras listas: o que está aplicado ("Para a imobiliária parceira", o termo buscado), cada um removível, e "Limpar filtros".
• As colunas não se reacomodam quando uma etapa some: cada coluna tem sempre a largura que teria com todas as etapas, e as que ficam se juntam à esquerda. Uma etapa sozinha ocupa uma coluna, não a largura inteira — um cartão de 1000px de miniatura seria a lista mudando de natureza porque alguém digitou uma palavra.

7.2 Mobile (375px)¶

A Central de ajuda (lista).

• Topo do app: "Central de ajuda", como no desktop.
• Abertura: só o título, "Como fazer na Garantora".
• Barra de filtro no padrão mobile das listas (MobileFilterBar): a busca em largura cheia e, abaixo, a pílula "Para quem" (FilterPill), que abre as três opções; a contagem ("3 tutoriais · 16 min") fica abaixo da pílula, onde essa barra a põe. Mesmo comportamento do desktop: abre em Todos, soma com a busca.
• As etapas empilhadas, sempre abertas — não há mais sanfona. Cada etapa tem o cabeçalho com o número e o nome; a frase curta da etapa não aparece no celular, porque empurraria as etapas para baixo sem dizer nada que o nome não diga.
• O cartão fica deitado: miniatura de uns 118px de largura à esquerda, ocupando toda a altura do cartão e recortada para caber nela (como o cartão de hoje já faz), com a duração no canto de baixo à direita dela; e à direita o título (até duas linhas), a frase (até duas linhas, cortada com reticências) e a etiqueta de público em forma curta — "Garantidora" ou "Imobiliária"; tutorial que serve aos dois lados leva as duas etiquetas na mesma linha, que é onde elas cabem em 225px, e nesse caso a frase fica em uma linha só. A miniatura é a da gravação que a pessoa vai ver, e o recorte segue a proporção dela: a de computador, 16:9 e mais larga que o espaço, é recortada pelos lados, mantendo o centro; a de celular, em pé e mais alta, é recortada pelo alto — o topo da tela gravada, que é onde está o título da tela. O atalho "Ir para " não aparece no cartão do celular: na largura que sobra ele empurraria a etiqueta para uma segunda linha, e o atalho está a um toque, na página do tutorial, com rótulo. O cartão inteiro é alvo de toque e abre o tutorial.

Isto revoga a RN14a da 0045 ("a linha da lista em 375px tem título e duração, e não miniatura"). O cartão deitado resolve o que fez o fix 0014 trocar cartões por linhas: em 375px um cartão em 16:9 comeria quase metade da altura. Deitado, com título e frase cortados em duas linhas cada, ele tem até uns 130px, e as três etapas com seus cartões cabem em pouco mais de uma tela — o índice inteiro à vista rolando, sem gesto escondido e sem toque para abrir assunto.

A página do tutorial, de cima para baixo:

1. "← Central de ajuda", o link do alto do corpo (7.1), sem a parte da etapa. Rola junto com a página.
2. O vídeo. Depende da gravação, porque as duas têm proporções opostas: Aqui a altura útil é a janela menos o topo do app e a barra de abas — uns 686px em
3. Vale a régua de 7.1: preso enquanto ocupar até 45% dela, senão rola e o toque no capítulo traz a página de volta ao vídeo. As duas gravações caem em lados opostos:
4. Gravação de computador (16:9) — presa no topo, com uns 193px de altura em 375px, e a linha "Agora: 2:51 · O pacote locatício" junto dela, presa também.
5. Gravação de celular (em pé, 375×812) — grande, e não presa. O player fica na proporção da gravação, ocupando a altura útil (uns 316px de largura, centralizado): a tela gravada aparece a uns 84% do tamanho real, legível. Presa, cobriria a página inteira. A linha "Agora" vem logo abaixo do player, e rola com ele.

Hoje a gravação em pé é exibida dentro do mesmo quadro 16:9 do computador, com a tela gravada espremida em uns 89px de largura em 375px; é isso que esta distinção desfaz. 3. O título do tutorial, a frase, e numa linha a duração e a etiqueta de público completa. 4. O aviso de versão e a oferta da outra, quando houver (como hoje). 5. "Ir para →", botão principal em largura cheia, com rótulo, e logo abaixo "Copiar link", contornado, também em largura cheia. Abaixo dos dois, o motivo, quando "Ir para" está desabilitado — a mesma posição do desktop, "abaixo dos botões". Abaixo do motivo, quando a cópia falha, o campo com o link (7.3). 6. Os capítulos, sem altura máxima — a lista rola com a página, por baixo do vídeo quando ele está preso, e junto com ele quando não está. Cada linha mostra o tempo e o nome do passo; só o capítulo que está tocando mostra também a frase (em até duas linhas), porque é o único em que a pessoa está lendo. Os anteriores ficam apagados. Alvo de toque de 44px por linha. 7. "Ir para →" de novo, em largura cheia, logo depois do último capítulo — quem percorreu treze capítulos rolando está no fim da página, e o botão do item 5 ficou uma tela e meia acima. Só se repete quando está liberado: desabilitado, o motivo já foi dito no item 5, e repetir um botão que não leva a lugar nenhum — para o ADMIN_GLOBAL, nunca leva — seria a recusa dita duas vezes. No desktop largo não se repete, porque lá o vídeo e os capítulos param presos lado a lado. 8. "Antes deste" e "Próximo passo", empilhados, um cartão por linha.

O que sobra de tela, com a gravação de computador: com o topo do app (64px), o vídeo preso (~220px com a linha "Agora") e a barra de abas do rodapé (62px), restam cerca de 466px de 812 para a lista de capítulos — uns nove a dez capítulos visíveis de cada vez. Com a gravação de celular, o vídeo ocupa a primeira tela e os capítulos começam logo abaixo dela.

PWA: a Central de ajuda e os tutoriais não passam a funcionar offline — o vídeo é do YouTube e depende de rede, como hoje. A página em si, instalada, é servida pelo cache como as demais; o que muda é só o código das duas telas.

7.3 Estados¶

• Carregando: não existe. O catálogo é arquivo do app, não chamada de rede — como hoje. Quem carrega é só o vídeo, dentro do quadro do player.
• Nenhum tutorial publicado: a página mostra "Nenhum tutorial publicado ainda — assim que o primeiro vídeo subir, ele aparece aqui", sem barra de filtro (não há o que filtrar). Igual nos dois viewports.
• Busca ou filtro sem resultado: no lugar das etapas, "Nenhum tutorial com """ quando só há busca, "Nenhum tutorial para a imobiliária parceira" (ou "…para a garantidora") quando só há filtro, e "Nenhum tutorial com "" para a imobiliária parceira" quando os dois estão aplicados e um botão "Limpar filtros", que apaga a busca e o filtro e volta a mostrar tudo. No desktop é o mesmo rótulo que a barra já mostra na segunda linha; no celular a barra não tem essa linha (é decisão do componente), e o botão do estado vazio é a única forma de limpar os dois de uma vez. A barra continua no alto, com o termo digitado, para a pessoa corrigir em vez de recomeçar. Igual nos dois viewports, com o botão em largura cheia no celular.
• Tutorial com assunto que não virou etapa (um assunto ainda não organizado, que o catálogo já marca como provisório — RN5b da 0045): aparece depois das etapas numeradas, com o nome dele e sem número, porque não é passo da jornada. É estado de transição; o make preflight já recusa publicar assim.
• O vídeo não carrega (rede que bloqueia o YouTube): no lugar do player, o aviso de hoje — "O vídeo não carregou. A rede pode estar bloqueando o YouTube." —, com o link direto para o vídeo. A segunda frase muda de palavra, porque os capítulos deixaram de ficar sempre abaixo: "Os capítulos continuam valendo, e o vídeo também abre direto". Eles continuam na tela, como texto, sem virar botão morto (RN13 da 0042); a linha "Agora" some, porque não há o que estar tocando. No celular, o aviso ocupa o lugar do vídeo e não fica preso no topo — preso, ele cobriria a lista sem ter nada a mostrar.
• Capítulo atual enquanto o vídeo não foi tocado: nenhum marcado, e a linha diz "Agora: início". Depois do primeiro play, a marcação acompanha o vídeo — inclusive quando a pessoa arrasta a barra do próprio player.
• Capítulo tocado antes do primeiro play, onde o aparelho não deixa o vídeo começar sozinho (é o caso do iPhone, que só toca depois de um toque no próprio player): o vídeo vai para o tempo do capítulo e fica parado ali, com o botão de play do player à vista; o capítulo fica marcado. A pessoa toca no play e ele começa daquele ponto.
• Sem permissão para a tela do tutorial: "Ir para " aparece desabilitado, com o rótulo inteiro, e o motivo escrito logo abaixo (a glosa do catálogo); para o ADMIN_GLOBAL, "Estas telas são do app da garantidora" (RN10 e RN10a da 0042). No cartão da lista, o atalho simplesmente não aparece (7.1). A Ajuda em si não tem permissão: qualquer autenticado abre, inclusive a garantidora que ainda não concluiu o onboarding (RN13a da 0042).
• Link de tutorial que não existe mais: o topo do app diz "Central de ajuda", como nas outras duas páginas, e o corpo traz o aviso de hoje — "Este tutorial não está mais disponível. Ele pode ter sido substituído por uma versão nova." — com o botão "Ver todos os tutoriais", que leva à lista. Link de assunto que não existe mais (/ajuda/<assunto>): abre a Central de ajuda com o aviso de hoje, "O assunto que você procurava não existe mais". Link de assunto que existe: abre a Central de ajuda inteira, rolada até a etapa daquele assunto — quando há o que rolar, pela mesma régua da volta (7). O endereço continua levando ao que levava.
• "Copiar link" sem acesso à área de transferência (navegador que nega, ou o app instalado, que não tem barra de endereço de onde copiar): abaixo dos botões — e abaixo do motivo, quando ele estiver lá (7.1) — aparece um campo só de leitura com o endereço, já selecionado, e o aviso "Não foi possível copiar automaticamente — o link está selecionado no campo abaixo." A pessoa copia pelo gesto do aparelho (segurar e copiar, ou Ctrl+C). A saída se inspira na da tela de convites, que também recorre a um campo com o link quando a cópia automática falha — aqui o campo só aparece nessa hora.

8. Revisão da experiência¶

Preenchido pelo laço do /spec new, rubrica .claude/rubrics/experiencia.md. Registrar todas as rodadas, inclusive as reprovadas.

Resultado: aprovada na rodada 5 (nota 8), e revalidada na 6 depois de um bloco das duas colunas do desktop ter sido perdido numa edição e reescrito. Os achados das seis rodadas foram corrigidos, inclusive os Important das rodadas aprovadas.

O que travou as quatro primeiras foi sempre a mesma pergunta — quem cede quando o vídeo não cabe na janela —, respondida em pedaços até virar uma régua só: a coluna esquerda inteira cabe na altura útil, e nos modos empilhados o vídeo fica preso até 45% dela, senão rola e o toque num capítulo traz a página de volta.

Pendências aceitas:

• Os dois destinos vizinhos continuam com nome quase igual — "Ir para Análise de Créditos" (configurar as consultas) e "Ir para Análise de Crédito" (abrir a análise) —, porque o botão repete o rótulo do menu. Renomear o item do menu é /tweak à parte, decidido pelo usuário na entrevista.
• O item do menu continua "Ajuda" enquanto a página passa a se chamar "Central de ajuda".

Parte III — Detalhamento¶

Não preencher antes das revisões das seções 6 e 8 estarem aprovadas.

9. Regras de negócio¶

O catálogo e a etapa

• RN1. As etapas da jornada são os assuntos que já existem, reordenados e renomeados em videos/publicacoes.json; não há classificação nova. Os identificadores não mudam, e por isso todo endereço /ajuda/<assunto> e /ajuda/<assunto>/<slug> já compartilhado continua valendo:

A ordem continua sendo a posição da declaração no publicacoes.json, como o montar.mjs já a calcula (RN4 da 0042) — reordenar é mover os blocos no arquivo. - RN1a. O assunto ganha um campo frase: uma linha curta exibida sob o nome da etapa no desktop. Obrigatório para assunto declarado, ausente nos sintéticos. Ele viaja do publicacoes.json para o catálogo do bundle pelo montar.mjs, como titulo e ordem já viajam, porque a tela não lê publicacoes.json (decisão da 0042). - RN1b. Renomear o assunto renomeia a playlist do YouTube, e isso é um passo explícito, não automático: o nome da lista é "<título do assunto> — <sufixo>", e quem aplica a renomeação do que divergiu é node videos/publicar-youtube.mjs playlists. É efeito esperado, não acidente, e não exige republicar vídeo nenhum — entra no plano (14) como passo próprio. - RN2. A ordem das etapas é a ordem, igual para todo mundo. listarAssuntos deixa de promover por papel: isto revoga a RN13 da 0045 (assunto do papel primeiro) e encerra, na Central de ajuda, o efeito da RN8 da 0042 (tutoriais do papel à frente). O que passa a dizer "isto é para você" é a etiqueta de público (RN3) e o filtro (RN5). Os sintéticos continuam por último, sem número (RN5b da 0045). - RN3. A etiqueta de público é derivada do publico do tutorial, sem campo novo: qualquer papel começando por AGENCY_ (hoje AGENCY_USER e AGENCY_MANAGER, o gestor da imobiliária) → "Para a imobiliária parceira"; qualquer papel da garantidora (ADMIN_TENANT, ANALYST, OPERATOR, VIEWER) → "Para a garantidora"; os dois lados no mesmo publico → as duas etiquetas. A régua do lado da imobiliária é o prefixo para o papel novo daquele lado já nascer etiquetado; a da garantidora é a lista, porque ali os papéis não compartilham prefixo. ADMIN_GLOBAL fica fora das duas, de propósito: ele administra a plataforma e não opera tela de garantidora (10.5). As três regras se aplicam nesta ordem: prefixo AGENCY_, depois a lista da garantidora, depois nada — então um perfil personalizado chamado AGENCY_REGIONAL recebe a etiqueta da imobiliária, que é o que o nome dele promete. publico vazio, só com ADMIN_GLOBAL ou só com papel que não casa nenhuma das duas → nenhuma etiqueta, e o tutorial aparece em Todos e em nenhuma das duas opções do filtro — inventar um público a partir de papel que ninguém previu é pior que não dizer. - RN4. O nome da tela de destino é derivado do menu, e a derivação não depende de quem está olhando. Casa-se o destino com o path dos itens do menu pelo prefixo mais longo (/credit-analyses/create → "Análise de Crédito"; /settings/credit-checks → "Análise de Créditos", que é mais longo que /settings). Sem nenhum prefixo casando, o botão diz "Ir para a tela", o rótulo de hoje.

A lista tem de ser a crua, não a recortada por papel. O que nav-groups.tsx exporta hoje é buildNavGroups(badges, visao), que termina em recortar(...) e joga fora o item que aquele usuário não pode ver — e o AGENCY_USER não vê "Imobiliárias", porque o item exige partner_agencies:list e ele tem só read. Derivando dali, ele veria "Ir para a tela" onde o CA21 exige "Ir para Imobiliárias" desabilitado, e o ADMIN_GLOBAL, que nem renderiza esse menu, nunca casaria nada. Então nav-groups.tsx ganha um export da lista crua — os pares path e label de todos os itens, sem recortar —, e é ele que a Ajuda usa. O nome da tela é rótulo de conteúdo, não sinal de acesso: quem decide o acesso é o destinoExige (RN7).

Derivar mantém uma fonte só: o destino já é verificado contra as rotas do App.tsx pelo make preflight (RN11 da 0042).

A lista

• RN5. A busca e o filtro são client-side, sobre o catálogo do bundle. Não vale aqui a regra do docs/ui-patterns.md de filtrar no servidor: ela existe contra o recorte de uma página paginada, e este catálogo é um arquivo do bundle, inteiro em memória, sem paginação e sem API. O escopo da busca: titulo, frase, os nomes dos passos de todas as gravações do tutorial, o título do assunto/etapa e o nome da tela de destino (RN4). A frase da etapa (RN1a) fica de fora de propósito: ela é conectivo de leitura ("o que fazer antes de operar"), e casar por ela devolveria uma etapa inteira para quem digitou "operar" procurando um tutorial. Comparação sem diferenciar maiúscula, minúscula e acento (normalização NFD com remoção de diacríticos), por trecho contido; filtra a cada tecla, sem espera.
• RN5a. O filtro "Para quem" tem três opções — Todos (padrão), Para a garantidora, Para a imobiliária parceira — e compara com as etiquetas da RN3. Abre sempre em Todos, para qualquer papel: a Ajuda continua sem filtrar por quem entrou (RN7 da 0042).
• RN5b. Busca e filtro se somam (E, não OU), e ficam no endereço da lista como ?q= e ?para= — o que permite mandar o link de uma busca. Os valores de ?para= são garantidora e imobiliaria (sem acento, como viewport já faz); a ausência do parâmetro é Todos, e não existe valor para Todos. Valor desconhecido é ignorado em silêncio, como a 0045 faz com ?v= (RN17a).
• RN5c. O estado da lista viaja no endereço do tutorial e volta por ele. Abrir um cartão leva ?q= e ?para= junto (somando-se ao ?v=, quando houver), e o link "← Central de ajuda" monta a volta com o que recebeu. É o que faz a volta funcionar tanto pelo botão do navegador quanto pelo link, e sem depender do histórico — quem chega ao tutorial por link compartilhado simplesmente não traz nenhum dos dois, e a lista abre sem filtro (7.1). A reescrita de endereço que já existe — quando o segmento do assunto no caminho não é o do tutorial (RN17b da 0045) — passa a preservar q e para junto do v; hoje ela preserva só o v, e descartá-los ali perderia a volta de quem chegou por um link antigo. O "Copiar link" (RN12) não copia q nem para: eles são estado de quem procurava, não do tutorial, e quem recebe o link não deve abrir a Ajuda filtrada por uma busca que não fez.
• RN6. Etapa sem nenhum tutorial que case some, e as que ficam mantêm o número — o número é a posição na jornada, não a posição na tela. Nenhum tutorial casando, a lista some inteira e entra o estado vazio de busca (7.3), com "Limpar filtros".
• RN7. O atalho "Ir para " no cartão só aparece quando a pessoa pode usar a tela — mesma avaliação da RN9/RN10a da 0042, e no celular ele não aparece nunca (7.2). A ação desabilitada com a glosa continua existindo onde a 0042 a colocou: na página do tutorial (RN10 da 0042), que é onde o motivo cabe escrito.

A página do tutorial

• RN8. O capítulo é o passo do roteiro (agruparEmPassos), não a fala — a granularidade que a 0042 já escolheu para navegar (RN2a). O texto de apoio de cada capítulo é a primeira fala dele.
• RN9. A tela acompanha o vídeo sem carregar a IFrame API. O iframe já sobe com enablejsapi=1; a página manda {"event":"listening"} ao contentWindow e passa a receber os infoDelivery do player, de onde lê currentTime e o estado. Daí saem o capítulo marcado (o último cujo t já passou) e os anteriores em tom apagado. Continua valendo a RN13 da 0042: sem player, o roteiro continua legível — sem mensagem nenhuma, a lista fica sem marcação e a linha "Agora" some, e nada quebra.
• RN9a. Clicar num capítulo manda seekTo e, em seguida, playVideo. Onde o aparelho recusa tocar sem gesto no próprio player (iOS), o vídeo fica parado no tempo pedido, com o capítulo marcado — não se insiste nem se avisa: a pessoa toca no play.
• RN9b. Só se aceita mensagem vinda do player. O message é filtrado pela origem (https://www.youtube-nocookie.com) antes de virar tempo corrente; mensagem de qualquer outra origem é descartada em silêncio. Sem isto, qualquer frame da página poderia mover a marcação dos capítulos.
• RN10. O vídeo respeita a proporção da gravação. A de computador é 16:9; a de celular é em pé (375×812 na gravação, e a miniatura em public/ tem 374×812) e deixa de ser exibida dentro de um quadro 16:9. As medidas e os tetos são os de 7.1 e 7.2: no desktop, a coluna esquerda inteira cabe na altura útil; nos modos empilhados, o vídeo fica preso enquanto ocupar até 45% da altura útil, e, passando disso, rola com a página e o clique num capítulo traz a página de volta ao vídeo antes de saltar.
• RN11. A sequência "Antes deste / Próximo passo" é a jornada inteira, na ordem etapa (RN1) → posição dentro da etapa, ignorando busca e filtro. A ordem dentro da etapa é a que a lista já usa: a do catálogo, alfabética por nome de arquivo, como o import.meta.glob entrega (RN14 da 0045). Sem anterior, o lugar da esquerda fica vazio; sem próximo, o da direita vira "Voltar para a Central de ajuda".
• RN12. "Copiar link" copia o endereço do tutorial com o ?v= se ele estiver lá (RN17a da 0045), e sem o ?q=/?para= da lista (RN5c). Falhando navigator.clipboard — contexto negado, app instalado sem barra de endereço —, a tela mostra um campo somente-leitura com o endereço já selecionado e o aviso correspondente (7.3), como a tela de convites faz.
• RN13. A barra de assuntos sai, e com ela o NavegadorDeAssuntos — nas duas páginas e nos três tamanhos. O que ela resolvia (ver o próximo vídeo sem voltar à lista, 7.1 da 0045) passa a ser feito pelos cartões da RN11. Isto revoga também a RN14a da 0045 (a linha sem miniatura em 375px), substituída pelo cartão deitado de 7.2.

Verificação

• RN14. O make preflight passa a exigir frase no bloco assunto do catálogo, em ramo próprio, não dentro de CHAVES_ASSUNTO: aquele dicionário é percorrido para todo bloco assunto, inclusive o sintético, e pôr frase ali reprovaria justamente o caso em que ela não existe (RN1a). A exigência é: sintetico: false → frase presente e string não vazia; sintetico: true → frase ausente. Mensagem nomeando o arquivo, como as demais.
• RN14b. A verificação que compara o bloco assunto do catálogo com o videos/publicacoes.json (hoje titulo e ordem) passa a comparar frase também. Sem isso, mudar a frase no publicacoes.json e esquecer de regerar os catálogos passa despercebido — que é exatamente o que aquela verificação existe para pegar.
• RN15. O montar.mjs ganha um caminho barato que reescreve só o bloco assunto dos catálogos — --so-assuntos —, relendo videos/publicacoes.json e aplicando id, titulo, frase, ordem e sintetico a todos os apps/web/src/tutoriais/*.json, sem tocar em mais nada. O vínculo tutorial → assunto vem do assunto.id que já está no catálogo, não do roteiro em videos/<slug>.json: o que se está atualizando é o rótulo de um assunto que aquele tutorial já declara, e ler o roteiro traria de volta a dependência de docs/videos/ que este caminho existe para evitar. Catálogo com assunto sintético é deixado como está — quem o conserta é declarar o assunto e remontar. Existe porque os dois caminhos de hoje não servem: --so-catalogo grava só o youtubeId, e a montagem completa lê docs/videos/<slug>/<viewport>/, pasta ignorada pelo git que só existe para quem acabou de gravar. Sem ele, mudar o nome ou a ordem de um assunto exigiria regravar os vídeos ou editar três JSON à mão — e a segunda opção reapareceria na próxima vez.

10. Autorização e isolamento¶

Esta spec não cria endpoint, não lê dado de tenant e não muda o que ninguém pode fazer. Muda três coisas no que se vê, e as três estão registradas abaixo: a ordem das etapas deixa de depender do papel (RN2, em 10.3), todo cartão passa a exibir a etiqueta de público derivada do publico que já está no bundle (RN3, em 10.3), e o rótulo da tela de destino passa a ser o nome do menu mesmo para quem não tem aquele item (RN4, em 10.4 e 10.5). O catálogo de tutoriais é arquivo do bundle — import.meta.glob sobre apps/web/src/tutoriais/*.json —, então não há chamada de API, filtro por tenant_id nem FK vinda de corpo a resolver. O que existe de superfície de acesso continua sendo a que a 0042 desenhou, e esta spec a mantém inteira: a Ajuda não tem permissão, e o botão para a tela que o tutorial ensina avalia o que a pessoa pode fazer.

10.1 Matriz de papéis¶

Os três tutoriais de hoje exigem, para usar a tela que ensinam (destinoExige): ativar-consultas-de-credito → papel ADMIN_TENANT; cadastro-de-imobiliaria → permissão partner_agencies:create; analise-credito-imobiliaria → permissão credit_analyses:create. A tabela abaixo é o cruzamento disso com o rbac_seed.py, e é ela que os CAs negativos exercitam.

O negativo desta tabela é o mesmo de hoje — esta spec não muda destinoExige nem porteiro de rota. O que muda é onde a recusa aparece: o botão desabilitado com a glosa continua na página do tutorial, e o atalho do cartão simplesmente não é renderizado (RN7).

10.2 Permissões¶

Nenhuma permissão nova, e nenhuma alteração no rbac_seed.py. A Ajuda continua sem resource:action própria — criar uma seria proteger conteúdo que não é dado de ninguém (10.2 da 0042). O destinoExige de cada tutorial continua comparado contra roles ou permissions do /auth/me, sem mudança.

10.3 Isolamento por garantidora (tenant)¶

Sem impacto. Nada nesta spec lê, grava ou lista entidade de negócio; o catálogo é igual para todas as garantidoras, porque é parte do produto. A única informação do usuário que a tela usa continua sendo roles e permissions do /auth/me, e agora para um fim só: decidir se "Ir para " está liberado. A ordenação por papel, que era o outro uso, deixa de existir (RN2).

10.4 Isolamento por imobiliária¶

Uma mudança, e ela é de rótulo, não de dado. Pela RN4, o nome da tela de destino passa a ser derivado da lista crua do menu, e não do menu recortado por papel — então o AGENCY_USER e o AGENCY_MANAGER passam a ler "Ir para Imobiliárias" (desabilitado, com a glosa) onde hoje leriam "Ir para a tela". É decisão consciente, e o que ela expõe é o nome de uma tela que o tutorial inteiro já ensina — o título do vídeo é "Cadastrar uma imobiliária parceira", e o vídeo mostra a tela funcionando. Nenhum dado de negócio, de garantidora ou de imobiliária atravessa por aí. A alternativa — o rótulo mudar conforme quem olha — faria a mesma tela ter dois nomes na boca do produto, que é pior para quem está aprendendo.

No mais, sem impacto: o AGENCY_USER continua vendo todos os tutoriais, inclusive os de gestão da garantidora (RN7 da 0042). Não há dado de negócio neles — são gravações em ambiente de demonstração, com dados fictícios, declarados como públicos no publicacoes.json e publicados no YouTube. O que ele não pode fazer continua barrado pelo destinoExige e pelo porteiro da rota, que esta spec não toca.

10.5 Plataforma × cliente (SaaS admin)¶

Nenhuma tela de /app/admin/* muda, e o ADMIN_GLOBAL abre a Central de ajuda como qualquer autenticado, continuando sem poder saltar para as telas do app da garantidora (RN10a da 0042) — a regra que existe justamente porque ele não tem tenant.

Duas consequências da RN4 ficam registradas aqui, porque a fronteira plataforma × cliente é onde elas moram:

• o ADMIN_GLOBAL passa a ler, dentro da Ajuda, os nomes das telas do app da garantidora ("Análise de Créditos", "Imobiliárias", "Análise de Crédito"), sempre em botão desabilitado. São os nomes das telas que os tutoriais ensinam, públicos no YouTube; não há dado de cliente neles;
• o export cru é só o do menu da garantidora (buildNavGroups). O menu do SaaS admin (buildAdminNavGroups) fica de fora, e nenhum destino de tutorial pode apontar para /admin/* — o make preflight já exige que todo destino seja rota declarada no App.tsx (RN11 da 0042), e um tutorial de tela de plataforma seria outra feature, com outra decisão de público.

11. Impacto por app¶

apps/api¶

Sem impacto. Nenhum endpoint, schema, model ou migration. O catálogo não passa pela API, e o /auth/me já devolve roles e permissions.

apps/web¶

• src/pages/ajuda/index.tsx — reescrita: deixa de ser navegador por assunto e passa a ser a página única em etapas (7.1 e 7.2), com FilterBar/MobileFilterBar, busca, filtro "Para quem", estado de ?q=/?para=, rolagem até a etapa e os estados de 7.3.
• src/pages/ajuda/TutorialPage.tsx — reescrita: duas colunas com o vídeo preso e o painel de capítulos, link de volta no corpo, cabeçalho com as duas ações, marcação do capítulo por infoDelivery (RN9), cartões Antes/Próximo, proporção da gravação (RN10) e a régua de preso/rola dos modos empilhados.
• src/pages/ajuda/NavegadorDeAssuntos.tsx — removido (RN13).
• src/components/tutorial-card/index.tsx — ganha a etiqueta de público, o atalho "Ir para " (só quando liberado) e a forma deitada do celular, com a miniatura recortada conforme a proporção da gravação.
• src/components/tutorial-roteiro/index.tsx — vira o painel de capítulos: altura máxima e rolagem própria no desktop, capítulo atual marcado e trazido à vista dentro da lista, linhas com tempo, nome e a primeira fala. No celular, sem altura máxima e só o capítulo atual mostrando a fala.
• src/components/tutorial-antes-depois/ (novo) — os cartões "Antes deste" e "Próximo passo".
• src/tutoriais/index.ts — listarAssuntos perde a promoção por papel (RN2) e ganha a sequência linear da jornada (RN11); entram as funções de busca (RN5), de etiqueta (RN3) e de nome da tela (RN4).
• src/tutoriais/tipos.ts — AssuntoDoCatalogo ganha frase.
• src/tutoriais/*.json — regerados pelo montar.mjs com o assunto novo (título, frase, ordem).
• data-testid novos (na convenção do apps/web/CLAUDE.md — <recurso>-search-input, <recurso>-<filtro>-filter): ajuda-search-input, ajuda-publico-filter, ajuda-filter-bar, ajuda-etapa-<id> (o bloco da etapa), ajuda-vazio-busca, ajuda-limpar-filtros, ajuda-card-<slug>-atalho, ajuda-card-<slug>-publico, tutorial-voltar-lista, tutorial-ir-para-tela-fim, tutorial-anterior-vazio, tutorial-capitulos, tutorial-capitulo-<n>, tutorial-agora, tutorial-copiar-link, tutorial-link-fallback, tutorial-anterior, tutorial-proximo. Permanecem ajuda-card-<slug>, tutorial-player, tutorial-ir-para-tela, tutorial-ir-para-tela-glosa, tutorial-aviso-versao, tutorial-trocar-versao, tutorial-player-erro, tutorial-link-youtube. Saem com o navegador: ajuda-barra-assuntos, ajuda-lista-assuntos, ajuda-submenu-assuntos, ajuda-assunto-<id>, ajuda-assunto-bloco-<id>, ajuda-assunto-item-<slug>, ajuda-linha-<slug>.
• Sider e rotas: sem mudança. A Ajuda já está no menu (nav-groups.tsx:70) e as rotas /ajuda, /ajuda/:segmento e /ajuda/:assunto/:slug continuam as mesmas (App.tsx:357-365), inclusive o redirecionamento do link legado.
• Testes unitários (*.test.tsx, ao lado do arquivo, spec 0047): busca e filtro somados e normalização de acento; a ordem fixa das etapas com papéis diferentes; a derivação da etiqueta (incluindo publico vazio) e do nome da tela (incluindo o fallback); a sequência Antes/Próximo nas pontas; o atalho do cartão que só aparece liberado; a marcação do capítulo a partir do tempo corrente.
• Responsividade e PWA: as duas páginas entregam desktop e celular no mesmo passo (7.1 e 7.2). O PWA não ganha nada offline — o vídeo é do YouTube —; só o bundle muda, e a tela instalada precisa ser reaberta para furar o cache do service worker.

apps/e2e¶

• tests/e2e/ajuda.spec.ts — reescrito. Os cenários que afirmavam a barra de assuntos (abrir/fechar assunto, a faixa de pílulas, a lista do celular) deixam de existir com ela; ficam e se somam: os três tutoriais visíveis sem clique em 1280×800; a busca por "documentos" e por "corretor"; o filtro "Para a imobiliária parceira"; o estado vazio com "Limpar filtros"; a volta do tutorial preservando busca e filtro; o clique num capítulo mudando o tempo do player com o vídeo à vista; os cartões Antes/Próximo nas pontas; "Copiar link"; e os negativos de autorização — AGENCY_USER com o botão desabilitado num tutorial de gestão, ADMIN_GLOBAL com a glosa da plataforma, e o cartão sem atalho nos dois casos. Continuam os endereços: link legado, assunto errado no caminho, ?v= desconhecido, slug inexistente.
• A faixa de 600 a 1199px continua tendo cenário próprio. O describe Ajuda — largura intermediária de hoje existe por causa do fix 0014 (a sanfona do celular não pode vazar para o tablet) e não some com a barra: ele é reescrito para afirmar o que vale ali agora — as etapas empilhadas com cartões em grade, a barra de filtro no formato de desktop, e a página do tutorial empilhada com o vídeo no topo.
• Seeds: nenhum. O catálogo vem do bundle e os usuários de fixture já existem.

Fora dos três apps¶

• videos/publicacoes.json — assuntos reordenados, retitulados e com frase.
• .claude/skills/tutoriais/scripts/montar.mjs — copia frase para o catálogo (assuntoDoCatalogo).
• scripts/preflight.py — duas mudanças independentes: um ramo próprio que exige frase no assunto declarado e a proíbe no sintético (RN14, fora de CHAVES_ASSUNTO, que é percorrido para todo bloco assunto); e a verificação que compara catálogo × publicacoes.json passando a comparar frase também — o que inclui _assuntos_declarados, que hoje devolve só titulo e ordem (RN14b).
• videos/publicar-youtube.mjs — sem mudança de código, mas é por ele que o título novo do assunto vira o nome da playlist na próxima publicação (RN1b).
• apps/api/app/db/rbac_seed.py — sem mudança: nenhuma permissão nova (10.2).

12. Contrato de API¶

Sem impacto: nenhum endpoint novo, alterado ou removido, e nenhuma migration. O catálogo de tutoriais é arquivo do bundle desde a 0042, e nada nesta spec o move para a API. O único contrato consumido continua sendo o /auth/me, já existente, de onde saem roles e permissions para decidir o botão "Ir para ".

13. Critérios de aceite¶

• [x] CA1. (RN1, RN2) Em 1280×800, com o ADMIN_TENANT logado, /ajuda mostra as três etapas na ordem 1 Configurar a garantidora, 2 Trazer imobiliárias parceiras, 3 Operar análises de crédito, cada uma com os cartões dela visíveis — sem clique e sem rolagem.
• [x] CA2. (RN2) O mesmo endereço, com o AGENCY_USER logado, mostra as etapas na mesma ordem — nada é promovido por papel.
• [x] CA3. (RN1) Abrir /ajuda/gestao-imobiliarias (endereço antigo) continua funcionando e leva à Central de ajuda rolada até a etapa 2; /ajuda/<slug> legado continua redirecionando para /ajuda/<assunto>/<slug>.
• [x] CA4. (RN1a) No desktop, cada cabeçalho de etapa mostra a frase curta declarada no publicacoes.json ("o que fazer antes de operar" na etapa 1); em 375px a frase não aparece.
• [x] CA5. (RN3) O cartão de "Abrir uma análise de crédito" mostra "Para a imobiliária parceira"; os outros dois mostram "Para a garantidora".
• [x] CA6. (RN5) Digitar "documentos" deixa na tela só "Abrir uma análise de crédito" (casou pelos passos), e a etapa exibida continua numerada 3. Digitar "analise", sem acento, casa o mesmo que "análise".
• [x] CA7. (RN5, RN4) Digitar "imobiliárias", no plural, acha "Cadastrar uma imobiliária parceira" — pelo nome da tela de destino e pelo nome da etapa.
• [x] CA8. (RN5a, RN5b) Filtrar "Para a garantidora" deixa dois cartões; somando a busca "consulta", fica um. A URL passa a trazer ?q= e ?para=, e recarregar a página reproduz o mesmo resultado.
• [x] CA9. (RN6) Buscar "xyz" mostra "Nenhum tutorial com "xyz"" e o botão "Limpar filtros", que devolve os três cartões e limpa ?q=/?para=.
• [x] CA10. (RN5a) Entrando como AGENCY_USER, o filtro abre em Todos e os três tutoriais estão visíveis.
• [x] CA11. (RN5b, RN5c) Abrir um tutorial a partir de uma lista filtrada e voltar por "← Central de ajuda" devolve a lista com a busca e o filtro aplicados.
• [x] CA12. (RN8, RN9a) Na página de "Abrir uma análise de crédito" em 1280×800, clicar no capítulo "O pacote locatício" faz o player ir para 2:51 com o player visível na tela no momento do clique e depois dele.
• [x] CA13. (RN9) Com o vídeo tocando, o capítulo correspondente ao tempo corrente aparece marcado e os anteriores em tom apagado, sem clique nenhum.
• [x] CA14. (RN11) Em "Ativar as consultas de crédito pela API Full" (primeiro da jornada) não há cartão "Antes deste", e "Próximo passo" leva a "Cadastrar uma imobiliária parceira". Em "Abrir uma análise de crédito" (último), "Próximo passo" é "Voltar para a Central de ajuda".
• [x] CA15. (RN11) Com a lista filtrada em "Para a garantidora", abrir "Cadastrar uma imobiliária parceira" e ver que "Próximo passo" continua sendo "Abrir uma análise de crédito" — a sequência ignora o filtro.
• [x] CA16. (RN12, RN5c) Numa lista filtrada, abrir um tutorial e usar "Copiar link": o endereço copiado é o do tutorial, sem q nem para (com o ?v=, se houver), e a tela mostra "Link copiado.".
• [x] CA17. (RN12) Com a área de transferência negada, a tela mostra o campo somente-leitura com o endereço já selecionado e o aviso de que a cópia automática falhou.
• [x] CA18. (RN10, 7.2) Em 375×812, a página do tutorial de "Cadastrar uma imobiliária parceira" toca a gravação de celular, em pé, ocupando a altura útil, e a lista de capítulos rola por baixo dela; tocar num capítulo traz o vídeo de volta à vista e pula para o trecho.
• [x] CA19. (RN10, 7.2) Em 375×812, no tutorial de "Abrir uma análise de crédito" (só gravação de computador), o vídeo fica preso no topo ao rolar, e tocar num capítulo não o tira da vista.
• [x] CA20. (7.2) Em 375×812, a Central de ajuda mostra as três etapas com cartões deitados, sem sanfona, e sem rolagem horizontal (scrollWidth === clientWidth).
• [x] CA21. (em 1280×800; RN7 — negativo, AGENCY_USER) Logado como AGENCY_USER: o cartão de "Cadastrar uma imobiliária parceira" não mostra atalho, e a página desse tutorial mostra "Ir para Imobiliárias" desabilitado, com a glosa do catálogo escrita abaixo dos botões. Em 375×812, nenhum cartão mostra atalho, para qualquer papel (RN7).
• [x] CA22. (em 1280×800; RN7 — negativo, ADMIN_GLOBAL) Logado como ADMIN_GLOBAL: nenhum cartão mostra atalho, e em qualquer tutorial "Ir para " vem desabilitado com "Estas telas são do app da garantidora".
• [x] CA23. (em 1280×800; RN7 — positivo) Logado como ADMIN_TENANT: o cartão de "Ativar as consultas de crédito pela API Full" mostra "Ir para Análise de Créditos →" e o atalho leva a /settings/credit-checks.
• [x] CA24. (RN9, RN13 da 0042) Bloqueando o domínio do YouTube, a página do tutorial mostra o aviso com o link direto, os capítulos continuam na tela como texto e a linha "Agora" não aparece.
• [ ] CA25. (RN1b) Depois de renomear os assuntos, node videos/publicar-youtube.mjs playlists renomeia as listas existentes para " — " e imprime "playlist renomeada", sem republicar vídeo nenhum.
• [x] CA26. (RN14) make preflight reprova um catálogo cujo assunto declarado esteja sem frase, nomeando o arquivo.
• [x] CA27. (RN9b) Uma mensagem postMessage de outra origem, com um infoDelivery forjado, não move a marcação dos capítulos nem a linha "Agora".
• [x] CA28. (RN14b) Mudar a frase de um assunto no publicacoes.json sem regerar os catálogos faz o make preflight reprovar, nomeando o arquivo divergente.
• [x] CA29. (RN15) node .claude/skills/tutoriais/scripts/montar.mjs --so-assuntos atualiza o bloco assunto dos três catálogos a partir do publicacoes.json — título, frase e ordem — sem alterar nenhuma outra chave dos arquivos.
• [x] CA30. (RN13) Nenhuma tela da Ajuda renderiza a barra de assuntos: os data-testid ajuda-barra-assuntos, ajuda-lista-assuntos e ajuda-submenu-assuntos não existem em nenhum dos dois viewports.

14. Plano de implementação¶

Não há fase de apps/api: o contrato não muda (12).

• [x] videos/publicacoes.json — reordenar, retitular e acrescentar frase aos três assuntos
• [x] .claude/skills/tutoriais/scripts/montar.mjs — copiar frase para o catálogo
• [x] .claude/skills/tutoriais/scripts/montar.mjs — caminho --so-assuntos (RN15)
• [x] scripts/preflight.py — ramo próprio exigindo frase no assunto declarado e proibindo-a no sintético (RN14)
• [x] scripts/preflight.py — frase na comparação catálogo × publicacoes.json, incluindo _assuntos_declarados (RN14b)
• [x] apps/web — nav-groups.tsx: export da lista crua de path/label (RN4)
• [x] regerar o bloco assunto dos três apps/web/src/tutoriais/*.json com --so-assuntos
• [x] apps/web — tipos.ts e index.ts: frase, ordem fixa, busca, etiqueta, nome da tela, sequência da jornada — com os testes unitários antes do código (spec 0047)
• [x] apps/web — pages/ajuda/index.tsx: etapas, FilterBar/MobileFilterBar, ?q= e ?para=, estados, cartão deitado no celular
• [x] apps/web — components/tutorial-card: etiqueta, atalho, forma deitada
• [x] apps/web — pages/ajuda/TutorialPage.tsx e tutorial-roteiro: duas colunas, vídeo preso, capítulos, infoDelivery, copiar link, Antes/Próximo
• [x] apps/web — remover NavegadorDeAssuntos.tsx
• [x] make preflight e make test-web
• [x] apps/e2e — reescrever tests/e2e/ajuda.spec.ts (13)
• [ ] node videos/publicar-youtube.mjs playlists — renomear as listas do YouTube (RN1b)
• [ ] /devremote-rebuild e rodar só ajuda.spec.ts
• [ ] validado no browser em 1280×800 e 375×812, e na tela instalada (PWA) para furar o cache

15. Decisões em aberto¶

Nenhuma. As duas que apareceram na revisão foram decididas pelo usuário na entrevista e estão registradas como pendências aceitas na seção 8: o botão repete o rótulo do menu (mesmo com "Análise de Créditos" e "Análise de Crédito" vizinhos), e o item do menu continua se chamando "Ajuda" enquanto a página se chama "Central de ajuda".

16. Revisão do detalhamento¶

Preenchido pelo laço do /spec new, rubrica .claude/rubrics/detalhamento.md. Registrar todas as rodadas, inclusive as reprovadas.

Resultado: aprovada na rodada 3 (nota 8). O Important e os Minor da rodada 3 foram corrigidos depois da aprovação: o passo do preflight no plano contradizia a própria RN14 (o ramo próprio, fora de CHAVES_ASSUNTO) e não tinha item para a RN14b; a abertura da seção 10 contava uma mudança visível onde há três; a ordem das regras da etiqueta ficou escrita; "Copiar link" e o recurso da cópia ganharam critério; os negativos do atalho ganharam o viewport; a faixa de 600 a 1199px continua com cenário e2e próprio; e os critérios foram renumerados em sequência.

As duas primeiras rodadas travaram na mesma classe de defeito: regra derivada de estrutura do código sem olhar como o código a entrega — o rótulo do menu vinha da lista recortada por papel, a exigência do preflight ia num dicionário percorrido também pelo assunto sintético, e a matriz de papéis contradizia o rbac_seed.py em duas linhas.

Riscos aceitos: risco de acesso que a revisão apontou e se decidiu não fechar nesta spec, com quem decidiu e por quê. Vazio se não houver — e o esperado é que esteja vazio.

17. Revisão da implementação¶

Preenchido pelo /spec implement, rubrica .claude/rubrics/implementacao.md. As revisões de fase (api, web, e2e) vão nas primeiras linhas; a da branch inteira, na última.

Resultado: aprovada na rodada 2 (a da branch inteira), nota 8, sem Critical.

Os três Important dela foram corrigidos, não aceitos, porque os três eram da mesma família — comentário afirmando uma regra que a linha abaixo não executava: o corte de duas colunas pela janela em vez da área medida, o teto de altura da coluna esquerda que não existia (com o cabeçalho dentro dela, comendo do mesmo orçamento), e o aperto de mão do listening decidido no relógio em vez do onLoad do player. Os Minor também entraram, inclusive os dois que a revisão apontou como critério sem teste — o atalho ausente em 375px e o recurso da cópia quando o navegador recusa viraram casos de e2e.

Defeitos aceitos: nenhum. O que ficou pendente não é defeito: node videos/publicar-youtube.mjs playlists (RN1b / CA25) renomeia as listas do YouTube e é passo de publicação, com credencial do canal — ele roda quando o time quiser, e não bloqueia o merge.

18. Registro¶

Não houve fase de API, e isso estava previsto¶

O contrato não mudou (12): o catálogo é arquivo do bundle e o único endpoint consumido continua sendo o /auth/me. A ordem do monorepo (api → web → e2e) valeu com a primeira etapa vazia, e a fase que abriu foi a do ferramental — publicacoes.json, montar.mjs, preflight —, porque é ela que produz o catálogo que o apps/web lê.

A régua do vídeo nasceu errada, e foi a revisão de fase que pegou¶

A primeira implementação decidia preso × rola pela proporção da gravação (videoPreso = !emPe), e não pela altura ocupada. Nas duas janelas que a RN10 enumera — 1100×800 e 932×430 — o vídeo de computador passa dos 45% da altura útil e, preso, cobria a tela inteira com os capítulos inalcançáveis. Pior: o comentário acima da linha afirmava a regra que o código não executava.

Consertado medindo de verdade (ResizeObserver no player + a altura da janela), e o e2e ganhou o caso que faltava — "janela estreita e alta: o vídeo rola com a página, e o capítulo tocado o traz de volta". Sem esse caso, a régua voltaria a ser inferida na primeira refatoração.

O cartão deitado crescia com a miniatura em pé — e só o print pegou¶

A gravação de celular é 374×812. No cartão deitado, a imagem com height: 100% dentro de uma caixa de altura indefinida não era recortada: ela esticava o cartão para quase 400px, refazendo o cartão alto que o fix 0014 tirou de 375px.

O e2e não pegou porque o que ele afirma é width > height — verdadeiro nos dois casos. A conferência visual nos dois viewports, que o Passo 5 do /spec implement manda fazer, pegou na primeira olhada. Conserto: a imagem é absoluta dentro do slot, e a altura do cartão volta a vir do texto.

O conteúdo se espalhava em tela larga¶

Numa janela de 2560px a coluna esquerda esticava por 1500px: o cabeçalho e os cartões de jornada atravessavam a tela enquanto o vídeo, limitado pelo teto de altura, ficava com 880 no canto — os botões acabavam longe do que comandam, e os cartões viravam duas faixas quase vazias. A coluna passou a ter a largura do vídeo, e o que sobra é margem à direita.

Na mesma passada o teto de largura subiu de 880 para 1100. Os 880 vinham da 0042, onde o vídeo ocupava a coluna sozinho; aqui ele divide a linha com os capítulos e a régua de altura já o limita antes disso na maioria das janelas — o teto maior só age em tela alta e larga, que era justamente onde sobrava branco.

Os cartões saíam de alturas diferentes, e quem viu foi o usuário¶

Cada etapa é uma coluna própria, então nada alinha os cartões entre colunas: o título de "Ativar as consultas de crédito pela API Full" quebra em duas linhas, o dos outros dois não, e a primeira coluna terminava mais alta. Nem o e2e nem os prints que eu olhei pegaram — eu tinha olhado a lista inteira e não a linha de base dos três cartões.

Conserto em duas camadas, e a segunda só apareceu porque a asserção nova reprovou: título e frase reservam duas linhas cada; e o rodapé virou duas linhas determinadas — etiqueta em cima, atalho embaixo —, porque "Para a imobiliária parceira" ao lado de "Ir para Análise de Crédito →" não cabe na largura de uma coluna e a quebra somava 22px naquele cartão. A segunda linha fica reservada mesmo sem atalho, senão quem não pode usar a tela veria um cartão mais curto que o do lado.

O e2e ganhou a asserção que faltava (a diferença entre a maior e a menor altura não passa de 1px), e foi ela que pegou a segunda camada — a primeira rodada dela ainda acusou 311, 311, 333.

O ferramental ganhou um caminho que não existia (RN15)¶

Renomear ou reordenar um assunto não tinha como chegar aos catálogos: --so-catalogo só grava youtubeId, e a montagem completa lê docs/videos/<slug>/<viewport>/, pasta fora do git que só existe para quem acabou de gravar. A alternativa era editar três JSON à mão — e o problema voltaria na próxima vez. O --so-assuntos foi decisão do usuário na revisão do detalhamento.

A suíte do web falhou quatro casos numa rodada, e não era regressão¶

Numa execução concorrente com o preflight e um subagente, quatro casos de billings, credit-analyses e my-garantidora estouraram os 15s — todos por timeout, nenhum por asserção, em arquivos que esta branch não toca e que não importam nada do que ela mudou. Rodados isolados, e depois a suíte inteira com a máquina livre: 371 verdes em 51 arquivos. O que os derrubou foi contenção de máquina, não a branch.

O dev-remote está servindo esta branch¶

Para rodar o e2e contra o que vai ao ar, a branch foi empurrada e o checkout de /opt/garantora trocado de main para spec/0053-central-ajuda-jornada, com rebuild do web (pedido do usuário). Ao mesclar, o dev-remote precisa voltar para main.

O apps/e2e/.env desta máquina apontava para https://oto.tail10981f.ts.net/app — o endereço do tailnet que saiu em 2026-09-17 — e foi corrigido para https://dev.garantora.com.br/app. O arquivo não é versionado; a correção vale só aqui.

Afirmações conferidas¶

Fatos sobre o repositório que uma rodada de portão já conferiu abrindo o arquivo. O recortar.py leva esta seção junto em qualquer parte, e o revisor da rodada seguinte pode tomá-los como dados em vez de reconferir tudo do zero.

Duas regras, e a segunda é a que faz a primeira valer:

1. Só entra o que um revisor conferiu — não o que você conferiu ao escrever. O ponto é aproveitar trabalho já pago por uma rodada, não abrir atalho para afirmar sem prova.
2. Mexeu na frase da spec, a linha sai da tabela. A afirmação volta a ser conferível. Sem isso a tabela vira o oposto do portão: uma afirmação carimbada como verdadeira porque um dia foi.

Feature sem afirmação sobre o repositório não precisa da seção — apague-a.