# Contributing to Persome Runtime

## Dev setup

Requirements: macOS 13+ (for the full capture stack; the Python daemon and its
offline tests also run on Linux), Python 3.12, [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/Intuition-Lab/personal-model.git
cd personal-model
uv sync --all-extras
```

## Tests

The default gate is fully offline: no network, no API key. LLM calls are mocked
via `PERSOME_LLM_MOCK=1`.

```bash
# Offline unit gate (what CI runs; ~2 min)
PERSOME_LLM_MOCK=1 uv run pytest -m "not macos and not integration" -q

# Single file / test
PERSOME_LLM_MOCK=1 uv run pytest tests/test_model_snapshot.py -q
```

Marker meanings:

| marker | needs | run in CI? |
|---|---|---|
| (unmarked) | nothing (offline, mocked LLM) | yes |
| `macos` | real macOS AX permission / Swift capture helpers | no |
| `integration` | real LLM provider credentials | no |

## Lint

```bash
uv run ruff check .
uv run ruff format --check .
uv run python scripts/secret_scan.py
uv run python scripts/language_scan.py
uv run python scripts/check_doc_links.py
```

To inspect coverage locally:

```bash
PERSOME_LLM_MOCK=1 uv run pytest -m "not macos and not integration" \
  --cov=persome --cov-report=term-missing
```

## Secret and PII gates (required)

No real names, emails, tokens, or captured personal content may enter the repo —
test data is synthetic, always. Before pushing:

```bash
uv run python scripts/secret_scan.py
uv run python scripts/pii_scan.py   # must exit 0
```

## Repository language

Human-authored source, prompts, documentation, and fixtures use English. Run
`uv run python scripts/language_scan.py` before pushing. Multilingual parser
test values use Unicode escapes, and the bundled PP-OCRv6 character dictionary
is allowlisted because changing it would break local OCR.

## Branches and pull requests

1. Fork (or branch) off `main`; name branches `feat/<scope>`, `fix/<scope>`,
   `docs/<scope>`, `chore/<scope>`.
2. Keep commits in Conventional Commit style: `type(scope): summary`.
3. Open the PR against `main` and fill in the template (What / Why / How
   verified).
4. CI must be green: offline test gate + PII scan on ubuntu and macos runners.

## Contributor acknowledgements

The contributor cards in `README.md` follow the
[All Contributors](https://allcontributors.org/) specification. They recognize
code and non-code work and are maintained separately from GitHub's automatic
commit-author contributor graph.

Maintainers can add or update a GitHub profile with the CLI:

```bash
npx all-contributors-cli add <github-login> <contribution-type[,contribution-type]>
uv run python scripts/render_contributors.py
```

For example, `code`, `doc`, `design`, `ideas`, `maintenance`, `projectManagement`,
and `review` are useful contribution types for this project. The second command
restores Persome's compact card layout after the CLI updates the contributor
data. Verify the generated cards with
`uv run python scripts/render_contributors.py --check`, then commit both
`README.md` and `.all-contributorsrc`. Organization membership can make a
profile easier to find, but acknowledgement should reflect a real contribution
rather than membership alone.

## DCO — sign your commits

This project uses the [Developer Certificate of Origin](https://developercertificate.org/).
Every commit must carry a `Signed-off-by` line matching the commit author:

```bash
git commit -s -m "fix(recall): handle empty FTS index"
```

which appends:

```
Signed-off-by: Your Name <you@example.com>
```

By signing off you certify you have the right to submit the contribution under
the project's Apache-2.0 license.

## License

Contributions are accepted under [Apache-2.0](LICENSE). See [LICENSES.md](LICENSES.md)
for the boundary between this Runtime and separate publication artifacts, and
`NOTICE` / `THIRD_PARTY_NOTICES` for incorporated third-party work.