Boas-vindas, tour, Academy e adoção

Objetivo

Fazer qualquer pessoa entender a Radhr AI em menos de dez minutos e saber o que fazer em seguida, sem depender de treinamento presencial — e medir isso. Quatro peças, todas atrás da flag welcome_experience (ADR-0013):

Welcome Experience (/radar/boas-vindas): a tela do primeiro acesso, antes do sistema. Sete passos: bem-vindo, função, objetivo, como a Radhr AI funciona (fluxo interativo), conheça sua IA, seu primeiro resultado (vitórias rápidas com dado real ou demonstração) e pronto (checklist, Adoption Score, caminho). O Radhr Assistant fica ao lado o tempo todo e responde pela documentação viva, com fonte.
Tour contextual: na primeira visita a cada tela (Home, Leads, Lead, Clientes, Cliente, Contrato, Escopo, Proposta, Copiloto, Conhecimento, Catálogo, Organização, Métricas, Relatório, Academy), dois a cinco passos curtos sobre os elementos daquela tela. Uma vez só, por pessoa.
Academy (/radar/academy): trilhas de certificação (Iniciante, Intermediário, Avançado, Especialista Radar), tutoriais, FAQs, vídeos, guias da organização e busca inteligente — tudo tirado da Living Documentation.
Product Adoption Engine: marcos de adoção lidos das trilhas que a Radhr AI já guarda, Adoption Score (0–100) com pesos por função, checklist de ativação e o painel /radar/organizacao/adocao para o admin.

Fluxo

Primeiro acesso. Ao abrir a Home com a flag ligada, a Radhr AI cria o estado de adoção da pessoa (usuario_adocao, uma linha por usuário e organização) e, se as boas-vindas não foram concluídas nem puladas, redireciona para /radar/boas-vindas. "Pular por agora" devolve à Home e deixa a experiência disponível na Academy.
Passos 1 e 2. Função (CEO/Founder, Diretor Comercial, Gestor Comercial, Vendedor, SDR, Operações, Financeiro, Marketing, Administrador) e objetivo (aumentar vendas, organizar processos, automatizar, melhorar conversão, melhorar a operação, escalar). A função personaliza os passos seguintes: o foco no fluxo, os agentes "para você", as cinco vitórias rápidas, os KPIs, o Success Path e os pesos do score. O objetivo escolhe a primeira lição da Academy.
Passo 3. O fluxo do Revenue OS em sete nós (Lead → Diagnóstico IA → Proposta → Contrato → Cliente → Escopo → Projeto e expansão); cada nó abre o que acontece, o agente envolvido, a tela e um exemplo.
Passo 4. Os agentes em linguagem simples (Lead Analyzer, Proposal Strategist, Contract Builder, Risk Analyzer, Scope Builder, Delivery Advisor, Expansion, Customer Success, Copiloto, Organization Auditor, Agente SDR), com quantas vezes cada um rodou nesta organização nos últimos 30 dias (dado real de ia_chamadas) e a regra de ouro: a IA prepara, a pessoa confirma.
Passo 5. As cinco vitórias rápidas da função. Quando a organização tem o dado, o link abre o registro real (último lead, proposta, contrato, cliente ou escopo) por /radar/boas-vindas/ir/<chave>, que registra a vitória; quando não tem, a tela mostra um exemplo de demonstração (marcado, determinístico pela organização, nunca gravado) e o link abre a tela vazia.
Passo 7. Celebração (sem animação quando prefers-reduced-motion), as quatro respostas ("entendi o que faz…"), o checklist de ativação com percentual, o Adoption Score, o caminho e os KPIs da função, e o botão para o Radar ou a Academy. Concluir registra boas_vindas_concluidas_em e recalcula o score.
Depois. A Home mostra o cartão "Ativação N% · Adoption Score" com o próximo item do checklist até fechar 100%. Em cada tela, a concha pergunta uma vez por sessão do navegador ao progresso.json e, se o tour daquela tela ainda não foi visto, mostra os passos; fechar marca como visto. A Academy registra cada lição aberta. O cron diário recalcula o score de todos os usuários da organização.

Regras de negócio

Nada bloqueia o uso. Toda etapa pode ser pulada; as boas-vindas puladas não voltam a interromper a Home e continuam disponíveis em /radar/boas-vindas. Sem a migração 0040, as telas explicam e a Radhr AI segue igual. Vive em src/radar.ts (Home) e src/radar/boas-vindas.ts.
O estado é da pessoa, na organização. Uma linha por usuário e organização; todo papel (inclusive leitura) escreve o próprio estado — as rotas de escrita exigem docs.ler, que todo papel tem. Ninguém edita o estado de outra pessoa. Vive em src/rbac/engine.ts e src/radar/permissoes.ts.
Real vence, demo identifica. O passo 5 e o passo 4 usam dado real quando existe; o demo é determinístico pela organização, marcado "Demonstração" e nunca gravado. Vive em src/adocao/demo.ts e src/adocao/welcome.ts.
Marcos vêm das trilhas que já existem. O engine lê acessos (escritas permitidas da pessoa), eventos assinados por ela (payload.por), as vitórias rápidas, os tours e as lições — não há instrumentação nova nas telas. Os marcos: primeiro acesso, boas-vindas concluídas, primeira ação, primeiro lead, primeira proposta, primeiro contrato, primeiro cliente, primeiro uso da IA, primeira recomendação executada, primeira conversão, organização configurada, três tours, vitórias completas, trilha Iniciante. Vive em src/adocao/engine.ts.
Adoption Score por função. Cada função tem pesos que somam 100 (sem função, os pesos padrão cobrem o ciclo inteiro). O score é recalculado no máximo a cada 10 minutos quando a pessoa abre as boas-vindas ou a Academy, ao concluir as boas-vindas e todo dia útil no cron. Vive em src/adocao/perfis.ts (pesos) e engine.ts.
Certificação. Uma trilha fecha quando todas as lições visíveis foram abertas pela Academy. Especialista Radhr exige as quatro trilhas e score ≥ 80. Lição cujo documento não é visível para a organização (seções técnicas, só a Witbiz) não conta. Vive em src/adocao/trilhas.ts e academy.ts.
O assistente responde com fonte. O Radhr Assistant usa o assistente do Knowledge Center (docs_assistente, cache, limite de IA da organização): sem citação válida, devolve os trechos oficiais mais próximos; a pergunta entra em doc_perguntas (canal assistente) e na telemetria. Não depende do plano (o Copiloto, sim).
Isolamento. usuario_adocao e adocao_eventos têm organizacao_id, filtro automático e RLS; o painel de adoção mostra só a organização da sessão (o master vê outra com ?org=).
Acessibilidade. Passos como regiões rotuladas, foco levado ao título a cada passo, teclado no tour (←/→, Enter, Esc, Tab preso ao cartão), aria-live nas respostas do assistente, contraste do Theme Engine, celebração desligada com prefers-reduced-motion.

Casos de uso

Vendedora no primeiro dia. Entra, vê "Bem-vindo", escolhe Vendedor e "Aumentar vendas", clica nos sete nós do fluxo, lê os três agentes "para você", abre a proposta real mais recente numa aba nova (vitória rápida), conclui, cai na Home com o cartão "Ativação 50%". Na primeira visita a Leads, o tour mostra a lista e os filtros.
Admin de organização nova. Escolhe Administrador; o checklist pede organização configurada e primeiro produto no catálogo; as vitórias rápidas levam a Organização, Usuários, Catálogo, Marca e Health Score. A organização não tem leads: o passo 5 mostra os exemplos de demonstração.
CEO que só lê. Papel leitura: pode concluir as boas-vindas, ver tours, abrir lições e perguntar ao assistente (escrita só do próprio estado). Score dele pesa IA, relatório e vitórias, não proposta.
Admin acompanhando a equipe. Abre Organização → Adoção: taxa de conclusão, tempo médio, drop-off por etapa, score por faixa e por função, retenção 7/30 dias, adoção da IA e engajamento.

Telas

**/radar/boas-vindas — Welcome Experience.** Casca própria (sem trilho): barra com marca, progresso e "Ir para o Radar"; trilho de passos à esquerda; o passo atual no centro; o Radhr Assistant à direita. ?etapa=n abre um passo. Os formulários enviam por fetch (JSON) e, sem script, por POST com redirect.
**/radar/boas-vindas/ir/<chave> — vitória rápida.** Registra e redireciona ao dado real (ou à tela).
**/radar/academy — Academy.** Cabeçalho com Adoption Score (anel), nível e função; trilhas com progresso e selos; busca inteligente; tutoriais (seção Fluxo), FAQs (seção Perguntas frequentes), vídeos (vazio até existirem), guias da organização; na lateral, checklist, caminho da função e links do Knowledge Center.
**/radar/academy/licao/<id> — lição.** Marca concluída e abre o documento em /radar/conhecimento/doc/<id>.
**/radar/organizacao/adocao — Adoção.** Item "Adoção" do grupo Organização no trilho (ao lado de "Acessos e permissões"). Painel do admin: números, drop-off por etapa, faixas de score, uso por função, engajamento; ?formato=json devolve as métricas.
Home. Redirect no primeiro acesso; cartão de ativação depois.
Tour. Cartão flutuante com foco no elemento, em qualquer tela listada, só na primeira visita.

Permissões

Ver as boas-vindas, a Academy, o progresso e escrever o próprio estado (etapa, tour, vitória, lição, pergunta): todo papel. As rotas POST exigem docs.ler na Permission Engine; no papel legado, boas-vindas e academy são escritas de consulta.
Painel de adoção (/radar/organizacao/adocao): admin da organização (owner, admin, manager e operação no papel legado); o master vê qualquer organização com ?org=.
Flag welcome_experience: nasce ligada em todos os planos pagos, no interno e no teste; desligável por organização em /radar/plataforma.

Perguntas frequentes

Já usava a Radhr AI e caí nas boas-vindas. Por quê? A flag foi ligada e o seu estado de adoção não existia. "Pular por agora" leva à Home e não volta a interromper; a experiência fica em Academy → "Continuar as boas-vindas" para quando quiser.

O tour apareceu numa tela e não quero mais. Fechar (ou "Pular tour") marca a tela como vista para você. Cada tela mostra o tour uma vez; não há tour nas telas não listadas.

Por que o meu Adoption Score não sobe depois de ver uma proposta? "Ver uma proposta" conta como vitória rápida e como "primeira proposta" quando aberta pelas boas-vindas. Fora delas, o marco vem de uma escrita no editor da proposta (salvar, enviar). O score é recalculado em até 10 minutos ao abrir as boas-vindas ou a Academy e todo dia útil no cron.

O exemplo de demonstração é um cliente de verdade? Não. É gerado pela semente da organização, marcado "Demonstração", nunca gravado, e some quando o dado real existe.

O Radhr Assistant é o Copiloto? Não. O assistente responde só pela documentação (com fonte) e existe em todo plano; o Copiloto conversa com os seus dados e propõe ações, a partir do Profissional.