# Contributing to portfolio-optimiser-claude

Thank you for your interest in contributing! This document provides guidelines and instructions
for contributing.

## Code of Conduct

Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).

## How to Contribute

### Reporting Issues

- Check existing issues before creating a new one
- Provide clear reproduction steps
- Include relevant environment details (OS, Python version)

### Submitting Changes

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes following the conventions below
4. Run the test, lint, and type checks (see Development Setup) and ensure they pass
5. Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/)
   (`type(scope): description`)
6. Push to your branch and open a Pull Request

### Pull Request Guidelines

- Follow the existing code style (`ruff` enforced)
- Type hints everywhere; `mypy`-clean where possible
- Include tests for new functionality — this project uses **load-bearing tests**: a test that
  covers a seam must fail when that seam is detached, not merely pass while wired
- The **deterministic validator is mandatory and blocking** — never make it an optional plugin
- Keep PRs focused on a single change
- Update documentation as needed

## Development Setup

Requires Python ≥ 3.10 and [`uv`](https://docs.astral.sh/uv/).

```bash
# Clone your fork
git clone https://git.fromaitochitta.com/open/portfolio-optimiser-claude.git
cd portfolio-optimiser-claude

# Install dependencies
uv sync

# Run tests (offline, no API key required)
uv run pytest

# Lint and format
uv run ruff check .
uv run ruff format --check .

# Type-check (strict)
uv run mypy src
```

Tests run offline without an API key. A live run requires your own `ANTHROPIC_API_KEY` — keep it
in your environment, never commit it. It is the only accepted credential: a consumer Claude Code
subscription is not supported and must not be used to pay for a run, so a `CLAUDE_CODE_OAUTH_TOKEN`
is refused by the preflight and by the run entrance.

## Questions?

Feel free to open an issue for any questions about contributing.