Docs: publish API contract index.

docs/quality/CONTRIBUTOR_GUIDE.md

@@ -0,0 +1,148 @@
+# Stellar Wave Contributor Guide
+
+## What is a Stellar Wave Issue?
+
+A **Stellar Wave** issue represents a significant, well-scoped feature or infrastructure improvement that deserves careful, production-ready implementation. Stellar Wave issues are the gold standard for quality in the Tikka ecosystem.
+
+The name reflects our commitment to making a "wave" of quality across all packages — raising the bar for robustness, documentation, testing, and observability.
+
+---
+
+## When to Use Stellar Wave
+
+Label an issue **Stellar Wave** if it:
+
+✅ **Is a major feature or improvement**
+- New auction mechanism, payment flow, or notification system
+- Infrastructure overhaul (new cache layer, observability platform, CI/CD enhancement)
+- API redesign or significant contract interaction change
+
+✅ **Will impact multiple components or users**
+- Changes to backend API used by client and SDK
+- Database schema changes affecting indexer or oracle
+- Public API additions to published packages
+
+✅ **Requires careful rollout**
+- Data migrations needed
+- Backward compatibility concerns
+- Deployment sequencing required
+
+❌ **Is NOT appropriate for Stellar Wave**
+- Bug fixes (use `bug` label instead)
+- Minor refactorings (use `refactor` label)
+- Documentation-only PRs (use `docs` label)
+- Dependency updates (use `dependencies` label)
+
+---
+
+## How to Implement a Stellar Wave Issue
+
+### 1. Plan Before Coding
+
+Read this entire quality standards document: [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md)
+
+Identify which sections apply to your issue:
+- Is it backend-only? Focus on [Backend section](./STELLAR_WAVE_CHECKLIST.md#backend-backend)
+- Does it touch client? Include [Client requirements](./STELLAR_WAVE_CHECKLIST.md#client-client)
+- Are there database changes? Review [Migration section](./STELLAR_WAVE_CHECKLIST.md#5-database-migrations)
+
+### 2. Implement with Quality in Mind
+
+Build the feature while addressing each requirement category:
+
+| Category | Action |
+|---|---|
+| **Docs** | Write API spec, code comments, runbook as you code |
+| **Tests** | Write tests alongside implementation (TDD or alongside approach) |
+| **Logging** | Add structured logs for debugging and monitoring |
+| **Errors** | Implement proper error handling and user messaging |
+| **Migration** | Create database migrations; test rollback |
+| **Types** | Use TypeScript strict mode; validate inputs with Zod |
+
+### 3. Verify Before Review
+
+Run the package-specific CI command from [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md#package-specific-expectations):
+
+```bash
+# Example for backend
+cd backend
+pnpm run build
+pnpm run test -- --ci
+pnpm run lint
+pnpm run validate:openapi
+```
+
+Use the [Review Checklist](./STELLAR_WAVE_CHECKLIST.md#review-checklist) before opening your PR.
+
+### 4. Open PR with Context
+
+In your PR description:
+- Link the original issue
+- Briefly describe implementation approach
+- Highlight any design decisions or trade-offs
+- Note any new dependencies added
+- Confirm you've completed the Stellar Wave checklist
+
+Example:
+```markdown
+Fixes #42 (Implement auction mechanism)
+
+## Implementation
+- Implemented blind auction with commit-reveal phases
+- Added auction state machine to validate transitions
+- Integrated with existing raffle contract interface
+
+## Quality Checklist
+- [x] Tests: 84% coverage, integration tests for state machine
+- [x] Docs: OpenAPI spec, runbook for operators
+- [x] Logging: Structured logs for each auction phase
+- [x] Errors: User-friendly messages, proper HTTP status codes
+- [x] Migrations: TypeORM migration for auction_events table, rollback tested
+
+## New Dependencies
+None
+
+## Breaking Changes
+None; auction mechanism is additive feature
+```
+
+### 5. Address Review Feedback
+
+Reviewers will check:
+- Does implementation satisfy the Stellar Wave standard?
+- Are there gaps in tests, docs, or error handling?
+- Does code follow package conventions?
+- Are there security or performance concerns?
+
+Iterate until all feedback addressed.
+
+---
+
+## Common Pitfalls
+
+| Pitfall | How to Avoid |
+|---|---|
+| **Missing Tests** | Write tests first or alongside code; aim for 80%+ coverage |
+| **Vague Error Messages** | Put yourself in user's shoes; error should explain what went wrong and suggest fix |
+| **No Logging** | Add structured logs with context; should be debuggable from logs alone |
+| **Incomplete Migrations** | Test `migration:revert` works; include data migration logic, not just schema |
+| **Undocumented Design Decisions** | Comment non-obvious logic; document why, not just what |
+| **Ignored Package Conventions** | Read existing code in the package; follow established patterns |
+| **Cross-Package Integration Issues** | Test with real dependencies; don't mock away integration problems |
+
+---
+
+## Questions?
+
+Refer to:
+- [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md) — comprehensive requirements
+- [ARCHITECTURE.md](../ARCHITECTURE.md) — ecosystem design and data flows
+- Package README — language, tools, and conventions
+
+If guidance is missing or unclear, open an issue labeled `question` or `documentation`.
+
+---
+
+**Remember:** Stellar Wave issues are about raising the bar collectively. High standards make the codebase more maintainable, debuggable, and reliable for everyone.
+
+Happy building! 🌊

docs/quality/QUICK_REFERENCE.md

@@ -0,0 +1,115 @@
+# Stellar Wave Quick Reference
+
+**One-page checklist for contributors implementing Stellar Wave issues.**
+
+---
+
+## Pre-Implementation
+
+- [ ] Read [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md)
+- [ ] Identify affected package(s) (backend, client, indexer, oracle, sdk)
+- [ ] Plan docs, tests, logging, error handling upfront
+
+---
+
+## Universal Checklist
+
+| Item | Status |
+|---|---|
+| **Docs** — API spec, code comments, runbook |  |
+| **Tests** — Unit (80%+), integration, e2e | ✓ |
+| **Logging** — Structured logs, no PII | ✓ |
+| **Errors** — Proper status codes, user-friendly messages | ✓ |
+| **Migrations** — TypeORM, reversible, data-safe | ✓ |
+| **Linting** — `pnpm run lint` passes | ✓ |
+| **Security** — No secrets in code, dependencies audited | ✓ |
+
+---
+
+## Package-Specific Commands
+
+### Backend
+```bash
+cd backend
+pnpm run build && pnpm run test -- --ci && pnpm run lint && pnpm run validate:openapi
+```
+
+### Client
+```bash
+cd client
+pnpm run build && pnpm run test:unit && pnpm run test:e2e && pnpm run lint
+```
+
+### Indexer
+```bash
+cd indexer
+pnpm run build && pnpm run test && pnpm run test:integration --forceExit && pnpm run lint
+```
+
+### Oracle
+```bash
+cd oracle
+pnpm run build && pnpm run test && pnpm run lint
+```
+
+### SDK
+```bash
+cd sdk
+npm run build && npm run test && npm run lint && npm run docs
+```
+
+---
+
+## Cross-Package
+
+```bash
+# From root
+pnpm run build && pnpm run test
+```
+
+---
+
+## Before Opening PR
+
+- [ ] All CI commands pass locally
+- [ ] No console.log, TODOs, or debug code left
+- [ ] Code follows package conventions
+- [ ] `README.md` updated (if user-facing)
+- [ ] Changelog entry added (if applicable)
+- [ ] Related issues linked
+
+---
+
+## PR Description Template
+
+```markdown
+Fixes #<issue-number>
+
+## Implementation
+- [ ] Describe approach
+
+## Stellar Wave Checklist
+- [x] Tests: <coverage %>
+- [x] Docs: <what documented>
+- [x] Logging: <what logged>
+- [x] Errors: <error handling>
+- [x] Migrations: <if applicable>
+
+## Breaking Changes
+<none / describe>
+
+## Dependencies
+<none / list>
+```
+
+---
+
+## Need Help?
+
+- **Full Requirements** → [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md)
+- **What is Stellar Wave?** → [CONTRIBUTOR_GUIDE.md](./CONTRIBUTOR_GUIDE.md)
+- **Ecosystem Design** → [ARCHITECTURE.md](../ARCHITECTURE.md)
+
+---
+
+**Last Updated:** 2026-05-29

docs/quality/README.md

@@ -0,0 +1,94 @@
+# Tikka Quality Standards
+
+Welcome to the quality standards directory for the Tikka ecosystem. Here you'll find the guidelines and checklists that define what it means to ship high-quality, production-ready code.
+
+---
+
+## Documents
+
+### 📋 [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md)
+**The definitive standard for Stellar Wave issues.**
+
+Comprehensive requirements across:
+- Documentation (API specs, code comments, runbooks)
+- Tests (unit, integration, e2e)
+- Telemetry (logging, tracing, metrics)
+- Error handling (user-facing messages, graceful degradation)
+- Database migrations (TypeORM, reversibility, data safety)
+- Package-specific expectations (backend, client, indexer, oracle, sdk)
+- CI/CD integration and commands
+
+**When to use:** Before implementing a Stellar Wave issue, or reviewing one. Reference this to ensure nothing is missed.
+
+---
+
+### 🎯 [CONTRIBUTOR_GUIDE.md](./CONTRIBUTOR_GUIDE.md)
+**Guidance for implementing Stellar Wave issues.**
+
+Explains:
+- What qualifies as a Stellar Wave issue
+- Step-by-step implementation workflow
+- Common pitfalls and how to avoid them
+- PR submission best practices
+
+**When to use:** You're about to start a Stellar Wave issue, or onboarding a new contributor.
+
+---
+
+### ⚡ [QUICK_REFERENCE.md](./QUICK_REFERENCE.md)
+**One-page checklist for fast reference.**
+
+Contains:
+- Pre-implementation checklist
+- Package-specific CI commands
+- PR description template
+- Quick links to full docs
+
+**When to use:** Before opening a PR, or as a refresher during implementation.
+
+---
+
+## Quick Start
+
+1. **Implementing your first Stellar Wave issue?**
+   - Read [CONTRIBUTOR_GUIDE.md](./CONTRIBUTOR_GUIDE.md) first
+   - Then reference [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md) as you build
+
+2. **Need to verify implementation?**
+   - Use [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) for CI commands and checklist
+   - Reference package-specific section in [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md)
+
+3. **Reviewing someone else's Stellar Wave PR?**
+   - Check against [STELLAR_WAVE_CHECKLIST.md](./STELLAR_WAVE_CHECKLIST.md) requirements
+   - Use [CONTRIBUTOR_GUIDE.md](./CONTRIBUTOR_GUIDE.md) to understand implementation approach
+
+---
+
+## Philosophy
+
+Stellar Wave issues are the ecosystem's commitment to quality. By maintaining high standards:
+
+✅ **Reliability** — Issues are thoroughly tested and documented  
+✅ **Maintainability** — Clear logging and comments make debugging easier  
+✅ **Scalability** — Error handling and migrations prepare for growth  
+✅ **Consistency** — Package-specific expectations align with ecosystem patterns  
+
+Every Stellar Wave issue raises the bar for the entire project.
+
+---
+
+## Feedback
+
+These standards are living documentation. If you find:
+- **Missing guidance** — Open an issue with `quality` label
+- **Outdated information** — Submit a PR with corrections
+- **Unclear requirements** — Ask in PR discussions or issues
+
+Together, we maintain excellence. 🌊
+
+---
+
+**Related Resources:**
+- [Tikka Architecture](../ARCHITECTURE.md) — Ecosystem design and data flows
+- [Tikka README](../../README.md) — Project overview and setup
+- [GitHub Workflows](.github/workflows/) — CI/CD configuration