@neetru/cli 2.28.10 → 2.31.0

package/dist/lib/product-docs/ops.js

@@ -0,0 +1,975 @@
+/**
+ * Operações em disco dos docs de produto: `docs init`, `docs init --migrar` e
+ * `docs new`. Sem saída de terminal — devolvem o resultado e o comando decide
+ * como mostrar (texto ou `--json`).
+ *
+ * Regras de segurança (decisão do dono 2026-10-03):
+ *   - `init` é IDEMPOTENTE: nunca sobrescreve, só cria o que falta.
+ *   - `--migrar` NÃO move nem renomeia nada e NÃO mexe no corpo dos docs: só
+ *     acrescenta frontmatter inferido nos `.md` que não têm, gera
+ *     `_nomes-legados.json` (se não existir) e grava um relatório.
+ *   - Nada é escrito fora da pasta do repositório.
+ */
+import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
+import * as path from 'node:path';
+import { parseDoc, serializeFrontmatter } from './frontmatter.js';
+import { firstH1, toFileWords } from './markdown.js';
+import { CATEGORY_FOLDER, DAY_ONE_MODELS, FILE_NAME_REGEX, FOLDER_RULES, STANDARD_FOLDERS, STOPWORDS, THREAT_MODEL_SECTIONS, TYPE_DEFAULT_FOLDER, TYPE_MODELS, TYPE_PREFIX, topFolder, } from './structure.js';
+import { ADR_EXTRA, FOLDER_LABEL, NORMA_POLITICA_EXTRA, PLANO_RFC_EXTRA, PLANO_SPEC_EXTRA, THREAT_EXTRA, renderChangelog, renderDoc, renderIndex, renderReadme, } from './templates.js';
+import { EMBEDDED_TAXONOMY, productCategories } from './taxonomy.js';
+import { ensureDocsKey, productExposesApi, readProductVersion } from './config.js';
+import { firstCommitDate, git, lastCommitDate } from './git.js';
+import { listDocFiles, readLegacyNames } from './check.js';
+import { localIsoDate, todayIso } from './dates.js';
+const BOM = '\uFEFF';
+async function writeIfMissing(abs, content, dryRun) {
+    if (fsSync.existsSync(abs))
+        return false;
+    if (!dryRun) {
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, content, { encoding: 'utf8', flag: 'wx' });
+    }
+    return true;
+}
+/** Versões que ainda não foram lançadas de fato (scaffold recém-criado). */
+const INITIAL_VERSIONS = new Set(['0.0.0', '0.0.1', '0.1.0']);
+/**
+ * Semente do CHANGELOG. Produto "maduro" = versão do package.json além da
+ * inicial (0.0.x/0.1.0) OU tags de versão no git. Nesse caso NÃO se escreve
+ * "primeira versão" (bug da migração real: PDV 1.0.12 ganhava "Primeira versão
+ * do produto"): a entrada registra só o início do changelog neste formato,
+ * datada pela tag da versão (ou pelo último commit do package.json).
+ */
+export function changelogSeed(repo, today) {
+    const version = readProductVersion(repo);
+    const v = version && /^\d+\.\d+\.\d+/.test(version) ? version : '0.1.0';
+    const inGit = !!repo.gitRoot;
+    const tags = inGit ? (git(repo.configDir, ['tag', '--list']) ?? '').split(/\r?\n/).filter((t) => /^v?\d+\.\d+\.\d+/.test(t)) : [];
+    const maduro = !INITIAL_VERSIONS.has(v) || tags.length > 0;
+    if (!maduro)
+        return { version: v, date: today, maduro, origemData: 'hoje' };
+    const tag = tags.find((t) => t === `v${v}` || t === v);
+    const tagDate = tag ? git(repo.configDir, ['log', '-1', '--format=%cs', tag]) : null;
+    if (tagDate && /^\d{4}-\d{2}-\d{2}$/.test(tagDate))
+        return { version: v, date: tagDate, maduro, origemData: 'tag' };
+    const pkgDate = inGit ? git(repo.configDir, ['log', '-1', '--format=%cs', '--', 'package.json']) : null;
+    if (pkgDate && /^\d{4}-\d{2}-\d{2}$/.test(pkgDate))
+        return { version: v, date: pkgDate, maduro, origemData: 'package.json no git' };
+    return { version: v, date: today, maduro, origemData: 'hoje' };
+}
+function dayOneSpecs(repo, today) {
+    const name = repo.name;
+    const base = { product: repo.slug, status: 'draft', date: today, updated: today, owner: 'produto' };
+    return {
+        'produto/VISAO_DO_PRODUTO.md': {
+            ...base,
+            title: 'Visão do produto',
+            description: `O problema que o ${name} resolve, para quem e o que ele faz, como referência para quem chega ao produto.`,
+            category: 'Produto',
+            subcategory: 'visao',
+            type: 'referencia',
+            audience: 'dev-produto',
+            lead: 'Para a equipe do produto, o staff do Core e quem escreve a ajuda ao usuário. Rascunho: complete antes do primeiro deploy em produção.',
+            sections: DAY_ONE_MODELS['produto/VISAO_DO_PRODUTO.md'],
+        },
+        'arquitetura/ARQUITETURA.md': {
+            ...base,
+            title: `Arquitetura do ${name}`,
+            description: `Como o ${name} é montado e como se integra ao Core: SDK, login, banco, credenciais e ambientes.`,
+            category: 'Plataforma',
+            subcategory: 'visao-geral',
+            type: 'arquitetura',
+            audience: 'dev-produto',
+            lead: 'Para quem desenvolve o produto. Rascunho: complete antes do primeiro deploy em produção.',
+            sections: DAY_ONE_MODELS['arquitetura/ARQUITETURA.md'],
+            extra: {
+                'Integração com o Core': [
+                    '- **Dados:** só pelo `@neetru/sdk` — o produto nunca fala direto com o banco do Core.',
+                    '- **Login:** OIDC do Core.',
+                    '- **Banco:** banco isolado por produto, provisionado pelo Core (`neetru db`).',
+                    '- **Credenciais:** injetadas no servidor pelo Core; nunca no navegador nem em `.env` versionado.',
+                    '- **Ambientes:** dev → homologação (staging) → produção.',
+                ].join('\n'),
+            },
+        },
+        'runbooks/RUNBOOK_DEPLOY.md': {
+            ...base,
+            title: `Deploy do ${name}`,
+            description: `Passo a passo para levar uma versão do ${name} de dev a produção, com verificação e como desfazer.`,
+            category: 'Operações',
+            subcategory: 'producao',
+            type: 'runbook',
+            audience: 'dev-produto',
+            lead: 'Para quem publica uma versão. Rascunho: confira os comandos com o produto antes do primeiro deploy em produção.',
+            sections: DAY_ONE_MODELS['runbooks/RUNBOOK_DEPLOY.md'],
+            extra: {
+                'Passo a passo': [
+                    '1. Atualize o `CHANGELOG.md` com a versão do `package.json`.',
+                    '2. Se o esquema do banco mudou: `neetru db apply` (veja a skill `neetru-migrations`).',
+                    '3. `neetru deploy --env staging` e confira.',
+                    '4. `neetru deploy --env prod` (pede MFA).',
+                ].join('\n'),
+                'Verificação': '- `neetru deployments get <deploymentId>` mostra as fases e o erro, se houver.\n- O endereço de saúde do produto responde 200.',
+                'Como desfazer': '- `neetru deployments rollback <deploymentId>`.',
+            },
+        },
+        'api/API_V1.md': {
+            ...base,
+            title: 'Contrato da API v1',
+            description: 'Endpoints, autenticação, erros e regras de evolução da /api/v1 que o app e as integrações usam.',
+            category: 'API',
+            subcategory: 'rest-v1',
+            type: 'referencia',
+            audience: 'dev-produto',
+            lead: 'Para quem consome a API do produto (app móvel, integrações). O doc descreve o que existe; se fugir da convenção, diga onde e por quê.',
+            sections: DAY_ONE_MODELS['api/API_V1.md'],
+            extra: { Endpoints: '### GET /api/v1/me\n\n<!-- Autenticação, corpo, respostas, erros e exemplo. -->' },
+        },
+    };
+}
+function nameOutOfRule(rel) {
+    const base = path.posix.basename(rel);
+    const top = topFolder(rel);
+    if (top === 'superpowers' || top === '_archive' || top === '_audit' || base === 'INDEX.md')
+        return false;
+    return !FILE_NAME_REGEX.test(base);
+}
+/** Agrupa para o índice: pastas do padrão → superpowers → fora do padrão → raiz → arquivo. */
+export function groupIndex(items) {
+    const by = new Map();
+    for (const it of items) {
+        const top = topFolder(it.rel);
+        if (!by.has(top))
+            by.set(top, []);
+        by.get(top).push(it);
+    }
+    const groups = [];
+    const take = (folder, label, foraDoPadrao, nota) => {
+        const list = by.get(folder);
+        if (list?.length)
+            groups.push({ label, files: list, foraDoPadrao, nota });
+        by.delete(folder);
+    };
+    for (const [folder, label] of Object.entries(FOLDER_LABEL))
+        take(folder, label, false);
+    take('superpowers', 'Planos (superpowers)', false);
+    const others = [...by.keys()].filter((k) => k !== '' && k !== '_archive' && k !== '_audit').sort();
+    for (const k of others) {
+        take(k, `${k}/ — fora do padrão`, true, 'Pasta fora da estrutura do protocolo: mova os docs para a pasta do assunto (veja o relatório do `neetru docs init --migrar`).');
+    }
+    take('', 'Raiz de docs/ — fora do padrão', true, 'Na raiz de docs/ só fica este índice: mova estes docs para a pasta do assunto.');
+    take('_archive', 'Arquivo morto', false);
+    take('_audit', 'Relatórios automáticos', false);
+    return groups;
+}
+/** `neetru docs init` — cria o mínimo do primeiro dia sem sobrescrever nada. */
+export async function initProductDocs(repo, opts = {}) {
+    const today = opts.today ?? todayIso();
+    const dryRun = !!opts.dryRun;
+    // --com-api é pedido explícito: liga `docs.api` mesmo que a chave já exista com false.
+    const configKeysAdded = await ensureDocsKey(repo, opts.comApi ? { api: true } : {}, dryRun, opts.comApi ? ['api'] : []);
+    const withApi = !!opts.comApi || productExposesApi(repo);
+    const docsRoot = repo.docs.root;
+    const absDocs = path.join(repo.cwd, docsRoot);
+    const created = [];
+    const skipped = [];
+    const folders = [];
+    for (const f of STANDARD_FOLDERS) {
+        const abs = path.join(absDocs, f);
+        if (!fsSync.existsSync(abs)) {
+            folders.push(`${docsRoot}/${f}`);
+            if (!dryRun)
+                await fs.mkdir(abs, { recursive: true });
+        }
+    }
+    const specs = dayOneSpecs(repo, today);
+    for (const [rel, spec] of Object.entries(specs)) {
+        if (rel === 'api/API_V1.md' && !withApi)
+            continue;
+        const repoRel = `${docsRoot}/${rel}`;
+        if (await writeIfMissing(path.join(absDocs, rel), renderDoc(spec), dryRun))
+            created.push(repoRel);
+        else
+            skipped.push(repoRel);
+    }
+    // index.md por último: lista TUDO o que existe (inclusive o que acabou de
+    // ser criado), marcando o que está fora do padrão.
+    const indexRel = `${docsRoot}/index.md`;
+    if (!fsSync.existsSync(path.join(absDocs, 'index.md'))) {
+        const existing = await listDocFiles(repo);
+        const planned = created.filter((c) => c.startsWith(`${docsRoot}/`)).map((c) => c.slice(docsRoot.length + 1));
+        const all = [...new Set([...existing, ...planned])].filter((r) => r !== 'index.md').sort();
+        const items = [];
+        for (const rel of all) {
+            let title = specs[rel]?.title ?? path.posix.basename(rel, '.md');
+            try {
+                const p = parseDoc(await fs.readFile(path.join(absDocs, rel), 'utf8'));
+                title = (typeof p.data.title === 'string' && p.data.title) || firstH1(p.body) || title;
+            }
+            catch {
+                /* dry-run: ainda não existe */
+            }
+            items.push({ rel, title, nomeForaDaRegra: nameOutOfRule(rel) });
+        }
+        if (await writeIfMissing(path.join(absDocs, 'index.md'), renderIndex({ product: repo.slug, name: repo.name, today, groups: groupIndex(items) }), dryRun)) {
+            created.push(indexRel);
+        }
+    }
+    else {
+        skipped.push(indexRel);
+    }
+    // README / CHANGELOG na raiz (sem frontmatter)
+    const readme = renderReadme(repo.name).split('docs/').join(`${docsRoot}/`);
+    if (await writeIfMissing(path.join(repo.cwd, 'README.md'), readme, dryRun))
+        created.push('README.md');
+    else
+        skipped.push('README.md');
+    if (await writeIfMissing(path.join(repo.cwd, 'CHANGELOG.md'), renderChangelog(changelogSeed(repo, today)), dryRun)) {
+        created.push('CHANGELOG.md');
+    }
+    else
+        skipped.push('CHANGELOG.md');
+    // .gitkeep nas pastas que ficaram vazias (o git não versiona pasta vazia)
+    if (!dryRun) {
+        for (const f of STANDARD_FOLDERS) {
+            const abs = path.join(absDocs, f);
+            try {
+                if ((await fs.readdir(abs)).length === 0)
+                    await fs.writeFile(path.join(abs, '.gitkeep'), '');
+            }
+            catch {
+                /* ignora */
+            }
+        }
+    }
+    return { slug: repo.slug, docsRoot, created, skipped, folders, configKeysAdded, withApi, dryRun };
+}
+/** Pastas legadas comuns nos produtos → pasta do protocolo. */
+const LEGACY_FOLDERS = {
+    architecture: 'arquitetura',
+    arquitetura: 'arquitetura',
+    design: 'arquitetura',
+    'guia-do-usuario': 'usuario',
+    'guia-usuario': 'usuario',
+    help: 'usuario',
+    ajuda: 'usuario',
+    _review: 'relatorios',
+    review: 'relatorios',
+    reviews: 'relatorios',
+    auditorias: 'relatorios',
+    deploy: 'runbooks',
+    runbook: 'runbooks',
+    adr: 'decisoes',
+    adrs: 'decisoes',
+    decisions: 'decisoes',
+    guides: 'guias',
+    security: 'seguranca',
+    integrations: 'integracoes',
+    plans: 'planos',
+    specs: 'planos',
+};
+function guessTypeFromName(base) {
+    const n = base.replace(/\.md$/i, '').toUpperCase().replace(/-/g, '_');
+    const rules = [
+        [/^ADR_?\d+/, 'adr'],
+        [/^(RUNBOOK|SETUP)_|_RUNBOOK$|DEPLOY_PROD/, 'runbook'],
+        [/^GUIA_|^GUIDE_|_GUIDE$|^HOWTO/, 'guia'],
+        [/^DESIGN_SYSTEM/, 'referencia'],
+        [/^(ARQUITETURA|ARCHITECTURE|PLATFORM|DESIGN)(_|$)/, 'arquitetura'],
+        [/^(PROTOCOLO|POLITICA|POLICY)_/, 'norma'],
+        [/^(PLANO|PROJ|PLAN|SPEC|RFC|ROADMAP|EXECUTION_PLAN)(_|$)/, 'plano'],
+        [/^(AUDITORIA|AUDIT|REVIEW|ANALISE|RELATORIO|INVENTARIO|ACHADO|BACKLOG|STATUS)(_|$)/, 'relatorio'],
+        [/^(INCIDENTE|INCIDENT|POSTMORTEM)(_|$)/, 'incidente'],
+        [/^(ATA|DECISOES|MINUTES)(_|$)/, 'ata'],
+        [/^(INDEX|README)$/, 'indice'],
+        [/^CHANGELOG/, 'changelog'],
+        [/(_API_REFERENCE|_REFERENCE|^REFERENCIA_|^API(_V\d+)?$)/, 'referencia'],
+    ];
+    for (const [re, type] of rules)
+        if (re.test(n))
+            return { type, why: `prefixo do nome (${base})`, conf: 'alta' };
+    return null;
+}
+function guessCategoryFromName(base, cats) {
+    const n = base.toUpperCase().replace(/-/g, '_');
+    const rules = [
+        [/PRIMEIROS_PASSOS|COMECE_AQUI|GETTING_STARTED|ONBOARDING/, 'Ajuda ao usuário', 'primeiros-passos'],
+        [/DESIGN_SYSTEM|UI_|UX_/, 'Desenvolvimento', 'interface'],
+        [/FAQ|PERGUNTAS/, 'Ajuda ao usuário', 'perguntas-frequentes'],
+        [/MELI|MERCADO_?LIVRE|MAGALU|AMAZON|SHOPEE|MARKETPLACE|BLING|TRAY/, 'Integrações', 'marketplaces'],
+        [/STRIPE|PAGAMENTO|PAYMENT|PIX|BOLETO|ASAAS|PAGSEGURO|MERCADO_?PAGO/, 'Integrações', 'pagamentos'],
+        [/NFE|NFCE|FISCAL|SEFAZ|NOTA_FISCAL|SAT_/, 'Integrações', 'fiscal'],
+        [/WHATSAPP|SMS|EMAIL|E_MAIL|MENSAG|TELEGRAM/, 'Integrações', 'mensageria'],
+        [/THREAT|AMEACA/, 'Segurança', 'vulnerabilidades'],
+        [/SECURITY|SEGURANCA|LGPD|PRIVAC/, 'Segurança', 'configuracao-segura'],
+        [/DATABASE|MODELO_DE_DADOS|DATA_MODEL|SCHEMA|BANCO/, 'Dados', 'bancos-de-produto'],
+        [/MIGRA/, 'Dados', 'migracoes'],
+        [/BACKUP/, 'Dados', 'backup-e-recuperacao'],
+        [/DEPLOY|RELEASE/, 'Operações', 'producao'],
+        [/INCIDENT|ALERT/, 'Observabilidade', 'incidentes'],
+        [/GLOSSARIO|GLOSSARY/, 'Produto', 'glossario'],
+        [/ROADMAP/, 'Produto', 'roadmap'],
+        [/VISAO|VISION|EXECUTIVE_SUMMARY|OVERVIEW|PRODUTO/, 'Produto', 'visao'],
+        [/OIDC|OAUTH|LOGIN|AUTH|SSO/, 'Identidade', 'oidc'],
+        [/PERMISS|RBAC|ROLES/, 'Identidade', 'permissoes'],
+        [/API/, 'API', 'rest-v1'],
+        [/DEV_LOCAL|DESENVOLVIMENTO_LOCAL|LOCAL_DEV|SETUP/, 'Desenvolvimento', 'ambiente-local'],
+        [/TEST|QA|E2E/, 'Desenvolvimento', 'qualidade-e-testes'],
+    ];
+    for (const [re, category, subcategory] of rules) {
+        // casa no começo de uma palavra do nome ("PASSOS" não casa com SSO, "LATEST" não casa com TEST)
+        const anchored = new RegExp(`(?:^|_)(?:${re.source})`);
+        if (anchored.test(n) && cats[category]?.includes(subcategory)) {
+            return { category, subcategory, why: `palavra-chave no nome (${base})`, conf: 'media' };
+        }
+    }
+    return null;
+}
+const FAMILY_STATUS = { vivo: 'active', plano: 'proposed', registro: 'historical' };
+/** Primeiro parágrafo de texto do corpo, reduzido a uma frase de até 200 caracteres. */
+function guessDescription(body) {
+    // Junta os parágrafos de texto (fora de código, cabeçalho, lista, tabela).
+    const paras = [];
+    let cur = [];
+    let inFence = false;
+    const flush = () => {
+        if (cur.length)
+            paras.push(cur.join(' '));
+        cur = [];
+    };
+    for (const l of body.split(/\r?\n/)) {
+        if (/^\s{0,3}(```|~~~)/.test(l)) {
+            flush();
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const t = l.trim();
+        // linha indentada = continuação de item de lista ou código indentado
+        if (!t || /^\s{2,}/.test(l) || /^(#|\||[-*+]\s|\d+\.\s|<!--|!\[|---|===)/.test(t)) {
+            flush();
+            continue;
+        }
+        cur.push(t.replace(/^>\s*/, ''));
+        if (paras.length >= 6)
+            break;
+    }
+    flush();
+    for (const para of paras.slice(0, 6)) {
+        const text = para
+            .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+            .replace(/[`*_]/g, '')
+            .replace(/\p{Extended_Pictographic}\uFE0F?/gu, '')
+            .replace(/\s+/g, ' ')
+            .trim();
+        // Pula aviso de estado e linha de metadado ("Status: …", "Data: …", "Nota: …").
+        if (/^(atualizado|obsoleto|desatualizado|parcialmente|snapshot|aten[çc][ãa]o|aviso|deprecated|legado)\b/i.test(text))
+            continue;
+        if (/^[\wÀ-ú ]{2,28}:\s/.test(text))
+            continue;
+        const first = (text.match(/^.*?[.!?](\s|$)/)?.[0] ?? text).trim().replace(/[:;,]+$/, '');
+        if (first.length < 20)
+            continue;
+        const cut = first.length > 200 ? `${first.slice(0, 196).replace(/\s+\S*$/, '')}…` : first;
+        return /[.!?…]$/.test(cut) ? cut : `${cut}.`;
+    }
+    return null;
+}
+/** `_revisado: AAAA-MM-DD_` (e variações) escrito no corpo. */
+function bodyRevisedDate(body) {
+    const m = body.match(/_?\*?(revisado|atualizado|updated|última atualização|ultima atualizacao)\*?\s*[:=]\s*\*?(\d{4}-\d{2}-\d{2})/i);
+    return m ? m[2] : null;
+}
+function humanize(base) {
+    const t = base.replace(/\.md$/i, '').replace(/^\d{4}-\d{2}-\d{2}[-_]/, '').replace(/[-_]+/g, ' ').trim().toLowerCase();
+    return t.charAt(0).toUpperCase() + t.slice(1);
+}
+/**
+ * Nome pela regra do §8.1 — preservando a data ISO COM hífens no fim
+ * (`AUDITORIA-GERAL-2026-06-30.md` → `AUDITORIA_GERAL_2026-06-30.md`; antes
+ * virava `…_2026_06_30`, que falha no NM002). Registro sem data no nome ganha
+ * a do frontmatter; doc vivo perde a data (data no nome é só de registro).
+ */
+export function suggestedName(base, type, family, fmDate) {
+    const stem = base.replace(/\.md$/i, '');
+    const dm = stem.match(/(\d{4}-\d{2}(?:-\d{2})?)/);
+    const nameDate = dm?.[1];
+    const words = toFileWords(nameDate ? stem.replace(nameDate, ' ') : stem);
+    if (type === 'adr') {
+        const num = words[0] === 'ADR' && /^\d+$/.test(words[1] ?? '') ? words[1].padStart(4, '0') : '0001';
+        const rest = words.slice(words[0] === 'ADR' ? 2 : 0);
+        return `ADR-${num}_${rest.join('_') || 'DECISAO'}.md`;
+    }
+    // "01-visao" → descarta o número de ordem
+    let clean = /^\d+$/.test(words[0] ?? '') ? words.slice(1) : words;
+    if (type === 'relatorio' && clean[0] === 'AUDIT')
+        clean = ['AUDITORIA', ...clean.slice(1)];
+    if (!clean.length)
+        clean = ['DOC'];
+    if (/^\d/.test(clean[0]))
+        clean = ['DOC', ...clean];
+    const subject = clean.join('_');
+    const date = family === 'registro' ? nameDate ?? fmDate : family === 'plano' ? nameDate : undefined;
+    return date ? `${subject}_${date}.md` : `${subject}.md`;
+}
+/**
+ * Destinos que o §10 do protocolo de produtos nomeia (os mesmos casos nos 3
+ * produtos): CHANGELOG na raiz, RUNBOOK_DEPLOY em runbooks/, API_V1 em api/,
+ * ARQUITETURA/MODELO_DE_DADOS em arquitetura/, a visão a partir do resumo
+ * executivo, os modelos do zelo que saem do repo.
+ */
+function canonicalDestination(rel, cats) {
+    const r = rel.toLowerCase().replace(/\\/g, '/');
+    const base = path.posix.basename(r);
+    const cg = (category, subcategory, why, conf = 'alta') => cats[category]?.includes(subcategory) ? { category, subcategory, why, conf } : { category: 'Plataforma', subcategory: 'visao-geral', why, conf: 'baixa' };
+    const t = (type, why, conf = 'alta') => ({ type, why, conf });
+    const why = '§10 do protocolo de produtos';
+    if (/^changelog[-_.]/.test(base) && topFolder(rel) === '') {
+        return {
+            type: t('changelog', `${why} (changelog solto em docs/)`),
+            category: cg('Documentação', 'indices', why, 'media'),
+            destino: 'CHANGELOG.md (raiz do repositório — junte o conteúdo no formato Keep a Changelog)',
+        };
+    }
+    if (r === 'deploy/readme.md' || /deploy[-_](prod[-_])?runbook|runbook[-_]deploy|^deploy\.md$/.test(base)) {
+        return { type: t('runbook', `${why} (deploy)`), category: cg('Operações', 'producao', why), destinoDocs: 'runbooks/RUNBOOK_DEPLOY.md' };
+    }
+    if (/^(architecture|arquitetura)\.md$/.test(base) && ['', 'architecture', 'arquitetura', 'design'].includes(topFolder(rel))) {
+        return { type: t('arquitetura', why), category: cg('Plataforma', 'visao-geral', why), destinoDocs: 'arquitetura/ARQUITETURA.md' };
+    }
+    if (/^(database[-_]model|database|data[-_]model|modelo[-_]de[-_]dados)\.md$/.test(base)) {
+        return { type: t('referencia', why), category: cg('Dados', 'bancos-de-produto', why), destinoDocs: 'arquitetura/MODELO_DE_DADOS.md' };
+    }
+    if (/^api[-_]v1\.md$/.test(base)) {
+        return { type: t('referencia', why), category: cg('API', 'rest-v1', why), destinoDocs: 'api/API_V1.md' };
+    }
+    if (/^executive[-_]summary\.md$/.test(base)) {
+        return {
+            type: t('referencia', why),
+            category: cg('Produto', 'visao', why),
+            destinoDocs: 'produto/VISAO_DO_PRODUTO.md',
+            nota: 'Base para a visão do produto: reescreva no modelo da VISAO_DO_PRODUTO.md (§10).',
+        };
+    }
+    if (/(^|\/)design\/modelos\//.test(r)) {
+        return {
+            type: t('referencia', 'modelo de documento do zelo'),
+            category: cg('Documentação', 'protocolos', why, 'media'),
+            destino: '(remover do repositório — os modelos agora vêm embutidos na CLI: `neetru docs new`)',
+        };
+    }
+    return null;
+}
+/** Destino + tipo COERENTES: o tipo sugerido é sempre aceito na pasta sugerida (sem FM005 depois de mover). */
+function planDestination(a) {
+    const { base, top, effFolder, cats } = a;
+    const named = guessTypeFromName(base);
+    const catByName = guessCategoryFromName(base, cats);
+    const ruleOf = (folder) => FOLDER_RULES.find((r) => r.folder === folder);
+    const accepts = (folder, type) => {
+        const r = ruleOf(folder);
+        return !!r && (r.types === 'qualquer' || r.types.includes(type));
+    };
+    const folderCat = (folder, why) => {
+        const r = ruleOf(folder);
+        return r && cats[r.category]?.includes(r.subcategory) ? { category: r.category, subcategory: r.subcategory, why, conf: 'media' } : null;
+    };
+    const fallbackCat = { category: 'Plataforma', subcategory: 'visao-geral', why: 'sem pista — padrão', conf: 'baixa' };
+    // Arquivo morto e superpowers ficam onde estão.
+    if (top === '_archive' || top === 'superpowers') {
+        const type = top === 'superpowers' ? { type: 'plano', why: 'pasta superpowers/', conf: 'alta' } : named ?? { type: 'referencia', why: 'arquivo morto', conf: 'baixa' };
+        return { type, category: catByName ?? folderCat(top, `padrão da pasta ${top}/`) ?? fallbackCat, folder: top, keepSubPath: true };
+    }
+    // Índice da raiz.
+    if (top === '' && (base.toLowerCase() === 'index.md' || base.toLowerCase() === 'readme.md')) {
+        return { type: { type: 'indice', why: 'índice na raiz de docs/', conf: 'alta' }, category: { category: 'Documentação', subcategory: 'indices', why: 'índice', conf: 'alta' } };
+    }
+    // Pasta conhecida (do protocolo ou legada): a pasta manda, salvo registro/plano de nome claro.
+    if (effFolder) {
+        const isReadme = base.toLowerCase() === 'readme.md';
+        let type = named && !(isReadme && named.type === 'indice') ? named : null;
+        const fam = type ? EMBEDDED_TAXONOMY.types[type.type] : undefined;
+        if (type && !accepts(effFolder, type.type) && (fam === 'registro' || fam === 'plano' || type.type === 'adr')) {
+            const folder = CATEGORY_FOLDER[catByName?.category ?? ''] && accepts(CATEGORY_FOLDER[catByName.category], type.type) ? CATEGORY_FOLDER[catByName.category] : TYPE_DEFAULT_FOLDER[type.type];
+            return { type, category: catByName ?? folderCat(folder, `padrão da pasta ${folder}/`) ?? fallbackCat, folder };
+        }
+        if (!type || !accepts(effFolder, type.type)) {
+            const r = ruleOf(effFolder);
+            const t0 = r.types === 'qualquer' ? 'referencia' : r.types[0];
+            type = { type: t0, why: `${isReadme ? 'README de pasta — ' : ''}tipo da pasta ${effFolder}/ (§3)`, conf: r.types !== 'qualquer' && r.types.length === 1 ? 'alta' : 'media' };
+        }
+        let category = catByName ?? folderCat(effFolder, `padrão da pasta ${effFolder}/`) ?? fallbackCat;
+        if (effFolder === 'usuario' && category.category !== 'Ajuda ao usuário')
+            category = folderCat('usuario', 'padrão da pasta usuario/') ?? category;
+        return { type, category, folder: effFolder, keepSubPath: true };
+    }
+    // Raiz de docs/ ou pasta desconhecida: escolhe o destino e um tipo que caiba nele.
+    let type = named && named.type !== 'indice' ? named : { type: 'referencia', why: top ? `pasta ${top}/ fora do padrão, sem pista no nome` : 'arquivo solto na raiz de docs/, sem pista no nome', conf: 'baixa' };
+    const byCat = catByName ? CATEGORY_FOLDER[catByName.category] : undefined;
+    let folder = byCat && accepts(byCat, type.type) ? byCat : TYPE_DEFAULT_FOLDER[type.type] ?? byCat ?? 'arquitetura';
+    if (!accepts(folder, type.type)) {
+        const r = ruleOf(folder);
+        type = { type: r.types === 'qualquer' ? 'referencia' : r.types[0], why: `tipo coerente com o destino ${folder}/`, conf: 'baixa' };
+    }
+    const category = catByName ?? folderCat(folder, `padrão da pasta de destino ${folder}/`) ?? fallbackCat;
+    return { type, category, folder };
+}
+/**
+ * `neetru docs init --migrar` — frontmatter inferido nos `.md` sem frontmatter,
+ * `_nomes-legados.json` e relatório. NÃO move, NÃO renomeia, NÃO edita corpo.
+ */
+export async function migrateProductDocs(repo, opts = {}) {
+    const dryRun = !!opts.dryRun;
+    const today = opts.today ?? todayIso();
+    const cats = productCategories(opts.taxonomy ?? EMBEDDED_TAXONOMY);
+    const types = (opts.taxonomy ?? EMBEDDED_TAXONOMY).types;
+    const docsRoot = repo.docs.root;
+    const absDocs = path.join(repo.cwd, docsRoot);
+    const configKeysAdded = await ensureDocsKey(repo, {}, dryRun);
+    const files = (await listDocFiles(repo)).filter((f) => topFolder(f) !== '_audit');
+    const legacy = readLegacyNames(repo);
+    const inGit = git(repo.cwd, ['rev-parse', '--is-inside-work-tree']) === 'true';
+    const out = [];
+    const offRule = [];
+    for (const rel of files) {
+        const abs = path.join(absDocs, rel);
+        const raw = await fs.readFile(abs, 'utf8');
+        const parsed = parseDoc(raw);
+        const base = path.posix.basename(rel);
+        const top = topFolder(rel);
+        const nameExempt = rel === 'index.md' || base === 'INDEX.md' || top === 'superpowers' || top === '_archive' || legacy.has(rel);
+        const nomeForaDaRegra = !nameExempt && !FILE_NAME_REGEX.test(base);
+        if (nomeForaDaRegra)
+            offRule.push(rel);
+        if (parsed.hasFrontmatter) {
+            const obs = [];
+            if (parsed.error)
+                obs.push(`Frontmatter inválido (${parsed.error}) — corrija à mão; nada foi alterado.`);
+            else if (parsed.data.product !== repo.slug)
+                obs.push(`Já tem frontmatter, sem \`product: ${repo.slug}\` — acrescente à mão.`);
+            out.push({ file: `${docsRoot}/${rel}`, acao: parsed.error ? 'frontmatter-invalido' : 'ja-tinha-frontmatter', inferencias: [], nomeForaDaRegra, observacoes: obs });
+            continue;
+        }
+        const inf = [];
+        const obs = [];
+        const fm = {};
+        const repoRel = `${docsRoot}/${rel}`;
+        // título
+        const h1 = firstH1(parsed.body);
+        const title = h1 ?? humanize(base);
+        fm.title = title;
+        inf.push({ campo: 'title', valor: title, origem: h1 ? 'primeiro H1' : 'nome do arquivo', confianca: h1 ? 'alta' : 'baixa' });
+        if (!h1)
+            obs.push('Sem H1: o validador vai pedir um H1 igual ao `title` (TI001).');
+        // descrição (só se der para tirar uma frase do primeiro parágrafo)
+        const desc = guessDescription(parsed.body);
+        if (desc) {
+            fm.description = desc;
+            inf.push({ campo: 'description', valor: desc, origem: 'primeira frase do texto', confianca: 'baixa' });
+        }
+        else {
+            obs.push('Sem `description`: escreva uma frase de 40 a 200 caracteres (FM002).');
+        }
+        fm.product = repo.slug;
+        // pasta efetiva (protocolo ou legado) e destino sugerido
+        const effFolder = top === '' ? '' : FOLDER_RULES.some((r) => r.folder === top) ? top : LEGACY_FOLDERS[top.toLowerCase()];
+        const canon = canonicalDestination(rel, cats);
+        const plan = canon ?? planDestination({ rel, base, top, effFolder, cats });
+        const tg = plan.type;
+        fm.type = tg.type;
+        inf.push({ campo: 'type', valor: tg.type, origem: tg.why, confianca: tg.conf });
+        const cg = plan.category;
+        fm.category = cg.category;
+        fm.subcategory = cg.subcategory;
+        inf.push({ campo: 'category/subcategory', valor: `${cg.category}/${cg.subcategory}`, origem: cg.why, confianca: cg.conf });
+        // status
+        const family = types[tg.type] ?? 'vivo';
+        const status = top === '_archive' ? 'archived' : tg.type === 'adr' ? 'active' : FAMILY_STATUS[family];
+        fm.status = status;
+        inf.push({ campo: 'status', valor: status, origem: top === '_archive' ? 'pasta _archive/' : `família ${family}`, confianca: 'media' });
+        // datas
+        const nameDate = base.match(/(\d{4}-\d{2}-\d{2})/)?.[1];
+        const first = inGit ? firstCommitDate(repo.cwd, repoRel) : null;
+        const last = inGit ? lastCommitDate(repo.cwd, repoRel) : null;
+        const mtime = localIsoDate((await fs.stat(abs)).mtime);
+        let date = (family === 'registro' && nameDate) || first || nameDate || mtime;
+        const dateFromMtime = !(family === 'registro' && nameDate) && !first && !nameDate;
+        const dateInf = {
+            campo: 'date',
+            valor: date,
+            origem: family === 'registro' && nameDate ? 'data do nome' : first ? 'primeiro commit do arquivo' : nameDate ? 'data do nome' : 'data de modificação do arquivo',
+            confianca: first || nameDate ? 'alta' : 'baixa',
+        };
+        inf.push(dateInf);
+        if (family === 'vivo') {
+            const revised = bodyRevisedDate(parsed.body);
+            let updated = revised ?? last ?? mtime;
+            if (updated < date) {
+                // `updated` ≥ `date` (FM007): se a data de criação é só o mtime, ela é que cede.
+                if (dateFromMtime) {
+                    date = updated;
+                    dateInf.valor = date;
+                    dateInf.origem = 'igual ao updated (sem histórico de criação)';
+                }
+                else
+                    updated = date;
+            }
+            fm.updated = updated;
+            inf.push({
+                campo: 'updated',
+                valor: updated,
+                origem: revised ? 'metadado no corpo (ex.: _revisado: …_) — a linha do corpo continua lá' : last ? 'último commit do arquivo' : 'data de modificação do arquivo',
+                confianca: revised || last ? 'alta' : 'baixa',
+            });
+        }
+        fm.date = date;
+        fm.owner = 'produto';
+        const audienceFolder = plan.folder ?? effFolder ?? top;
+        const audience = audienceFolder === 'usuario' ? 'publico' : 'dev-produto';
+        fm.audience = audience;
+        inf.push({ campo: 'audience', valor: audience, origem: `padrão da pasta ${audienceFolder || 'raiz'}/`, confianca: 'media' });
+        if (tg.type === 'adr') {
+            const num = base.match(/adr[-_]?(\d+)/i)?.[1];
+            if (num)
+                fm.adr = Number.parseInt(num, 10);
+        }
+        if (top === '_archive') {
+            fm.archived_at = today;
+            fm.archived_from = rel.replace(/^_archive\//, '');
+            fm.archive_reason = 'Migrado para o protocolo de docs: já estava no arquivo morto.';
+            obs.push('Carimbo de arquivamento inferido — confira `archived_at` e `archive_reason`.');
+        }
+        fm.tags = ['migrado'];
+        if (h1 && h1 !== title)
+            obs.push('H1 diferente do title.');
+        let sugestaoDestino;
+        if (plan.destinoDocs) {
+            sugestaoDestino = `${docsRoot}/${plan.destinoDocs}`;
+        }
+        else if (plan.destino) {
+            sugestaoDestino = plan.destino;
+        }
+        else if (plan.folder !== undefined) {
+            const newBase = top === 'superpowers' || top === '_archive' || base === 'index.md'
+                ? base
+                : suggestedName(base, tg.type, family, date);
+            const dest = [plan.folder, plan.keepSubPath ? rel.split('/').slice(1, -1).join('/') : '', newBase].filter(Boolean).join('/');
+            if (dest !== rel)
+                sugestaoDestino = `${docsRoot}/${dest}`;
+        }
+        if (plan.nota)
+            obs.push(plan.nota);
+        const eol = parsed.eol;
+        const block = serializeFrontmatter(fm, eol);
+        const textNoBom = parsed.bom ? raw.slice(1) : raw;
+        const next = `${parsed.bom ? BOM : ''}${block}${eol}${eol}${textNoBom.replace(/^(\r?\n)+/, '')}`;
+        if (!dryRun) {
+            const tmp = `${abs}.${process.pid}.tmp`;
+            await fs.writeFile(tmp, next, 'utf8');
+            await fs.rename(tmp, abs);
+        }
+        out.push({ file: repoRel, acao: 'frontmatter-adicionado', inferencias: inf, sugestaoDestino, nomeForaDaRegra, observacoes: obs });
+    }
+    // _nomes-legados.json — só cria se não existe (a lista só diminui)
+    let legacyNamesFile;
+    const legacyPath = path.join(absDocs, '_nomes-legados.json');
+    if (offRule.length) {
+        if (!fsSync.existsSync(legacyPath)) {
+            if (!dryRun) {
+                await fs.writeFile(legacyPath, JSON.stringify({
+                    protocolVersion: 1,
+                    gerado_em: today,
+                    nota: 'Nomes fora da regra do protocolo, tolerados pelo validador. A lista só diminui: arquivo renomeado ou arquivado sai e não volta.',
+                    arquivos: offRule,
+                }, null, 2) + '\n', 'utf8');
+            }
+            legacyNamesFile = { path: `${docsRoot}/_nomes-legados.json`, created: true, count: offRule.length };
+        }
+        else {
+            legacyNamesFile = { path: `${docsRoot}/_nomes-legados.json`, created: false, count: offRule.length };
+        }
+    }
+    const withApi = productExposesApi(repo);
+    const faltandoPrimeiroDia = ['README.md', 'CHANGELOG.md', `${docsRoot}/index.md`, `${docsRoot}/produto/VISAO_DO_PRODUTO.md`, `${docsRoot}/arquitetura/ARQUITETURA.md`, `${docsRoot}/runbooks/RUNBOOK_DEPLOY.md`, ...(withApi ? [`${docsRoot}/api/API_V1.md`] : [])].filter((p) => !fsSync.existsSync(path.join(repo.cwd, p)));
+    const result = { slug: repo.slug, docsRoot, files: out, legacyNamesFile, configKeysAdded, faltandoPrimeiroDia, dryRun };
+    const reportRel = `${docsRoot}/_audit/MIGRACAO_DOCS_${today}.md`;
+    if (!dryRun && fsSync.existsSync(absDocs)) {
+        const reportAbs = path.join(repo.cwd, reportRel);
+        await fs.mkdir(path.dirname(reportAbs), { recursive: true });
+        await fs.writeFile(reportAbs, renderMigrationReport(repo, result, today), 'utf8');
+        result.reportPath = reportRel;
+    }
+    return result;
+}
+export function renderMigrationReport(repo, r, today) {
+    const fm = serializeFrontmatter({
+        title: `Migração dos docs para o protocolo — ${today}`,
+        description: 'Frontmatter inferido por arquivo, com a origem e a confiança de cada valor, e o que falta decidir à mão.',
+        product: repo.slug,
+        category: 'Documentação',
+        subcategory: 'relatorios-automaticos',
+        type: 'relatorio',
+        status: 'historical',
+        date: today,
+        owner: 'produto',
+        audience: 'dev-produto',
+    });
+    const added = r.files.filter((f) => f.acao === 'frontmatter-adicionado');
+    const lines = [
+        fm,
+        '',
+        `# Migração dos docs para o protocolo — ${today}`,
+        '',
+        '> Gerado por `neetru docs init --migrar`. Nada foi movido nem renomeado, e o texto dos docs não mudou: só entrou frontmatter nos arquivos que não tinham.',
+        '',
+        '## Resumo',
+        '',
+        `- Arquivos analisados: ${r.files.length}`,
+        `- Frontmatter acrescentado: ${added.length}`,
+        `- Já tinham frontmatter (intocados): ${r.files.filter((f) => f.acao === 'ja-tinha-frontmatter').length}`,
+        `- Frontmatter inválido (intocados, corrigir à mão): ${r.files.filter((f) => f.acao === 'frontmatter-invalido').length}`,
+        `- Nomes fora da regra: ${r.files.filter((f) => f.nomeForaDaRegra).length}${r.legacyNamesFile ? ` (${r.legacyNamesFile.created ? 'listados em' : 'o arquivo já existia e não foi alterado:'} ${r.legacyNamesFile.path})` : ''}`,
+        '',
+        '## Achados',
+        '',
+        '### Revisar primeiro (confiança baixa)',
+        '',
+    ];
+    const low = added.flatMap((f) => f.inferencias.filter((i) => i.confianca === 'baixa').map((i) => ({ f, i })));
+    if (!low.length)
+        lines.push('Nenhuma inferência de confiança baixa.', '');
+    else {
+        lines.push('| Arquivo | Campo | Valor | Origem |', '|---|---|---|---|');
+        for (const { f, i } of low)
+            lines.push(`| ${f.file} | ${i.campo} | ${i.valor.replace(/\|/g, '\\|')} | ${i.origem} |`);
+        lines.push('');
+    }
+    lines.push('### Para onde mover (decisão humana)', '');
+    const moves = r.files.filter((f) => f.sugestaoDestino);
+    if (!moves.length)
+        lines.push('Nenhuma mudança de lugar sugerida.', '');
+    else {
+        lines.push('| Hoje | Sugestão pelo protocolo |', '|---|---|');
+        for (const f of moves)
+            lines.push(`| ${f.file} | ${f.sugestaoDestino} |`);
+        lines.push('', 'Ao mover, use `git mv` e corrija os links de entrada (`neetru docs check` acusa os quebrados como LK001). Quem sai do lugar e ganha nome na regra deve sair também do `_nomes-legados.json`.', '');
+    }
+    lines.push('### Todas as inferências', '');
+    for (const f of r.files) {
+        lines.push(`#### ${f.file}`, '');
+        if (f.acao !== 'frontmatter-adicionado') {
+            lines.push(f.acao === 'ja-tinha-frontmatter' ? '- Já tinha frontmatter: não foi alterado.' : '- Frontmatter inválido: não foi alterado.');
+        }
+        for (const i of f.inferencias)
+            lines.push(`- \`${i.campo}\`: ${i.valor} — ${i.origem} (confiança ${i.confianca})`);
+        for (const o of f.observacoes)
+            lines.push(`- Observação: ${o}`);
+        lines.push('');
+    }
+    lines.push('## Recomendações', '');
+    lines.push('1. Revise as inferências de confiança baixa e as descrições (tiradas da primeira frase do texto).');
+    lines.push('2. Mova os arquivos conforme a tabela acima, num PR só de mudança de lugar.');
+    if (r.faltandoPrimeiroDia.length) {
+        lines.push(`3. Depois de mover, complete o mínimo do primeiro dia com \`neetru docs init\` (não sobrescreve nada). Falta hoje: ${r.faltandoPrimeiroDia.join(', ')}.`);
+    }
+    else {
+        lines.push('3. O mínimo do primeiro dia já está presente.');
+    }
+    lines.push('4. Rode `neetru docs check` e corrija os erros antes de abrir o PR.', '');
+    return lines.join('\n');
+}
+// ─── docs new ───────────────────────────────────────────────────────────────
+/** Aliases de `docs new` que trazem os modelos de base do zelo. */
+export const NEW_ALIASES = {
+    rfc: { type: 'plano', variant: 'rfc' },
+    spec: { type: 'plano', variant: 'spec' },
+    politica: { type: 'norma', variant: 'politica' },
+    ameacas: { type: 'referencia', variant: 'ameacas' },
+    'modelo-de-ameacas': { type: 'referencia', variant: 'ameacas' },
+};
+export const NEW_TYPES = ['guia', 'referencia', 'arquitetura', 'adr', 'runbook', 'norma', 'plano', 'relatorio', 'incidente', 'ata'];
+export class DocsNewError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DocsNewError';
+    }
+}
+/** Nome de arquivo pela regra do §6/§8: sem acento, MAIÚSCULAS, prefixo do tipo, data em registro. */
+export function fileNameFor(type, title, opts = {}) {
+    // datas no título não entram no assunto (a data do registro vai no fim do nome)
+    let words = toFileWords(title.replace(/\d{4}-\d{2}(-\d{2})?/g, ' '));
+    let prefix = TYPE_PREFIX[type] ?? '';
+    // Prefixos alternativos aceitos pelo §8.1: o título que já começa com um
+    // deles vira o prefixo ("Auditoria de UX…" → AUDITORIA_UX_…, "Protocolo de…"
+    // → PROTOCOLO_…). Os demais só não se repetem ("Guia de X" → GUIA_X).
+    const altPrefixes = {
+        GUIA: ['GUIA'], RUNBOOK: ['RUNBOOK', 'SETUP'], ARQUITETURA: ['ARQUITETURA'], POLITICA: ['POLITICA', 'PROTOCOLO'],
+        PLANO: ['PLANO'], RELATORIO: ['RELATORIO', 'AUDITORIA', 'REVIEW', 'ANALISE', 'INVENTARIO', 'ACHADO', 'BACKLOG'],
+        INCIDENTE: ['INCIDENTE'], ATA: ['ATA', 'DECISOES'], ADR: ['ADR'],
+    };
+    const alts = altPrefixes[prefix] ?? [];
+    if (words.length > 1 && alts.includes(words[0])) {
+        if (prefix !== 'ADR')
+            prefix = words[0];
+        words = words.slice(1);
+        while (words.length > 1 && STOPWORDS.has(words[0]))
+            words = words.slice(1);
+    }
+    else if (words.length > 1 && prefix === 'POLITICA' && words[0] === 'NORMA') {
+        words = words.slice(1);
+        while (words.length > 1 && STOPWORDS.has(words[0]))
+            words = words.slice(1);
+    }
+    if (words.length > 6) {
+        const noStop = words.filter((w) => !STOPWORDS.has(w));
+        words = (noStop.length ? noStop : words).slice(0, 6);
+    }
+    if (!words.length)
+        words = ['DOC'];
+    if (/^\d/.test(words[0]) && !prefix)
+        words = ['DOC', ...words];
+    const subject = words.join('_');
+    if (type === 'adr')
+        return `ADR-${String(opts.adrNumber ?? 1).padStart(4, '0')}_${subject}.md`;
+    const head = prefix ? `${prefix}_${subject}` : subject;
+    const fam = EMBEDDED_TAXONOMY.types[type];
+    return fam === 'registro' ? `${head}_${opts.date}.md` : `${head}.md`;
+}
+function nextAdrNumber(absDecisoes) {
+    let max = 0;
+    try {
+        for (const f of fsSync.readdirSync(absDecisoes)) {
+            const m = f.match(/^ADR-(\d{4})_/i);
+            if (m)
+                max = Math.max(max, Number.parseInt(m[1], 10));
+        }
+    }
+    catch {
+        /* pasta não existe */
+    }
+    return max + 1;
+}
+/** `neetru docs new <tipo> "<título>"`. Lança `DocsNewError` com mensagem PT-BR. */
+export async function createProductDoc(repo, tipo, titulo, opts = {}) {
+    const taxonomy = opts.taxonomy ?? EMBEDDED_TAXONOMY;
+    const cats = productCategories(taxonomy);
+    const today = opts.today ?? todayIso();
+    const key = tipo.trim().toLowerCase();
+    const alias = NEW_ALIASES[key];
+    const type = alias?.type ?? key;
+    if (!NEW_TYPES.includes(type)) {
+        throw new DocsNewError('invalid_type', `Tipo "${tipo}" não é criado por \`docs new\`. Use: ${NEW_TYPES.join(', ')} — ou os modelos ${Object.keys(NEW_ALIASES).filter((k) => k !== 'modelo-de-ameacas').join(', ')}.`);
+    }
+    const cleanTitle = titulo.trim().replace(/\s+/g, ' ').replace(/\.$/, '');
+    if (cleanTitle.length < 3)
+        throw new DocsNewError('invalid_title', 'Título vazio ou curto demais.');
+    const recordDate = opts.data ?? today;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(recordDate))
+        throw new DocsNewError('invalid_date', `--data "${opts.data}" fora do formato AAAA-MM-DD.`);
+    // categoria
+    if (opts.categoria && taxonomy.coreOnlyCategories.includes(opts.categoria)) {
+        throw new DocsNewError('core_only_category', `A categoria "${opts.categoria}" só existe no Core (PR003).`);
+    }
+    if (opts.categoria && !cats[opts.categoria]) {
+        throw new DocsNewError('invalid_category', `Categoria "${opts.categoria}" fora da lista: ${Object.keys(cats).join(', ')}.`);
+    }
+    // pasta
+    let folder = TYPE_DEFAULT_FOLDER[type];
+    if (alias?.variant === 'ameacas' || alias?.variant === 'politica')
+        folder = 'seguranca';
+    const catFolder = opts.categoria ? CATEGORY_FOLDER[opts.categoria] : undefined;
+    if (catFolder) {
+        const r = FOLDER_RULES.find((x) => x.folder === catFolder);
+        if (r && r.types !== 'qualquer' && r.types.includes(type))
+            folder = catFolder;
+    }
+    const rule = FOLDER_RULES.find((x) => x.folder === folder);
+    let categoria = opts.categoria ?? rule.category;
+    let subcategoria = opts.subcategoria;
+    let categoriaPadrao = !opts.categoria;
+    if (alias?.variant === 'ameacas' && !opts.categoria) {
+        categoria = 'Segurança';
+        subcategoria = subcategoria ?? 'vulnerabilidades';
+    }
+    if (!subcategoria)
+        subcategoria = categoria === rule.category ? rule.subcategory : cats[categoria][0];
+    if (!cats[categoria]?.includes(subcategoria)) {
+        throw new DocsNewError('invalid_subcategory', `Subcategoria "${subcategoria}" não pertence a "${categoria}". Aceitas: ${cats[categoria].join(', ')}.`);
+    }
+    if (opts.subcategoria || alias?.variant === 'ameacas')
+        categoriaPadrao = false;
+    const audience = opts.audience ?? rule.audience;
+    if (!taxonomy.audiences.includes(audience)) {
+        throw new DocsNewError('invalid_audience', `--audience "${audience}" fora da lista: ${taxonomy.audiences.join(', ')}.`);
+    }
+    const family = taxonomy.types[type];
+    const absDocs = path.join(repo.cwd, repo.docs.root);
+    let adrNumber;
+    let finalTitle = cleanTitle;
+    if (type === 'adr') {
+        adrNumber = nextAdrNumber(path.join(absDocs, 'decisoes'));
+        finalTitle = `ADR-${String(adrNumber).padStart(4, '0')} — ${cleanTitle.replace(/^ADR[-\s]?\d*\s*[—:-]?\s*/i, '')}`;
+    }
+    else if (family === 'registro' && !/\d{4}-\d{2}(-\d{2})?$/.test(cleanTitle)) {
+        finalTitle = `${cleanTitle} — ${recordDate}`;
+    }
+    const name = fileNameFor(type, cleanTitle.replace(/\s+—\s+\d{4}-\d{2}(-\d{2})?$/, ''), { date: recordDate, adrNumber });
+    const rel = `${folder}/${name}`;
+    const abs = path.join(absDocs, rel);
+    if (fsSync.existsSync(abs)) {
+        throw new DocsNewError('exists', `${repo.docs.root}/${rel} já existe — \`docs new\` nunca sobrescreve. Escolha outro título.`);
+    }
+    const status = type === 'adr' ? 'proposed' : 'draft';
+    let sections = TYPE_MODELS[type] ?? [];
+    let extra;
+    if (type === 'adr')
+        extra = ADR_EXTRA;
+    if (alias?.variant === 'rfc')
+        extra = PLANO_RFC_EXTRA;
+    if (alias?.variant === 'spec' || (type === 'plano' && !alias))
+        extra = PLANO_SPEC_EXTRA;
+    if (alias?.variant === 'politica')
+        extra = NORMA_POLITICA_EXTRA;
+    if (alias?.variant === 'ameacas') {
+        sections = THREAT_MODEL_SECTIONS;
+        extra = THREAT_EXTRA;
+    }
+    const description = opts.descricao?.trim() || 'Escreva aqui, em uma frase de 40 a 200 caracteres, o que este doc é e quando consultá-lo.';
+    const content = renderDoc({
+        title: finalTitle,
+        description,
+        product: repo.slug,
+        category: categoria,
+        subcategory: subcategoria,
+        type,
+        status,
+        date: family === 'registro' ? recordDate : today,
+        updated: family === 'vivo' ? today : undefined,
+        audience,
+        adr: adrNumber,
+        lead: audience === 'publico' ? 'Para quem usa o produto.' : 'Para a equipe do produto. Rascunho.',
+        sections,
+        extra,
+    });
+    if (!opts.dryRun) {
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        await fs.writeFile(abs, content, { encoding: 'utf8', flag: 'wx' });
+    }
+    return {
+        path: `${repo.docs.root}/${rel}`,
+        type,
+        title: finalTitle,
+        category: categoria,
+        subcategory: subcategoria,
+        audience,
+        status,
+        categoriaPadrao,
+        dryRun: !!opts.dryRun,
+        content,
+    };
+}
+//# sourceMappingURL=ops.js.map