docs: adiciona índice central de documentação

[enioxt]

Motivation
Melhorar a descoberta da documentação do projeto com um ponto de entrada único em docs/.

Registrar de forma explícita a decisão técnica sobre stack para escala (Python vs Go vs Node.js), evitando migração prematura sem evidência de gargalo real.

Consolidar riscos e mitigação operacional para consumo de APIs externas e custo de LLM no MVP.

What changed
Novo índice de documentação em docs/README.md com navegação por domínio:

governança/operação,

dados e ETL,

release pública,

compliance/jurídico,

documentação PT-BR,

relatórios e análises.

Novo documento técnico docs/analysis/STACK_SCALING_DECISION_2026-03.md com:

recomendação de manter Python no core (API + ETL),

manutenção de Node.js para bots/eventos/frontend,

critérios objetivos para extração pontual de hotspots para Go,

inventário de integrações/APIs em uso,

limites atuais observáveis (rate limits, throttle de DataJud, retries/backoff),

riscos (overload/compliance/custo de LLM) e plano de mitigação,

roadmap operacional em 90 dias.

README raiz atualizado com links diretos para:

docs/README.md,

docs/analysis/STACK_SCALING_DECISION_2026-03.md.

Engineering decision captured by this PR
Não migrar o core para Go/Node agora.

Escalar primeiro por arquitetura e governança operacional:

orçamento por fonte (QPS/limite diário),

filas + workers assíncronos,

circuit breaker por provedor,

consumo incremental/delta,

budget e fallback para LLM.

Só considerar Go para componentes isolados após benchmark e evidência (p95/p99 fora de meta mesmo após otimizações de cache/query/fila).

Why this matters
Evita reescrita custosa sem atacar gargalo real.

Reduz risco de sobrecarga indevida em APIs governamentais.

Dá previsibilidade de custo para LLMs no MVP.

Melhora onboarding e manutenção contínua da documentação.

Scope / impact
Mudança 100% documental.

Sem alteração de código de runtime.

Testing / validation
Verificação de consistência dos links adicionados no README raiz e no índice de docs.

Validação do conteúdo da análise de stack e presença das seções de limites, riscos, mitigação e roadmap.

Summary by CodeRabbit

• Documentation
  • Updated README with additional documentation navigation links
  • Added comprehensive documentation index organizing governance, data/ETL, compliance, and technical guides for improved discoverability
  • Added new analysis and planning documents detailing strategic and architectural decisions

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 02e601b and e69a7ca.

📒 Files selected for processing (7)

• README.md
• docs/README.md
• docs/analysis/MYCELIUM_AUDIT_TRAIL_2026-03.md
• docs/analysis/STACK_SCALING_DECISION_2026-03.md
• etl/src/bracc_etl/base.py
• etl/src/bracc_etl/provenance.py
• etl/tests/test_provenance.py

---

📝 Walkthrough

Walkthrough

This PR introduces a Mycelium Audit Trail system for provenance tracking and documentation scaffolding. It adds a new provenance module with deterministic hashing and audit field generation, extends the Pipeline base class with an audit field builder method, includes comprehensive design documentation for audit trail architecture and stack scaling decisions, and provides unit tests for the provenance utilities.

Changes

Cohort / File(s)	Summary
Documentation Index & Governance README.md, docs/README.md	Adds documentation structure with index links to governance, data/ETL, reports, and analysis assets.
Architecture & Design Plans docs/analysis/STACK_SCALING_DECISION_2026-03.md, docs/analysis/MYCELIUM_AUDIT_TRAIL_2026-03.md	New design documents outlining stack scaling strategy (Python/Go/Node.js rationale) and audit trail evolution plan with per-record metadata fields and legacy migration approach.
Provenance & Audit Implementation etl/src/bracc_etl/provenance.py, etl/src/bracc_etl/base.py	Introduces provenance module with deterministic hashing (SHA-256), row canonicalization, source fingerprinting, and audit field building; Pipeline class gains build_audit_fields() delegation method.
Provenance Tests etl/tests/test_provenance.py	Unit tests validating hash stability, audit field contents, and verified_at timestamp derivation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Hop hop, audit trails now bloom,
From raw rows hashed through provenance rooms,
Stack decisions documented with care,
Deterministic fingerprints floating in air! ✨

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/create-documentation-pr-from-files

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

AI PR Governor bloqueou esta PR no preflight.\n\n- decision: blocked_draft_pr\n- reasons: ["blocked_draft_pr","blocked_prompt_injection_signal"]\n\nNenhum merge automático será feito neste ciclo.

[github-actions]

AI PR Governor bloqueou esta PR no preflight.\n\n- decision: blocked_draft_pr\n- reasons: ["blocked_draft_pr","blocked_prompt_injection_signal"]\n\nNenhum merge automático será feito neste ciclo.

[github-actions]

AI PR Governor bloqueou esta PR no preflight.\n\n- decision: blocked_draft_pr\n- reasons: ["blocked_draft_pr","blocked_prompt_injection_signal"]\n\nNenhum merge automático será feito neste ciclo.

[github-actions]

AI PR Governor bloqueou esta PR no preflight.\n\n- decision: blocked_draft_pr\n- reasons: ["blocked_draft_pr","blocked_prompt_injection_signal","blocked_outside_low_risk_allowlist"]\n\nNenhum merge automático será feito neste ciclo.

[github-actions]

AI PR Governor bloqueou esta PR no preflight.\n\n- decision: blocked_prompt_injection_signal\n- reasons: ["blocked_prompt_injection_signal","blocked_outside_low_risk_allowlist"]\n\nNenhum merge automático será feito neste ciclo.