# Contributing to LenserFight

Thanks for contributing.

This root file exists for GitHub community health features. The canonical contributor docs live under `docs/en/how-to/contributors/`.

## Canonical docs

Canonical site (browse online): [https://docs.lenserfight.com](https://docs.lenserfight.com)

- Contributor guide: [docs.lenserfight.com/how-to/contributors/contributing](https://docs.lenserfight.com/how-to/contributors/contributing) — `docs/en/how-to/contributors/contributing.md`
- Development setup: [docs.lenserfight.com/how-to/contributors/development-setup](https://docs.lenserfight.com/how-to/contributors/development-setup) — `docs/en/how-to/contributors/development-setup.md`
- Your first PR: [docs.lenserfight.com/how-to/contributors/first-pr](https://docs.lenserfight.com/how-to/contributors/first-pr) — `docs/en/how-to/contributors/first-pr.md`
- Architecture map: [docs.lenserfight.com/how-to/contributors/architecture-map](https://docs.lenserfight.com/how-to/contributors/architecture-map) — `docs/en/how-to/contributors/architecture-map.md`
- Coding standards: [docs.lenserfight.com/how-to/contributors/coding-standards](https://docs.lenserfight.com/how-to/contributors/coding-standards) — `docs/en/how-to/contributors/coding-standards.md`
- Branching and versioning: [docs.lenserfight.com/how-to/contributors/branching](https://docs.lenserfight.com/how-to/contributors/branching) — `docs/en/how-to/contributors/branching.md`
- Release process: [docs.lenserfight.com/how-to/contributors/release-process](https://docs.lenserfight.com/how-to/contributors/release-process) — `docs/en/how-to/contributors/release-process.md`
- CLI release guide: [docs.lenserfight.com/how-to/contributors/cli-release](https://docs.lenserfight.com/how-to/contributors/cli-release) — `docs/en/how-to/contributors/cli-release.md`
- Code of conduct: [docs.lenserfight.com/how-to/contributors/code-of-conduct](https://docs.lenserfight.com/how-to/contributors/code-of-conduct) — `docs/en/how-to/contributors/code-of-conduct.md`
- Support routing: [docs.lenserfight.com/how-to/contributors/support](https://docs.lenserfight.com/how-to/contributors/support) — `docs/en/how-to/contributors/support.md`
- Security reporting: [docs.lenserfight.com/how-to/contributors/security](https://docs.lenserfight.com/how-to/contributors/security) — `docs/en/how-to/contributors/security.md`
- Translations & i18n: [docs.lenserfight.com/how-to/contributors/i18n-guide](https://docs.lenserfight.com/how-to/contributors/i18n-guide) — `docs/en/how-to/contributors/i18n-guide.md`
- Adding a new language: [docs.lenserfight.com/how-to/contributors/adding-a-language](https://docs.lenserfight.com/how-to/contributors/adding-a-language) — `docs/en/how-to/contributors/adding-a-language.md`

## Maintainer triage labels

- `p0-install`
- `p0-workflow`
- `docs`
- `good first issue`
- `deferred`

## Quick start

Three commands to get a working local environment:

```bash
git clone https://github.com/conectlens/lenserfight && cd lenserfight
./scripts/dev-start.sh          # starts Supabase local + Vite dev server
pnpm smoke                      # validates build, migrations, and pgTAP suite
```

Full setup detail: [docs/en/how-to/contributors/development-setup.md](docs/en/how-to/contributors/development-setup.md)

## Where to start

1. Browse issues labeled **`good first issue`** — these are scoped to ≤2 files and have acceptance criteria.
2. Check the [project board](https://github.com/orgs/conectlens/projects) for in-progress and backlog items.
3. For questions, open a GitHub Discussion or join the Discord linked in the repo description.

If you want to build something that isn't tracked yet, open a **Feature request** issue first. This avoids duplicate work and lets maintainers flag any conflicting migrations before you invest time.

## 🤝 Sharing & Showcasing Your Work

LenserFight is built to support collaborative experimentation. Developers are welcome to share their run logs, benchmark results, and creative integrations:

*   **Community Showcases**: If you have published a walkthrough guide, benchmark documentation, or setup tutorial, you can propose adding it to the community showcase table in the [root README.md](README.md) by opening a Pull Request. Proposing a link is optional and subject to repository guideline reviews by maintainers.
*   **Share Workflows & Lenses**: If you have developed a reusable workflow template or unique Lens contract, you can commit it to the `examples/` or `templates/` directory to share it with other developers.
*   **Agent Failures & Analysis**: If you capture an interesting model failure, edge-case behavior, or unexpected judge scoring rationale, you can open a thread under **GitHub Discussions** or share it on social channels with **`#LenserFight`** to help the community analyze and improve agent prompts.



## Test philosophy

LenserFight has two testing layers that serve different purposes:

**pgTAP — database layer**

All Supabase schema invariants, RLS policies, trigger behavior, and RPC correctness are verified with pgTAP tests in `supabase/tests/`. Run them with:

```bash
pnpm run-pgtap
```

Each test file uses `SELECT plan(N)` — check the plan count matches the assertions before opening a PR.

**Vitest — TypeScript layers**

Feature components, hooks, and utilities use Vitest. Always run tests for the specific project you changed:

```bash
pnpm nx test <project> --testFile=path/to/file.spec.ts
```

Never run `pnpm nx test cli` without `--testFile` — the CLI test suite includes integration specs that time out on most developer machines.

## Contribution license and expectations

Unless you explicitly state otherwise, contributions intentionally submitted to this repository are provided under the repository license, currently MIT. Do not submit code, docs, prompts, templates, media, generated output, or data that you do not have the right to contribute.

Open-source contributions are voluntary. Contributing does not create employment, payment rights, ownership, or governance authority. Any paid arrangement requires a separate written agreement with LenserFight maintainers. Questions or commercial proposals: lets@conectlens.com

Do not include secrets, private keys, provider credentials, customer data, regulated data, private prompts, non-public third-party content, or exploit details in issues, pull requests, examples, screenshots, logs, or generated fixtures. Report vulnerabilities privately through [SECURITY.md](SECURITY.md).

Maintainers should consider adding a DCO sign-off or CLA only if contribution provenance becomes hard to audit or commercial relicensing is planned. Until then, the MIT License plus clear PR provenance expectations are the lightweight baseline.

## PR checklist

Before opening a pull request, verify:

- [ ] `pnpm smoke` exits 0 (or `pnpm nx build cli && pnpm nx run web:build` for UI-only changes)
- [ ] Any migration is in a new file under `supabase/migrations/` — do **not** edit existing migrations
- [ ] New migration has a matching pgTAP test (or a comment explaining why it doesn't need one)
- [ ] `pnpm run-pgtap` passes against the new migration
- [ ] No direct SQL changes to already-migrated tables without a migration file
- [ ] Public library API changes are reflected in the lib's `src/index.ts`
- [ ] Screenshots included for UI changes
- [ ] No secrets, private data, or unsupported legal/security/privacy claims were added
- [ ] Agent, workflow, BYOK, provider, or automation changes document cost, permission, privacy, and misuse risks

## Code of conduct

This project follows the [Contributor Covenant](docs/en/how-to/contributors/code-of-conduct.md). Be kind, be specific, assume good faith.
