# Contributing to ALPHA

Thanks for your interest in improving ALPHA. This guide covers how to set up, what we expect in a pull request, and
how security-sensitive changes are handled.

## Ground Rules

- Be kind — see [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
- **Never** report security vulnerabilities in public issues — follow [SECURITY.md](SECURITY.md).
- Never commit secrets, API keys, tokens, or real customer data. Mock data only.
- Keep security labels honest: do not add UI text claiming a control is active unless it is implemented.

## Development Setup

```bash
cd nextjs_space
yarn install
yarn dev
```

Before pushing:

```bash
yarn lint
npx tsc --noEmit     # or: yarn tsc --noEmit
yarn build
```

## Project Conventions

| Area | Convention |
|------|-----------|
| Pages | One component per module in `components/pages/*-page.tsx`, loaded with `next/dynamic` (`ssr: false`) |
| Shared UI | `components/alpha-ui/` — reuse `PageWrapper`, `StatCard`, `HealthRing` before creating new widgets |
| Data | All mock data lives in `lib/mock-data.ts`; types in `lib/types.ts` |
| Navigation | Add new sections to the `NavSection` union and the sidebar config |
| Styling | Tailwind + `glass-panel` / `glass-panel-hover`; palette `#0A0A0F`, `#00F5FF`, `#8B5CF6`, `#EC4899` |
| Fonts | DM Sans (body), Plus Jakarta Sans (display), JetBrains Mono (data/code) |
| SSR safety | No `Math.random()` / `Date.now()` in render; use `useEffect` or `SafeDate` / `SafeNumber` |
| Framework | Next.js 16: async `params`, `proxy.ts` instead of middleware, no `webpack` key in config |

## Branches & Commits

- Branch from `main`: `feat/<topic>`, `fix/<topic>`, `docs/<topic>`, `sec/<topic>`.
- Use [Conventional Commits](https://www.conventionalcommits.org): `feat(mesh): add radial layout`.
- Keep PRs focused; one logical change per PR.

## Pull Request Checklist

- [ ] Lint, type-check, and build pass locally
- [ ] UI changes include a screenshot or short clip
- [ ] No secrets or real personal data added
- [ ] Docs updated (README / ARCHITECTURE / CHANGELOG) where relevant
- [ ] Commerce or policy changes validated with `node scripts/validate-commerce-policy.mjs`

## Review Process

1. CI (lint, type-check, build) and security workflows must be green.
2. A CODEOWNER approval is required; paths listed as security-sensitive in `.github/CODEOWNERS` need explicit owner review.
3. Maintainers squash-merge with a Conventional Commit title.

## Reporting Bugs & Requesting Features

Use the issue templates under **Issues → New issue**. Include steps to reproduce, expected vs. actual behavior, and
browser/OS details.

## License

By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).