trainjudge 0.2.1__tar.gz

trainjudge-0.2.1/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "trainjudge",
+  "description": "TrainJudge: decide whether to fine-tune, then verify it actually worked.",
+  "owner": {
+    "name": "Himanshu Kurrey"
+  },
+  "plugins": [
+    {
+      "name": "trainjudge",
+      "source": ".",
+      "description": "Decide whether fine-tuning is the right fix, then verify it actually worked — on task metrics, not training loss."
+    }
+  ]
+}

trainjudge-0.2.1/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "trainjudge",
+  "description": "Decide whether fine-tuning is the right fix, then verify it actually worked — on task metrics, not training loss.",
+  "version": "0.2.1",
+  "author": {
+    "name": "Himanshu Kurrey"
+  },
+  "homepage": "https://github.com/Himanshukurrey/trainjudge"
+}

trainjudge-0.2.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug report
+description: Something isn't working as expected
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for filing a bug. If the problem is with a training run, the fastest way to get it looked at is
+        to attach the run's `run.json` (and `eval_results.json` if `verify` got that far). They record the model,
+        settings, dataset hash and results, without the dataset itself. Check them for anything private before
+        attaching.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What did you expect, and what actually happened instead?
+    validations:
+      required: true
+
+  - type: input
+    id: command
+    attributes:
+      label: Exact command you ran
+      placeholder: "trainjudge verify trainjudge-runs/2026-09-24-sql_generation"
+    validations:
+      required: true
+
+  - type: textarea
+    id: run-files
+    attributes:
+      label: run.json / eval_results.json (if you have them)
+      description: Drag and drop the files here, or paste the relevant output.
+
+  - type: input
+    id: version
+    attributes:
+      label: TrainJudge version
+      description: Output of `trainjudge --version`
+    validations:
+      required: true
+
+  - type: input
+    id: mlx-version
+    attributes:
+      label: mlx-lm version (for train/eval/verify issues)
+      description: Output of `pip show mlx-lm | grep Version`
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - macOS (Apple Silicon)
+        - macOS (Intel)
+        - Linux
+        - Windows
+        - WSL
+    validations:
+      required: true

trainjudge-0.2.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

trainjudge-0.2.1/.github/ISSUE_TEMPLATE/domain_pack.yml

@@ -0,0 +1,44 @@
+name: Domain pack request
+description: Ask for TrainJudge checks tailored to an industry (healthcare, legal, retail, ...)
+labels: ["domain-pack"]
+body:
+  - type: input
+    id: domain
+    attributes:
+      label: Domain
+      placeholder: "Healthcare"
+    validations:
+      required: true
+
+  - type: textarea
+    id: tasks
+    attributes:
+      label: What do people fine-tune for in this domain?
+      description: Typical goals, e.g. "extract diagnosis codes from clinical notes" or "answer questions about drug dosing".
+    validations:
+      required: true
+
+  - type: textarea
+    id: changing-facts
+    attributes:
+      label: Facts that change
+      description: Information that goes stale and should live in retrieval, e.g. clinical guidelines or prices.
+
+  - type: textarea
+    id: high-stakes
+    attributes:
+      label: High-stakes decisions
+      description: Decisions about people that shouldn't be fully automated, e.g. triage or candidate screening.
+
+  - type: textarea
+    id: sensitive-data
+    attributes:
+      label: Sensitive identifiers
+      description: IDs or formats that appear in this domain's data and should be masked before training.
+
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Contributing
+      options:
+        - label: I'd like to help build or review this pack

trainjudge-0.2.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,25 @@
+name: Feature request
+description: Suggest an idea for TrainJudge
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: What are you trying to do that TrainJudge can't help with today?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: What would you want TrainJudge to do instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any workarounds you're using today, or other tools that solve this.

trainjudge-0.2.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## What does this PR do?
+
+<!-- One or two sentences describing the change. -->
+
+## Why?
+
+<!-- What problem does this solve, or what issue does it close? Link it: "Closes #12" -->
+
+## How was this tested?
+
+<!-- Commands you ran, and what you expected vs. saw. If you added tests, mention them here.
+     If the change affects training or evals, say whether you ran it on real hardware (and which Mac). -->
+
+## Checklist
+
+- [ ] `pytest` passes locally
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] I added/updated tests for the behavior I changed (if applicable)
+- [ ] I updated the README if this changes user-facing behavior
+- [ ] If I changed a demo generator, I regenerated and committed its output

trainjudge-0.2.1/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

trainjudge-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,108 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # weekly, Monday 06:00 UTC
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Pushes to main run Linux only: macOS and Windows runner minutes are billed
+        # at 10x and 2x on private repositories. Pull requests, manual runs
+        # (`gh workflow run ci.yml`) and the weekly schedule run the full matrix.
+        os: ${{ github.event_name == 'push' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest", "windows-latest", "macos-latest"]') }}
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # The test suite never downloads models or needs mlx-lm: training and
+      # generation are exercised through fake backends, so CI runs everywhere.
+      - name: Install trainjudge and dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install trainjudge with dev tools
+        run: pip install -e ".[dev]"
+
+      - name: Run ruff check
+        run: ruff check .
+
+      - name: Run ruff format --check
+        run: ruff format --check .
+
+      - name: Type-check with mypy
+        run: mypy
+
+  demo-data:
+    # The committed demo datasets must match what their generators produce.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install trainjudge
+        run: pip install -e .
+
+      - name: Regenerate demo datasets
+        run: |
+          for demo in sql_generation policy_docs domains/bfsi/transactions domains/bfsi/loan_faq; do
+            python demo/$demo/generate.py
+          done
+          python demo/domains/generate.py
+
+      - name: Check nothing changed
+        run: git diff --exit-code -- demo/
+
+  torch-integration:
+    # Real LoRA training and generation with the PyTorch backend, on CPU with a
+    # tiny model, so a breaking transformers/peft release is caught here.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Cache the tiny test model
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/huggingface
+          key: hf-smollm2-135m-instruct
+
+      - name: Install CPU-only PyTorch and trainjudge
+        run: |
+          pip install torch --index-url https://download.pytorch.org/whl/cpu
+          pip install -e ".[dev,cuda]"
+
+      - name: Train and generate on CPU
+        env:
+          TRAINJUDGE_TORCH_INTEGRATION: "1"
+        run: pytest -v tests/test_torch_integration.py

trainjudge-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Publish to PyPI
+
+# Fires when a GitHub Release is published (gh release create / the "Publish
+# release" button), NOT on every tag push, so tagging alone can't trigger an
+# accidental publish. Uses PyPI Trusted Publishing (OIDC): no API token is
+# stored as a secret. One-time setup is required on PyPI before this works;
+# see "Releasing" in CONTRIBUTING.md.
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Sanity-check the built wheel actually installs and runs
+        run: |
+          python -m venv /tmp/trainjudge-release-check
+          /tmp/trainjudge-release-check/bin/pip install dist/*.whl
+          /tmp/trainjudge-release-check/bin/trainjudge --version
+          /tmp/trainjudge-release-check/bin/trainjudge audit demo/sql_generation/data.jsonl > /dev/null
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/trainjudge/
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

trainjudge-0.2.1/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+
+# Training outputs / model weights
+trainjudge-runs/
+adapters/
+*.safetensors
+.DS_Store
+
+# Local Claude Code settings
+.claude/settings.local.json

trainjudge-0.2.1/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+Instructions for coding agents (Codex and others that read `AGENTS.md`).
+
+## Using TrainJudge
+
+When the user asks to fine-tune, LoRA-train or distill a model, or asks whether
+a fine-tuned model is better than its base model, use the `trainjudge` CLI.
+Install it with `pip install "trainjudge[mlx] @ git+https://github.com/Himanshukurrey/trainjudge"`
+on an Apple Silicon Mac, or `[cuda]` on Windows/Linux with an NVIDIA GPU (install PyTorch with
+CUDA first). `diagnose` and `audit` run anywhere; with no GPU, use
+`notebooks/trainjudge_colab.ipynb` on Colab.
+
+1. **Diagnose before training.**
+   `trainjudge diagnose --dataset <path> --model <model> --goal "<goal>"`.
+   If the result is a KNOWLEDGE GAP (use retrieval) or a PROMPT-ENGINEERING GAP
+   (fix the prompt), tell the user TrainJudge recommends not fine-tuning and
+   only continue if they explicitly ask to. For a FORMAT/BEHAVIOR or
+   COST/LATENCY gap, ask before training, because it takes a while.
+2. **Respect sensitive-data refusals.** If `train` refuses because the audit
+   found card numbers, Aadhaar, PAN or similar identifiers, tell the user and
+   offer `--mask-sensitive`, which replaces them with placeholders like `[EMAIL]`
+   and trains on the masked rows. Never add `--allow-sensitive-data` unless the
+   user asks for it.
+3. **Train.** `trainjudge train --dataset <path> --model <model> --goal "<goal>"`.
+   Add `--replay 200` when general skills matter.
+4. **Verify.** `trainjudge verify <run-dir>` (add `--db <database>` for SQL tasks).
+5. **Report the verdict as-is.** IMPROVED means it worked. REGRESSED means the
+   task improved but general capability broke, so don't call it ready to
+   deploy. REJECTED means it didn't really improve, whatever the loss did.
+   Never claim improvement from training loss alone.
+
+**Long jobs: keep the user informed.** `train` and `verify` take minutes, and
+command output often isn't shown live. Run them in the background, then run
+`trainjudge status <run-dir> --watch --milestones`, which prints one line per
+milestone (stage started, 25/50/75%, stage done, finished or failed) and exits
+when the job ends. Relay each milestone to the user with what's next and the
+ETA, and report failures right away. Never go quiet until the result is in.
+
+Full details: [skills/trainjudge/SKILL.md](skills/trainjudge/SKILL.md).
+
+## Working on this repository
+
+- Setup: `pip install -e ".[dev]"` (add `mlx` on an Apple Silicon Mac, or `cuda` for the PyTorch backend).
+- Before finishing a change, run `pytest`, `ruff check .`, `ruff format --check .` and `mypy`.
+- Tests must not download models or need `mlx-lm` or `torch`, except
+  `tests/test_torch_integration.py` (opt-in, its own CI job). Use the fake backends in
+  `tests/test_training.py` and `tests/test_verify.py`.
+- `demo/*/data.jsonl`, `demo/*/docs/` and `demo/sql_generation/shop.sql` are
+  generated. Edit the matching `generate.py`, rerun it and commit both.
+- Always pass `encoding="utf-8"` when reading or writing text files; CI runs on Windows.

trainjudge-0.2.1/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## 0.2.1 (2026-09-26)
+
+### Fixes
+
+- **GPU memory is released after every generation pass** (PyTorch backend). PyTorch's caching
+  allocator kept the model's memory reserved after generating replay examples, so the training
+  subprocess ran out of memory loading its own copy; it also built up across `verify`'s eval
+  passes. Found on a Colab T4 with SmolLM2-1.7B, which now trains and verifies there.
+
+### Internal
+
+- Shared text helpers (`textutil.py`) replace duplicated think-block and duration code.
+- `cli.py` only parses options and prints; watching, summaries and the accuracy line live with
+  their modules.
+- mypy type-checks `src/` in CI.
+
+## 0.2.0 (2026-09-25)
+
+### Train and verify on NVIDIA GPUs, not just Macs
+
+- **PyTorch backend** (`--backend torch`): LoRA with transformers + peft on NVIDIA GPUs via CUDA
+  (Windows and Linux), Apple GPUs via MPS, or CPU. `--backend auto` keeps MLX on Apple Silicon and
+  uses PyTorch elsewhere. Both backends render prompts the same way, train with the loss on
+  completions only and report the same progress. Verified end to end on an NVIDIA T4.
+- **Colab notebook** (`notebooks/trainjudge_colab.ipynb`): diagnose, mask, train and verify on a
+  free GPU, for anyone without one.
+
+### Every domain, not just one
+
+- **Domain packs** for healthcare, legal, e-commerce/retail, customer support, HR/recruiting, BFSI
+  and education: facts that change (pointing to retrieval), high-stakes decision warnings and
+  domain notes. `--domain` forces or disables one.
+- **Demos for every pack**: a fine-tune case and a retrieval case per domain, 600 rows each for
+  the fine-tune cases so a real gain can be statistically significant.
+
+### Evals and verdicts
+
+- **JSON extraction eval**: exact match plus field-level and per-field accuracy. `eval` and
+  `verify` detect SQL or JSON from the test split (`--task` overrides), so every domain's
+  fine-tune demo can be verified.
+- **Baseline cache**: base-model evals are reused across runs with the same model, test split,
+  decoding and database. `verify --rerun` bypasses it.
+- Reports include a complete reproduce command and the device training actually used.
+
+### Data safety
+
+- **PII masking**: `train --mask-sensitive` and `audit --write-clean --mask-sensitive` replace
+  identifiers with placeholders (`[EMAIL]`, `[MRN]`, `[CARD]`…).
+- **Region-aware detection**: US SSNs, UK National Insurance numbers, IBANs (mod-97),
+  international and US phone numbers, labelled medical record numbers and dates of birth, on top
+  of cards, Aadhaar, PAN, UPI IDs and emails. Compliance pointers follow what was found.
+
+### Progress for people and agents
+
+- `trainjudge status --watch --milestones` prints one line per milestone, so agents can relay
+  progress even where command output isn't streamed (such as the Claude Code VS Code extension).
+
+### Fixes
+
+- Label-like answers are split per row, so no label is missing from training; paraphrase-style
+  answers stay grouped.
+- Status files survive Windows file locking; cleaned datasets always use LF line endings.
+
+### Other
+
+- Relicensed from MIT to Apache-2.0.
+
+## 0.1.0 (2026-09-24)
+
+First release: `diagnose` (knowledge / format / cost / prompt gap), `audit` (duplicates,
+malformed, low-quality and sensitive rows), `train` (MLX LoRA with held-out splits and
+`--replay`), `eval` (SQL execution accuracy), `verify` (IMPROVED / REGRESSED / REJECTED with a
+regression suite and reports), `status`, and a Claude Code plugin plus `AGENTS.md`.

trainjudge-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement Responsibilities
+
+The maintainer is responsible for clarifying and enforcing standards of acceptable behavior and will take appropriate, fair corrective action in response to unacceptable behavior.
+
+## Scope
+
+This Code of Conduct applies within all project spaces (issues, pull requests, discussions) and when an individual is officially representing the project elsewhere.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported by opening an issue or, for sensitive matters, via [GitHub's private vulnerability reporting](https://github.com/Himanshukurrey/trainjudge/security/advisories/new) as a stand-in private contact channel. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

trainjudge-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to TrainJudge
+
+Thanks for considering a contribution. Here's the workflow.
+
+## How to contribute
+
+1. **Fork the repo** and clone your fork locally.
+2. **Create a branch** for your change: `git checkout -b fix/short-description`.
+3. **Make your change**, with tests if you're changing behavior.
+4. **Run the test suite and linter** locally before opening a PR:
+   ```bash
+   pip install -e ".[dev]"
+   pytest
+   ruff check .
+   ruff format --check .
+   mypy
+   ```
+   CI runs the same checks on Linux, Windows and macOS, on Python 3.10 and 3.12. It also checks that the
+   committed demo datasets match their generators. Running these locally first saves a round trip.
+5. **Open a pull request** against `main`. Fill in the PR template: what the change does, why, and how you
+   tested it.
+6. A maintainer will review it. Please be patient; this is currently maintained part-time.
+
+## Tests don't need a GPU
+
+The test suite never downloads a model or needs `mlx-lm` or `torch`. Training and generation go through fake backends
+(see `fake_backend` in `tests/test_training.py` and `good_model` in `tests/test_verify.py`), so every test runs
+on any OS in a few seconds. If you change something that only shows up with a real model, such as prompt
+rendering, generation or backend flags, also run it on real hardware (an Apple Silicon Mac for MLX, or an
+NVIDIA GPU, Colab included, for PyTorch) and say so in the PR:
+
+```bash
+pip install -e ".[dev,mlx]"    # or .[dev,cuda] with --backend torch
+trainjudge train --dataset demo/sql_generation/data.jsonl --model Qwen3-0.6B --iters 20
+trainjudge verify trainjudge-runs/<run> --db demo/sql_generation/shop.sql
+```
+
+## Adding a domain pack
+
+Domain packs add industry-specific checks to `diagnose` (see the README's "Domain packs"
+section). To add one, say for healthcare:
+
+1. Create `src/trainjudge/domains/healthcare.py` defining `PACK = DomainPack(...)`, using
+   `domains/bfsi.py` as the template:
+   - `terms`: words that identify the domain in a goal or dataset. Prefer specific terms;
+     generic words like "claim" appear in many domains.
+   - `changing_fact_terms`, `changing_facts` and `changing_fact_note`: facts that change
+     and belong in retrieval.
+   - `high_stakes_terms` and `high_stakes_note`: decisions about people that shouldn't be
+     fully automated.
+   - `closing_notes`: anything else worth saying for this domain.
+2. Register it in `_load_packs()` in `src/trainjudge/domains/__init__.py`.
+3. Add tests showing it's detected from a goal, isn't detected on the other demos, and
+   produces its notes.
+4. Add a `FinetuneCase` and a `RetrievalCase` for the domain in `demo/domains/generate.py`,
+   run it, and add both demos to the table in `tests/test_demo_datasets.py`.
+
+Keep sensitive-data detectors in `src/trainjudge/pii.py` rather than in a pack, so every
+dataset is scanned whatever its domain. Compliance pointers should name the rule, not
+interpret it.
+
+The PyTorch backend also has a real integration test that trains a tiny model on CPU (it downloads
+about 270 MB the first time):
+
+```bash
+pip install -e ".[dev,cuda]"
+TRAINJUDGE_TORCH_INTEGRATION=1 pytest tests/test_torch_integration.py
+```
+
+## Demo datasets
+
+The files in `demo/*/` are generated, not hand-written. To change one, edit its `generate.py`, run it, and
+commit both the script and its output. Tests pin the exact number of injected duplicate, low-quality,
+malformed and PII rows, so update those counts too if you change them.
+
+## Why PRs go through review
+
+Every change lands through a reviewed pull request, so the project has a consistent, auditable history and a
+second pair of eyes on every change.
+
+## What makes a good PR
+
+- **Small and focused.** One logical change per PR is much easier to review than five unrelated fixes bundled
+  together.
+- **Tested.** If you fixed a bug, a regression test that would have caught it is the strongest evidence the
+  fix is real.
+- **Explained.** A one-line "fixed the bug" isn't enough. Say what was broken and why your change addresses
+  it.
+
+## Reporting bugs
+
+Open an issue describing what you expected vs. what happened, your OS, Python and backend (`mlx-lm` or `torch`) versions, and the
+exact command you ran. For problems with a run, attaching its `run.json` (and `eval_results.json`, if it got
+that far) is the fastest way to get it looked at. Check them for anything private first.
+
+## License of contributions
+
+TrainJudge is licensed under the [Apache License 2.0](LICENSE). By submitting a pull request, you
+agree that your contribution is licensed under the same terms (section 5 of the license).
+
+## Code of conduct
+
+Be respectful. Disagreements about code are fine; personal attacks aren't. See
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## Releasing (maintainer only)
+
+1. Bump `version` in `pyproject.toml`, `src/trainjudge/__init__.py`, `.claude-plugin/plugin.json` and the
+   version badge at the top of `README.md`, and add the release to `CHANGELOG.md`.
+2. `git tag vX.Y.Z && git push origin vX.Y.Z`
+3. `gh release create vX.Y.Z --generate-notes`
+
+Publishing that release triggers `.github/workflows/release.yml`, which builds the package, checks that the
+wheel installs and `trainjudge --version` and `trainjudge audit` run, and publishes to PyPI via
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (no stored API token).
+
+**One-time setup required before the first release**, done once on pypi.org by whoever owns the PyPI project:
+add a "pending publisher" for a project named `trainjudge` under Account Settings → Publishing, with:
+
+- Owner: `Himanshukurrey`
+- Repository: `trainjudge`
+- Workflow name: `release.yml`
+- Environment name: `pypi`
+
+This reserves the trust relationship before the package exists on PyPI, so the first `gh release create` can
+publish without a manual upload.