> ## Documentation Index
> Fetch the complete documentation index at: https://docs.winstory.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing Guide

> How to contribute safely to Winstory.io.

## Goals

This guide explains **how to contribute** to the Winstory.io codebase **without breaking** critical Web3 and economic flows.

It is intended for:

* Internal engineers
* External contributors (agencies, partners)

## Branching & Workflow

* Use feature branches: `feature/<area>-<short-description>`
* Never push directly to `main` without a PR
* Use small, focused PRs:
  * 1 feature or fix
  * 1–5 files touched when possible

## Code Quality

* Language: **TypeScript** everywhere (frontend + backend)
* Follow existing patterns:
  * API routes in `app/api/*`
  * Shared logic in `lib/*`
  * UI in `components/*`
* Prefer **pure functions** in `lib/` over logic inside components

## Safety Rules (Web3 & Payments)

Before merging any change touching these areas:

* **Blockchain / contracts**
  * Never change contract addresses without updating `deployments/` and `contract-registry`
  * Run the Base Sepolia E2E tests
* **Payments (Stripe/Crypto)**
  * Keep verification logic in `lib/payment-verification.ts` and `lib/crypto-payment-verification.ts`
  * Never bypass amount checks in production
* **Rewards**
  * Use existing helpers for reward types and tiers
  * If in doubt, update docs in `ACCESS_REWARDS_IMPLEMENTATION_SUMMARY.md`

## Testing

For any non-trivial change:

* Run `npm run build` locally
* Run targeted tests:
  * `npm test -- __tests__/b2c-agency-e2e-flow.test.ts`
  * `tsx scripts/test-b2c-agency-e2e.ts` (when touching B2C/Agency)

## Documentation

* Any new public endpoint → update `advanced/api-reference.mdx`
* Any architectural change → update `advanced/architecture.mdx`