OmniRoute/docs/ops/DOCUMENTATION_AUDIT_REPORT.md

title, version, lastUpdated

title	version	lastUpdated
Documentation Audit & Sync Report	3.8.24	2026-06-13

OmniRoute — Relatório de Auditoria de Documentação & Plano de Sincronização

Versão do projeto: 3.8.24 · Data: 2026-06-13 · Status: FASE 1 (pesquisa/organização) — execução pendente de confirmação Escopo: docs raiz · /docs · site :20128/docs (Fumadocs) · Wiki GitHub · i18n (42 locales) · CI de docs/i18n

---

0. TL;DR

1. As contagens estão dessincronizadas entre 5 fontes diferentes (código, README, AGENTS.md, site, Wiki). O caso mais grave: providers aparece como 177 (README) / 232 (AGENTS) / 223 (gerador, correto) / 212+ (Wiki) / 160+ (CLAUDE.md).
2. Os gates de CI atuais NÃO validam os números mais visíveis (provider count, free count, test count, locale count). Por isso o drift passou despercebido.
3. A Wiki do GitHub está órfã: 995 páginas, sem automação de sync, último update genérico, números muito antigos (14 strategies, 37 MCP tools, 212+ providers).
4. O pipeline i18n nunca rodou para os docs: .i18n-state.json não existe → drift check não tem baseline.
5. ~10–12 funcionalidades recentes não têm documentação (Plugin Marketplace, Free Provider Rankings/Arena ELO, IPv6 egress, Feature Flags, Notion/Obsidian context, etc.).

---

1. Números canônicos REAIS (a fonte de verdade de cada um)

Métrica	Valor real	Fonte de verdade (como medir)	README	AGENTS.md	CLAUDE.md	docs/README.md	Wiki Home	Site
Providers (total)	223	scripts/docs/gen-provider-reference.ts → PROVIDER_REFERENCE.md ("unique IDs")	❌ 177	❌ 232	❌ "160+"	(n/a)	❌ 212+	via gerador
Providers c/ free tier	103 hasFree:true / 98 pesquisados c/ quota	grep hasFree:true providers.ts / FREE_TIERS.md	⚠️ "50+"	—	—	—	⚠️ "50+"	—
Free forever	11 (a revalidar)	README claim — sem fonte programática	"11"	—	—	—	—	—
Test files (unit)	1.574	find tests/unit -name '*.test.ts'	—	—	—	—	—	—
Test files (integration)	76	find tests/integration	—	—	—	—	—	—
Test files (total)	~1.660 (+46 em src/open-sse)	find global	—	—	—	—	—	—
Test cases (aprox)	~16.000	`grep -E '(test	it)(' tests/`	—	—	—	—	—	—
unit/ test files (CONTRIBUTING)	1.574	—	—	—	—	❌ CONTRIBUTING diz 122	—	—
API endpoints (route.ts)	502	find src/app/api -name route.ts	—	—	—	—	—	—
Endpoints /v1 (OpenAI-compat)	75	find src/app/api/v1 -name route.ts	—	—	—	—	—	—
MCP tools	87 (33 base + módulos)	schemas/tools.ts = 33 base; +memory/skill/notion/obsidian/gamification/plugin	✅ 87	✅ 87	✅ 87	—	❌ 37	—
MCP scopes	30 (16 base em tools.ts)	scopeEnforcement.ts + módulos	—	✅ 30	✅ 30	—	—	—
Routing strategies	15	open-sse/services/combo.ts (gate valida)	✅ 15	✅ 15	✅ 15	❌ 14	❌ 14	—
Auto-combo scoring factors	9 (label) / engine multifator	AUTO-COMBO.md	"9"	"12"	"9-factor"	❌ "9-factor"	—	—
i18n locales	42 (+en = 43)	config/i18n.json	—	✅ 42	—	❌ 40	❌ "40+"	✅ 40 (LANGUAGES)
Executors	60	gate valida ✓	—	✅	—	—	—	—
A2A skills	6	gate valida ✓	✅	✅	✅	—	—	—
Cloud agents	3	gate valida ✓	✅	—	—	—	—	—
OAuth flows / providers	16 flows / 19 providers OAuth	gate (16) vs PROVIDER_REFERENCE (19)	—	—	—	—	—	—
DB modules / migrations	83 / 97	gate/CLAUDE ✓	—	✅	✅	—	—	—

⚠️ Inconsistências de número que precisam de decisão de produto (não só correção mecânica):

• Free count: hasFree:true = 103, mas inclui créditos-de-cadastro one-time. FREE_TIERS.md documenta 98 pesquisados (≈63 recorrentes, 29 signup-only, 6 descontinuados). O "50+/11 forever" é conservador e defensável — decidir o headline canônico.
• Auto-combo "9-factor" vs "12": README diz 9, AGENTS diz 12. Precisa alinhar à contagem real em AUTO-COMBO.md.

---

2. Defasagens por fonte de documentação

2.1 Documentos da raiz

Arquivo	Problema	Ação
README.md	177 providers em ~9 lugares (linhas 9, 22, 23, 62, 139, 143, 266, 322, 326, 736) + badges + âncora #-177-ai-providers--50-free	Corrigir para 223; revisar badge/âncora; revalidar "50+/11 forever"
AGENTS.md	232 provider entries (linha 6) + live counts providers 232 (linha 11)	Corrigir para 223
CLAUDE.md	"160+" providers (linha ~40)	Corrigir para 223
CONTRIBUTING.md	unit/ (122 test files) (linha 255) — defasado em >1.400	Corrigir para 1.574 (ou texto dinâmico)
CHANGELOG.md	OK (v3.8.24 correto)	—
SECURITY.md / CODE_OF_CONDUCT.md / GEMINI.md	Genéricos, OK	—

2.2 /docs

Arquivo	Problema
docs/README.md (índice)	9-factor scoring, 14 strategies (linha 81 → deveria ser 15); 40 locales (linha 121 → 42)
docs/guides/I18N.md	"supports 30 languages" (real: 42); lastUpdated 2026-05-13
docs/frameworks/AGENT-SKILLS.md, AGENTBRIDGE.md	lastUpdated 2026-05-28 (v3.8.6)
docs/frameworks/WEBHOOKS.md, docs/guides/PWA_GUIDE.md	lastUpdated 2026-05-13 (v3.8.0)
docs/frameworks/SEARCH_TOOLS_STUDIO.md, PLAYGROUND_STUDIO.md	lastUpdated 2026-05-30
docs/guides/TROUBLESHOOTING.md, FEATURES.md, UNINSTALL.md, docs/reference/API_REFERENCE.md	refs a versões antigas (v3.5.x–v3.7.x) — verificar se históricas (ok) ou stale
Órfãos do site (existem em /docs mas fora do meta.json)	routing/QUOTA_SHARE.md, guides/CODEX-CLI-CONFIGURATION.md, security/SOCKET_DEV_FINDINGS.md, compression/EXTENDING_COMPRESSION.md — acessíveis por URL mas não na sidebar
Raiz /docs nunca no site	AGENTROUTER.md, PROVIDERS.md, DOCUMENTATION_OVERHAUL_PLAN.md, SUBMIT_PR.md, fix-opencode-context.md

2.3 Site :20128/docs (Fumadocs)

• Como funciona: docs/<seção>/*.md → source.config.ts (globs) → .source/server.ts (gerado) → src/lib/source.ts → src/app/docs/layout.tsx (sidebar = pageTree dos meta.json) → [...slug]/page.tsx. 60 docs em inglês entram no site.
• Navegação curada por meta.json → arquivo novo em /docs não aparece até ser adicionado manualmente ao meta.json da seção. Hoje há 4 arquivos importados mas fora da sidebar (acima).
• i18n no site: [...slug]/page.tsx lê cookie NEXT_LOCALE; se ≠ en, tenta docs/i18n/<locale>/docs/<seção>/<FILE>.md via marked.parse(), com fallback para o MDX inglês. Seletor: LanguageSelector.tsx (40 idiomas em LANGUAGES).
• API Explorer: openapi.generated.ts é gerado por scripts/docs/gen-openapi-module.mjs a partir de docs/reference/openapi.yaml no prebuild:docs.
• Riscos de drift: (a) meta.json manual; (b) traduções não atualizam quando o inglês muda; (c) openapi.yaml precisa de regen; (d) LANGUAGES no app diz 40, config diz 42 → divergência app vs config.

2.4 Wiki do GitHub (/wiki) — mais defasada de todas

• 995 páginas (60 docs Title-Case + 935 i18n), Home.md, _Sidebar.md, _Footer.md.
• Sem nenhum script/automação de sync no repo (grep wiki em scripts/, .github/, package.json = vazio). Foi populada uma vez, manualmente.
• Números muito antigos no Home.md: 212+ providers, 14 Routing Strategies, MCP Server 37 tools, 40+ Languages.
• Conclusão: a Wiki não tem "fonte de verdade" — precisa virar espelho automatizado de /docs (ver Plano §6, Fase 4).

2.5 i18n (42 locales)

• Fonte de verdade dos locales: config/i18n.json → 42 (+en=43). Documentação diz 30 (I18N.md) e 40 (docs/README.md, LANGUAGES no app) — 3 números diferentes.
• Subset espelhado por idioma: ~26–27 arquivos (7 raiz: README/CONTRIBUTING/CLAUDE/GEMINI/AGENTS/SECURITY/CODE_OF_CONDUCT + llm.txt/CHANGELOG copiados + ~19 docs em architecture/frameworks/guides/ops/reference/routing).
• .i18n-state.json não existe → i18n:check (drift) não tem baseline; tradução de docs nunca foi executada pelo pipeline novo.
• Duplicações/legados: pt vs pt-BR (ambos traduzem os mesmos arquivos); id vs in (Indonésio — in é legado ISO 639-3, deveria deprecar).
• CLI locales incompletos: bn, gu, he, mr, ms, phi, in = 3 bytes (vazios).
• Motor: run-translation.mjs usa endpoint OpenAI-compat via env OMNIROUTE_TRANSLATION_* (LLM); scripts Python (i18n_autotranslate.py, generate-multilang.mjs) marcados deprecated.

---

3. Gaps de funcionalidades (features sem doc) — com curadoria

Curadoria aplicada: o agente de exploração marcou 57% dos módulos como "não documentados", mas muitos (config, runtime, middleware, images, catalog, system, display, events, embeddings) são internos e não merecem doc dedicado. Lista abaixo filtrada para o que é voltado ao usuário/operador.

P0 — features novas visíveis ao usuário, sem doc

Feature	Onde no código	PR	Doc sugerido
Plugin Marketplace (customizável + SSRF hardening)	src/app/api/plugins/marketplace/	#3656, #3774	docs/frameworks/PLUGIN_MARKETPLACE.md
Free Provider Rankings (Arena ELO)	src/app/api/free-provider-rankings/, /dashboard/free-provider-rankings	#3799	docs/guides/FREE_PROVIDER_RANKINGS.md
IPv6 egress family selector (auto/ipv4/ipv6)	proxy/egress + UI form	#3777	docs/security/EGRESS_POLICY.md (ou seção em PROXY_GUIDE)
Feature Flags page (runtime + emergency fallback)	/dashboard feature-flags	#3752, #3741	docs/reference/FEATURE_FLAGS.md

P1 — integrações/frameworks sem doc

Feature	Onde	Doc sugerido
Notion context source	src/lib/notion/ (+6 MCP tools)	docs/frameworks/NOTION_CONTEXT.md
Obsidian context source	src/lib/obsidian/ (+22 MCP tools)	docs/frameworks/OBSIDIAN_CONTEXT.md
Quota-shared routing audit (#3779)	combo + quota	seção em AUTO-COMBO.md
Model lockout / success-decay	RESILIENCE_GUIDE.md desatualizado	atualizar RESILIENCE_GUIDE.md
Cost/Spend tracking	/dashboard/costs	docs/guides/COST_TRACKING.md

P2 — sub-documentados

Traffic Inspector, Search Tools Studio (raso), Prompt Caching, Credential Health, Background Jobs, Database Migrations guide.

Validação obrigatória na execução: cada item acima será confirmado no código (trust-but-verify) antes de escrever doc — não documentar feature que não exista/esteja como descrita.

---

4. CI de docs/i18n — coberto vs lacunas

Coberto (hard gates)

check:docs-sync (version package↔openapi↔CHANGELOG + mirrors i18n) · check:env-doc-sync (env code↔.env.example↔ENVIRONMENT.md) · check:docs-symbols (anti-alucinação rota) · check:openapi-routes · check:cli-i18n · check-ui-keys-coverage (floor 65%).

Parcial / advisory

check:docs-counts (soft, não no CI principal — e não cobre providers/free/tests/locales) · check:doc-links (só internos) · check:fabricated-docs (soft) · check-translation-drift (--warn, não bloqueia) · validate_translation.py (matrix continue-on-error).

Lacunas (sem gate algum)

1. Provider count / free count / test count / locale count — os números mais visíveis não são validados. → causa-raiz de todo o drift atual.
2. Validação MDX/Fumadocs — quebra de sintaxe só aparece no deploy.
3. Lint de prosa (Vale/markdownlint) — sem checagem de estilo/ortografia.
4. Links externos — check:doc-links ignora http(s); URLs mortas passam.
5. Imagens/screenshots/diagramas órfãos.
6. Drift de tradução não é blocking.
7. meta.json ↔ /docs — arquivo novo fora da sidebar não é detectado.
8. Wiki sync — inexistente.
9. config/i18n.json (42) vs LANGUAGES app (40) — sem gate de consistência.

---

5. Boas práticas 2026 (pesquisa web) aplicáveis

Prática	Ferramenta	Aplicação no OmniRoute
Lint de prosa em CI	Vale (Google/Microsoft style) + markdownlint	Novo job docs-lint (warning-first p/ não travar)
Severidade graduada	error = link quebrado / code-fence / alt-text faltando; warning = voz passiva / estilo	Configurar .vale.ini + .markdownlint.json
Feedback local rápido	pre-commit com markdownlint/Vale (<2s)	Adicionar ao husky lint-staged p/ *.md
Accept-list de vocabulário	Vale accept.txt	Evitar ruído com termos do projeto (OmniRoute, combo, etc.)
Link checker robusto	lychee (Rust, externos + internos, cache)	Job semanal/cron + flag opcional no doc-links
Wiki como espelho automatizado	Andrew-Chen-Wang/github-wiki-action ou wiki-sync	Workflow que espelha /docs → .wiki.git em push to main
Tradução LLM roteada por tarefa	docs técnicos → GPT-5.x; nuance → Claude; bulk → modelo barato	Já temos roteamento próprio — usar cx/gpt-5.4-mini p/ docs (config existente)
Translation memory + glossário	reduz drift e protege termos	Adotar glossário/accept-list compartilhado UI+docs
TMS via MCP	Crowdin/Lokalise/Tolgee/SimpleLocalize têm MCP oficial	Opcional futuro; hoje pipeline próprio já cobre
Gerar docs no CI	docs sempre refletem o código	Elevar gerador de provider/openapi + count-guard a gate

Fontes: Fern — Docs Linting Guide (jan/2026) · Netlify — Docs Linting in CI/CD · GitLab Docs — Documentation testing · Lokalise — Best LLM for translation 2026 · Crowdin — AI Localization 2026 · Andrew-Chen-Wang/github-wiki-action · OneUptime — Generate Docs with GitHub Actions

---

6. PLANO DE MELHORIAS & SINCRONIZAÇÃO (execução pós-confirmação)

Fase A — Números canônicos (correção mecânica de alto impacto)

1. Regenerar PROVIDER_REFERENCE.md (gen-provider-reference.ts) e fixar 223 como fonte.
2. Corrigir providers em: README (9 ocorrências + badge + âncora), AGENTS.md, CLAUDE.md, Wiki Home → 223.
3. Corrigir tests em CONTRIBUTING.md (122 → 1.574) — ou tornar texto dinâmico.
4. Corrigir strategies (14 → 15) e locales (30/40 → 42) em docs/README.md, I18N.md, Wiki Home, e LANGUAGES do app.
5. Corrigir MCP tools na Wiki (37 → 87) e alinhar auto-combo factors (9 vs 12 → valor real).
6. Decidir headline free (50+/11 vs 98/103) e aplicar uniformemente.

Fase B — Sincronizar /docs + README (estrutural)

7. Atualizar lastUpdated/versão dos docs defasados (AGENT-SKILLS, WEBHOOKS, PWA, I18N, SEARCH/PLAYGROUND_STUDIO).
8. Adicionar os 4 arquivos órfãos ao meta.json (ou removê-los conscientemente).
9. Avaliar README: adicionar/atualizar seções (Quick Start, tabela de números, links p/ novos docs).

Fase C — Novos documentos (gaps de features, P0→P1)

10. Criar P0: PLUGIN_MARKETPLACE, FREE_PROVIDER_RANKINGS, EGRESS_POLICY, FEATURE_FLAGS.
11. Atualizar RESILIENCE_GUIDE (model lockout) e AUTO-COMBO (quota-shared).
12. Criar P1: NOTION_CONTEXT, OBSIDIAN_CONTEXT, COST_TRACKING (conforme confirmação).

Fase D — i18n

13. Bootstrapar .i18n-state.json (i18n:run --dry-run) e rodar tradução dos docs corrigidos.
14. Reconciliar config/i18n.json (42) ↔ LANGUAGES app (40); decidir sobre in (deprecar) e pt/pt-BR.
15. Atualizar I18N.md com o processo real e contagem 42.

Fase E — Site :20128/docs

16. Regenerar openapi.generated.ts e validar API Explorer.
17. Garantir que os novos docs entram no meta.json e renderizam (verificação visual via browser).

Fase F — Wiki GitHub (automatizar)

18. Criar workflow wiki-sync.yml espelhando /docs → .wiki.git (github-wiki-action) — fim do drift manual.
19. Re-sincronizar a Wiki com os números corrigidos.

Fase G — CI de docs (fechar lacunas)

20. Adicionar count-guard a check:docs-counts: providers, free, tests, locales, MCP tools/scopes → gate blocking (matando a causa-raiz).
21. Promover check-translation-drift a blocking (--strict) após baseline.
22. Adicionar job advisory docs-lint (Vale + markdownlint) e link-check externo (lychee, cron).
23. Adicionar gate de consistência config/i18n.json ↔ LANGUAGES.

---

7. Decisões necessárias do usuário (antes de executar)

1. Headline de "free": manter 50+ / 11 forever ou adotar número pesquisado (98 documentados)?
2. Escopo dos novos docs: criar todos P0+P1 agora, ou só P0 nesta rodada?
3. Wiki: automatizar via workflow (recomendado) ou só re-sincronizar manualmente desta vez?
4. i18n: re-traduzir os docs alterados agora (custa chamadas LLM) ou só corrigir o inglês e deixar i18n para um passo seguinte?
5. in/pt legados: deprecar in (Indonésio legado) nesta rodada?
6. CI: implementar os novos gates (count-guard, Vale, wiki-sync) nesta rodada ou em PR separado?

---

Relatório gerado na Fase 1 (pesquisa). Nenhum documento de produto foi alterado ainda. A sincronização começa após confirmação do escopo acima.