Custom post type dando 404: flush_rewrite_rules na ativação do plugin

Registrei o post type imovel, o arquivo de listagem em /imoveis/ abre certinho, e /imoveis/casa-no-centro/ devolve o 404 do tema. Não é erro no register_post_type: as regras de reescrita do WordPress ficam gravadas na opção rewrite_rules da tabela wp_options, e ninguém mandou regravar.

A saída de 10 segundos

sudo -u www-data wp rewrite flush
sudo -u www-data wp rewrite list --match=/imoveis/casa-no-centro/

O segundo comando mostra qual regra pegou a URL. Se não voltar nada, o problema é outro: slug do rewrite batendo com uma página existente, ou public em false no register_post_type. Abrir Configurações > Links permanentes e clicar em Salvar dá no mesmo, porque essa tela chama o flush no final. O --hard do WP-CLI só serve pra regravar o .htaccess — em nginx não muda nada.

Resolver de vez no plugin

add_action('init', 'rt_registra_imovel');

register_activation_hook(__FILE__, function () {
    rt_registra_imovel();   // registra ANTES de gerar as regras
    flush_rewrite_rules();
});

register_deactivation_hook(__FILE__, 'flush_rewrite_rules');

A ordem é o pulo do gato. No request da ativação o init já passou, então o post type ainda não existe pro WordPress; chamar o flush sozinho regrava as regras sem as do CPT e o 404 continua. Por isso a função de registro roda na mão, ali dentro, antes do flush.

O que nunca fazer

Não chame flush_rewrite_rules() dentro do init pra garantir. Isso faz um UPDATE na wp_options a cada carregamento de página, do admin e do site, e derruba a performance inteira. Em tema, o gancho equivalente ao de ativação é o after_switch_theme.

Se travou nisso e precisa de ajuda, me chama aqui.