# PRD: Preparar o repositório arandu para open-source

> Generated via /vibeflow:discover on 2026-03-18

## Problem

O arandu (long-term memory para AI agents) é um projeto funcional com ~40 arquivos de código, 23 suítes de teste e documentação bilíngue (EN/PT-BR), mas o repositório não tem a infraestrutura que desenvolvedores open-source sérios esperam. Faltam sinais básicos de maturidade: CI rodando testes, arquivo de licença, guia de contribuição, templates de issues/PRs, e o README contém links quebrados referenciando um nome antigo ("personal-genius") e paths que não existem ("packages/memory-sdk"). Além disso, o pacote ainda não foi publicado no PyPI.

Quem chega no GitHub hoje vê um projeto sem CI, sem licença-arquivo, com links 404 no README — e descarta. O objetivo é que um dev experiente bata o olho e pense "projeto bem mantido, posso confiar e contribuir".

## Target Audience

Desenvolvedores Python que trabalham com AI/LLM agents e buscam uma solução de memória de longo prazo. Perfil: engenheiros de software que avaliam qualidade de OSS antes de adotar — olham CI, licença, contribuição, e atividade do projeto.

## Proposed Solution

Adicionar toda a infraestrutura padrão de um projeto open-source profissional e publicar o pacote no PyPI:

- **README corrigido** — links reais, URLs corretas, path de setup correto
- **Arquivo LICENSE** (MIT)
- **CONTRIBUTING.md** — setup de dev, como rodar testes, padrão de PRs
- **CODE_OF_CONDUCT.md** — Contributor Covenant
- **SECURITY.md** — política de reporte de vulnerabilidades
- **CI completo** — GitHub Actions com pytest + ruff + mypy
- **Issue templates e PR template** — bug report, feature request, PR checklist
- **pyproject.toml completo** — URLs (homepage, repo, issues), email do autor
- **Publicação no PyPI** — workflow de CD com Trusted Publishers (OIDC)

## Success Criteria

1. Um dev clona o repo, roda `pip install -e ".[dev]"` e `pytest` — funciona sem fricção
2. O README não tem nenhum link quebrado e mostra badges reais (CI, PyPI, license)
3. CI roda em todo push/PR: testes passam, lint passa, type check passa
4. `pip install arandu` funciona via PyPI
5. Existe guia claro de como contribuir (CONTRIBUTING.md)
6. Issue templates aparecem ao criar nova issue no GitHub

## Scope v0

- [ ] Corrigir README.md (links, badges, paths, URL real do GitHub Pages)
- [ ] Criar arquivo `LICENSE` (MIT, autor Pedro Menezes)
- [ ] Criar `CONTRIBUTING.md` (setup, testes, lint, PR guidelines)
- [ ] Criar `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1)
- [ ] Criar `SECURITY.md` (política de vulnerabilidades)
- [ ] Criar `.github/workflows/ci.yml` (pytest + ruff + mypy)
- [ ] Criar `.github/workflows/publish.yml` (PyPI via Trusted Publishers)
- [ ] Criar `.github/ISSUE_TEMPLATE/bug_report.yml`
- [ ] Criar `.github/ISSUE_TEMPLATE/feature_request.yml`
- [ ] Criar `.github/PULL_REQUEST_TEMPLATE.md`
- [ ] Atualizar `pyproject.toml` (urls, email, classifiers)

## Anti-scope

- **CHANGELOG.md** — usar GitHub Releases por agora
- **Bot de stale issues** — overhead desnecessário pra v0.1.0
- **GitHub Discussions** — pode ativar depois se houver comunidade
- **Pre-commit hooks** — CI já cobre lint/format
- **Docker / docker-compose** — testes rodam com mock, não precisa de Postgres no CI
- **Badges de cobertura (codecov)** — pode adicionar depois
- **Configuração de branch protection rules** — é manual no GitHub, fora do repo
- **Tradução dos arquivos de OSS** — CONTRIBUTING/CODE_OF_CONDUCT ficam em inglês (padrão)
- **Reestruturação de código** — foco é infraestrutura, não refactoring

## Technical Context

- **Stack:** Python 3.11+, hatchling (build), SQLAlchemy, pgvector, pydantic
- **Testes:** Todos com mock (FakeLLMProvider, FakeEmbeddingProvider) — não precisam de Postgres no CI
- **Lint/format:** ruff já configurado no pyproject.toml
- **Type check:** mypy strict já configurado no pyproject.toml
- **Docs:** MkDocs Material, bilíngue, deploy via GitHub Actions (já funciona)
- **GitHub:** repo `pe-menezes/arandu`, Pages em `pe-menezes.github.io/arandu/`
- **PyPI:** conta `pe-menezes`, Trusted Publisher configurado (arandu → pe-menezes/arandu, workflow publish.yml, environment pypi)
- **Email do autor:** pedromenezesrs@gmail.com

## Open Questions

Nenhuma questão aberta. Todas as dependências externas foram resolvidas.
