Skip to content
2 min read · 476 words

Contributing

Contributions are welcome — code, docs, and bug reports alike. The bar is simple: match the house patterns, keep the contracts, update the docs.

Setup

Fork/clone, then follow Installation. Verify your environment with the Quick Start sequence before changing anything — it's also the manual regression test you'll run after.

What we expect in a change

  1. The five contracts hold — observability logging, tool gating, migration entries, the frontend proxy pattern, design tokens (the list).
  2. Style matches the file you're in — Coding Standards; there's no autoformatter yet, so consistency is manual.
  3. Docs move with code — module pages map 1:1 to backend files; endpoints appear in the API Reference; fixed bugs leave Known Issues. Undocumented features don't exist.
  4. Honesty over polish — new limitations get documented (Known Issues / Roadmap), not hidden.

PR checklist

  • Branch from main; main stays deployable (it auto-publishes the docs site)
  • Backend boots from backend/app/ against an existing dev DB (catches missing migrations)
  • Quick Start sequence passes manually (until automated tests land — adding some is a great PR)
  • npm run typecheck clean (if frontend touched)
  • uv run mkdocs build warning-free (if docs touched)
  • Commit style matches history (fix: …, docs: …, feat: …)
  • PR description: what changed, why, how verified, and which docs pages were updated

Reporting bugs

Best-case report: the failing curl, the response, the relevant telemetry (runs / tool-calls / workflow-runs output — failures always leave records, Observability), and your environment (OS, Python, whether OPENAI_API_KEY is set). Check Troubleshooting and Known Issues first.

Good first contributions

In rough order of ramp-up difficulty:

ContributionDocs that spec it
Tier-1 unit tests (pure functions)Testing plan
Fix a Known Issue (e.g. the generate_rag_answer indentation)Known Issues
Uniform cost logging on chat/analyze/RAGcoverage map
Shared log_tool_call helper (de-duplicate routers)documents router
Real DELETE /agents/{id} with vector cleanupKnown Issues
Agent detail pageRoadmap M2

Docs-only contributions

Fix typos, clarify explanations, add diagrams — docs PRs follow the same flow. Authoring conventions (relative .md links, admonitions, mermaid, nav registration): Docs Site.

Code of conduct

Be kind, assume good faith, critique code not people. Review comments should teach, not gatekeep.

PreviousRAG End to EndNextRoadmap