docs: add ADRs, API error reference, troubleshooting and git workflow guides

[graceuvala-collab]

Overview

Adds four contributor-facing documentation sets that were missing from the project. Documentation only — no source changes.

Closes #516
Closes #511
Closes #513
Closes #512

Changes

Architecture Decision Records — Closes #516

New docs/adr/ directory:

File	Purpose
README.md	Index, lifecycle/status table, and how to write or supersede an ADR
0000-template.md	Template: context, drivers, options considered, decision, consequences
0001-off-chain-listener-architecture.md	Why a centralised listener over per-consumer polling or a streaming platform
0002-soroban-smart-contracts.md	Why Soroban on Stellar
0003-sqlite-for-local-persistence.md	Why SQLite over in-memory or an external database
0004-typescript-for-listener-service.md	Why TypeScript over plain JS or Rust for the listener
0005-event-deduplication-strategy.md	Why a bounded SHA-256 fingerprint cache over raw ID sets or SQLite lookups

Each record documents the options actually weighed and the trade-offs accepted, not just the outcome.

API Error Reference — Closes #511

New docs/API_ERROR_REFERENCE.md. Every error response the listener API returns, organised by status code (400/401/404/409/413/429/500/503), each with cause, resolution, and a runnable example. Also covers the diagnostic headers (X-Request-Id, X-Correlation-Id, X-API-Version), the rate-limit headers, the nine batch-validation error codes, and a quick-reference table mapping every documented error to its endpoint and fix.

Content is derived from the actual handlers — listener/src/api/events-server.ts, template-routes.ts, rate-limiter.ts, and listener/src/utils/batch-validator.ts — rather than written from assumption. The guide explicitly flags that only the batch-validation code values are stable enough to branch on, since the API does not yet emit a top-level machine-readable code.

Contributor Troubleshooting Guide — Closes #513

New docs/CONTRIBUTOR_TROUBLESHOOTING.md, covering install/dependency failures, TypeScript and build errors, test failures (including flaky timing-dependent tests and open handles), running the listener locally, database and migration issues, dashboard problems, Rust/Soroban issues, Git mistakes, and CI failures — with a triage section up front and a structured bug-report checklist at the end.

Scoped deliberately to the contribution workflow so it complements rather than duplicates the existing TROUBLESHOOTING.md (environment setup) and DEPLOYMENT_TROUBLESHOOTING.md (deploys); a table at the top routes readers to the right one.

Git Workflow Guide — Closes #512

New docs/GIT_WORKFLOW.md: the fork model with a diagram and remote-role table, one-time setup, fork syncing, branch naming (six prefixes, with worked examples and an anti-pattern table), Conventional Commits, the day-to-day loop, PR requirements, conflict recovery, post-merge cleanup, and a command cheat sheet.

Documentation cross-references

• README.md — new links to the ADR index, API error reference, and both contributor guides; Contributing section now points at them.
• CONTRIBUTING.md — companion-guides block at the top; the workflow section now directs contributors to read the ADRs before significant architectural changes and to add a new ADR when a decision changes.

This satisfies the "Documentation references ADRs" criterion on #516.

Acceptance criteria

#516 — ADR template added ✅ · Initial ADRs created (5) ✅ · Documentation references ADRs ✅
#511 — Error codes listed ✅ · Descriptions included ✅ · Examples provided ✅
#513 — Common issues documented ✅ · Guide is easy to navigate (numbered TOC, triage section, cross-links) ✅
#512 — Workflow documented ✅ · Branch naming examples included ✅ · PR process explained ✅

Verification

Documentation-only change — no code, config, or dependency modifications, so no build or test run was performed. Technical claims were grounded by reading the source directly rather than by execution:

• Error responses, status codes, and endpoint paths read from the API handlers listed above.
• Default events API port (8787) and database path (./data/notifications.db) from listener/src/config.ts.
• Payload limit (64 KB) from listener/src/utils/payload-size-validator.ts.
• Deduplication defaults (10,000 entries / 60s window) and fingerprint construction from listener/src/services/notification-deduplicator.ts.
• npm commands from the listener/ and dashboard/ package.json scripts; Node 22 and the CI job matrix from .github/workflows/ci.yml.

One item worth a reviewer's eye: the guides state that CI is path-filtered on pull requests (listener/src/migrations/, listener/src/database/, listener/src/scripts/, listener/package.json), so a docs-only PR such as this one runs no CI jobs by design. Please confirm that filter is intended — if CI is meant to run more broadly on PRs, that is a separate fix and I'm happy to open an issue.

How to test

1. Read docs/adr/README.md and confirm all five indexed ADRs resolve.
2. Open docs/API_ERROR_REFERENCE.md and spot-check a few responses against listener/src/api/events-server.ts.
3. Follow the TOC links in each new guide to verify anchors resolve.
4. Confirm the new links in README.md and CONTRIBUTING.md resolve.

🤖 Generated with Claude Code

[drips-wave]

@graceuvala-collab Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits