# Contributing to Lumotia

## Welcome

Lumotia is a single-developer-led, AI-assisted, human-directed indie app. Jake Sames at CORBEL defines the product, sets the privacy model, writes the tests that matter, and ships through a repeatable quality gate. AI coding tools are used during implementation. Every release is dogfood-tested, every release ships a known-limitations document, and every release has an audit trail in the git log. Read `docs/release/how-lumotia-is-built.md` to understand the trust model before contributing.

## What we are looking for in v0.1

Bug reports and tester feedback are the most valuable contributions right now. **New feature work is paused until v0.2** — the scope is locked per `docs/release/v0.1-checklist.md`. Reopening a v0.2-flagged item moves the ship date. If you have a feature idea, open a Discussion rather than a PR.

## How to file a bug

Open an issue using the **Bug report** template. The template walks you through version, platform, steps to reproduce, and expected vs actual behaviour.

Please attach a diagnostic bundle — it speeds up triage significantly. Generate one from **Settings → Help → Generate diagnostic bundle**. The bundle never includes audio or transcript content; it contains logs, system info, and redacted preferences only.

## How to file v0.1 tester feedback

Open an issue using the **v0.1 Tester feedback** template. It covers the structured questions from the tester-onboarding-kit: cold-setup pass, warm-activation pass, confusion points, breakage, task-extraction quality, and whether you would use it again.

If you followed the onboarding kit, you already have the answers. The template takes about 5 minutes to fill in.

## How to submit a PR

Small, focused changes only. The PR template has a checklist — run every gate green before submitting.

Before submitting:

- `cargo test --workspace` green
- `cargo fmt --check` clean
- `cargo clippy --workspace --all-targets -- -D warnings` clean
- `npm run check` 0 errors / 0 warnings
- `npm run test` green
- `scripts/dogfood-rebrand-drill.sh` 8/8 (if you touched migration or data-directory logic)
- Manual UI walk-through (if you touched the frontend)

**Architectural changes require a Discussion first.** Opening a PR that restructures crates, reorganises commands, or changes the storage schema without prior alignment wastes both our time.

## Local dev setup

```bash
npm ci --ignore-scripts   # never bare npm install — --ignore-scripts blocks postinstall vectors
./run.sh                  # canonical dev launch (Vite + Tauri, with supply-chain pre-flight)
npm run dev:frontend      # frontend-only iteration, no Tauri
```

Per-platform dependencies (WebKit, LLVM, Rust toolchain, evdev headers) are documented in `docs/dev-setup.md`. The Rust toolchain is pinned in `rust-toolchain.toml` — you do not need to manage it manually.

## Code of conduct

This is a calm, professional project. No harassment, no personal attacks, no bad-faith contributions. The maintainer is one person — please be patient on response times. Issues and PRs that are rude or dismissive will be closed without comment.

## Licence

Lumotia is licensed under **AGPL-3.0-or-later**. By submitting a pull request, you agree that your contribution is offered under the same licence. If that does not work for you, please say so before putting in the work.