# Contribution Guidelines

These guidelines are aimed at keeping work in this repository consistent across the frontend, backend, and operational layers.

## Contribution Workflow

1. Start from a focused branch.
2. Keep the change set tight around one feature, bug fix, or documentation task.
3. Update tests or docs when behavior changes.
4. Run the relevant validation commands before opening a review.

## Frontend Conventions

- App routes live in `stitch/frontend/src/app`.
- Reusable product UI lives in `stitch/frontend/src/components`.
- API clients and integration helpers live in `stitch/frontend/src/lib`.
- Prefer fitting new work into the existing route groups and shared component system rather than duplicating patterns.

## Backend Conventions

- Keep HTTP routing readable and explicit.
- Put reusable domain behavior in `stitch/backend/services` instead of growing route handlers further.
- Add focused controllers when a domain area deserves its own router, as already done for billing and chat.
- Keep Pydantic models explicit and aligned with the API surface.

## Database and Data Changes

- Schema snapshots live in `stitch/backend/supabase_schema.sql`.
- Incremental changes should be added in `stitch/backend/migrations`.
- If a feature depends on recommendations or academic knowledge, update the corresponding sync or ingestion flow as part of the same change.

## Design and Prototyping

- Non-runtime stitched prototypes in `stitch/` are useful references when implementing new product surfaces.
- Experimental work should stay isolated in `experiments/` until it is ready to move into the production runtime.

## Validation Checklist

Run the commands that match your change:

```bash
cd stitch/frontend
npm run lint
```

```bash
cd stitch/backend
pytest
```

```bash
cd docs
make html
```

## Documentation Expectations

If you add a new major route group, backend capability, worker, or integration, update the matching documentation page in this `docs/` tree so the site stays useful as a project handbook.