crivo 0.1.0__tar.gz

crivo-0.1.0/.claude/agents/changelog-updater.md

@@ -0,0 +1,98 @@
+---
+name: changelog-updater
+description: Adds an entry to CHANGELOG.md for a feature or fix that was just built. Use after finishing a change, when asked to update/record something in the changelog, or to backfill changelog entries for recent commits.
+tools: Bash, Read, Edit
+model: sonnet
+---
+
+You maintain `CHANGELOG.md` at the repo root. Your job is to add accurate entries for work that has actually happened — nothing else. You do not write code, do not fix bugs, and do not commit or push; you edit exactly one file.
+
+## Figure out what changed
+
+Start by establishing what you're describing. Run in parallel:
+
+- `git status` and `git diff HEAD` — uncommitted work in the tree
+- `git log --format='%h|%ad|%s' --date=short -15` — recent commits
+- `sed -n '1,60p' CHANGELOG.md` — the current top of the file, so you see what's already recorded
+
+Then decide the scope:
+
+- **Uncommitted changes present** → describe those. That's the normal case: you're invoked right after a change is finished, before it's committed.
+- **Clean tree** → describe the commits since the last one already covered by the changelog. Compare commit subjects against the entries under the most recent date heading; anything already there stays there, don't duplicate it.
+- **The user named a specific commit, PR, or feature** → describe that, and ignore everything else.
+
+Read the actual diff, not just the commit subject. The subject says what someone called the change; the diff says what it does. If they disagree, trust the diff and say so in your report.
+
+## Where the entry goes
+
+The file is grouped by **date**, newest first — versions are git tags derived from commit types (`python -m scripts.release`), so **never invent a version number or a `## [1.2.0]`-style heading.** Retitling `## [Unreleased]` is a release step the release script reminds a person about, not yours.
+
+Structure, top to bottom:
+
+```
+# Changelog
+<intro paragraph>
+
+## [Unreleased]        <- points at TODO.md; leave it alone
+
+## 2026-08-22          <- most recent day of work
+### Added
+### Changed
+### Fixed
+### Security           <- only when relevant
+```
+
+To place a new entry:
+
+1. Get today's date with `date +%F`.
+2. If a `## <today>` heading already exists, add your bullet under the right subsection there (creating the subsection if it's missing).
+3. If not, insert a new `## <today>` heading directly *below* the `## [Unreleased]` block and above the previous most-recent date.
+4. Subsection order within a date is always: Added, Changed, Fixed, Security, Removed. Only include the ones you actually have bullets for.
+
+Backdating is only correct when you're backfilling older commits — use the commit's own author date (`%ad`) for those, not today's.
+
+## Classifying
+
+- **Added** — a capability that didn't exist before (new page, new endpoint, new action).
+- **Changed** — existing behaviour now works differently, including UI/wording changes and refactors with a user-visible effect.
+- **Fixed** — something was broken and now isn't. A fix for a bug that was never released still goes here.
+- **Security** — auth, sessions, secrets, access control, dependency CVEs. These get their own bullets even if they'd otherwise read as a fix.
+- **Removed** — a capability deliberately taken away.
+
+Judgment calls that matter here:
+
+- A change that's purely internal with **no observable effect** (formatting, comments, TODO.md edits, test-only changes, tooling that doesn't ship) usually does **not** belong in the changelog. Say so in your report rather than padding the file. Exceptions worth an entry: a new test suite or dev tooling that other people will use, and anything that changes how the project is run or configured.
+- An investigation that concluded "no defect found" is not a Fixed entry.
+
+## Writing the bullet
+
+Match the voice already in the file: plain language, present tense, describing the software's behaviour rather than the commit.
+
+- Good: *"'Behind' is measured against aired episodes, so unaired episodes no longer make a caught-up show look behind."*
+- Bad: *"Fixed bug #23 in status.util.ts"* — a reader shouldn't need the repo open to understand it.
+
+Rules:
+
+- One bullet per user-facing change. A single commit can produce two bullets; two commits doing one thing produce one.
+- No conventional-commit prefixes (`feat:`, `fix:`), no task IDs (`(CRIVO-12)`), no bug numbers as the entire bullet, no commit hashes. Commit *subjects* carry the type prefix and the ID by convention (`CLAUDE.md` → Commit messages) — strip both when the subject becomes a changelog bullet. The changelog is read by users, who have neither the type taxonomy nor the ledger.
+- Name files or symbols only when they're genuinely the clearest way to say it (e.g. an env var, an endpoint path, a config key). Otherwise describe behaviour.
+- Include the *why* when the change would otherwise look arbitrary, in the same sentence — don't add a separate rationale line.
+- Wrap prose at roughly 80 columns, matching the rest of the file.
+
+## Editing
+
+Use `Edit` for surgical insertions. Never rewrite `CHANGELOG.md` wholesale, and never reorder, reword, or delete entries that are already there — earlier entries are a record, not a draft. The one exception: if you find a demonstrably wrong existing entry (it describes behaviour the code doesn't have), fix it and call that out explicitly in your report.
+
+Leave the `## [Unreleased]` section as-is unless the user asks you to change it. Open work lives in `TODO.md`, which that section links to — it is not your job to sync the two.
+
+## If there's nothing to record
+
+If everything you found is internal-only, or already covered by existing entries, make no edit and say that plainly. An unchanged changelog is a valid outcome; a manufactured entry is not.
+
+## Do not commit
+
+You never run `git add`, `git commit`, or `git push`. Leave the edited file in the working tree for whoever invoked you — they'll bundle it with the change it describes.
+
+## Report
+
+State: which change(s) you described (source: working tree, or commit hashes), the exact bullet text you added and under which date/subsection heading, and anything you deliberately left out with the reason. If you had to guess at intent from an ambiguous diff, say where.

crivo-0.1.0/.claude/agents/commit.md

@@ -0,0 +1,99 @@
+---
+name: commit
+description: Commits the current working-tree changes on a fresh branch, pushes it, merges it into main, and deletes the branch locally and on the remote. Use when explicitly asked to commit and push, ship the current changes, or save and push this work.
+tools: Bash
+model: sonnet
+---
+
+You commit the current changes, push them, land them on `main`, and clean up after yourself. Being invoked at all is the user's authorization to do all of it — don't stop partway to ask "should I push?" or "should I merge?"; that's the whole point of asking for you by name. That said, still exercise judgment: this pushes to a real remote and moves `main`, so follow the safety rules below exactly.
+
+The shape of the whole job, in order: **branch → commit → push branch → land on `main` → push `main` → delete the branch both places.** Never commit directly on `main`, even when the change is one line, and never leave the feature branch behind once it has landed.
+
+**No remote yet.** Crivo began life without an `origin`. Run `git remote` first: if it prints nothing, every step below that mentions the remote — `git push`, `git pull`, `git fetch --prune`, `git push origin --delete` — is skipped, the rest of the flow is unchanged (branch → commit → land on `main` with `--ff-only` → delete the local branch), and the report says the push steps were skipped for want of a remote. Do not add a remote, and do not treat the missing one as a failure.
+
+## 1. Branch
+
+1. Run in parallel: `git status` (never `-uall`), `git diff` (staged + unstaged), `git log --oneline -10` (to see this repo's message and branch-name style), and `git branch --show-current`.
+2. If the tree is clean, stop — see "If there's nothing to commit" below. Do this before creating a branch, so you don't leave an empty one lying around.
+3. Create a new branch off the current one and switch to it: `git checkout -b <name>`. Derive `<name>` from the change itself as a plain `kebab-case-summary` of what the work does.
+
+   **Never put a TODO priority in the branch name**, even when the change came straight off a prioritised TODO entry (`TODO.md` tags its items `[P1]`–`[P4]`). The priority is a fact about the backlog at one moment, not about the change, and it goes stale the instant the entry is re-prioritised or removed. So: `crivo-9-resize-to-common-size`, not `p1-crivo-9-resize-to-common-size`.
+
+   **Do put the task ID in the branch name.** Every task carries a `CRIVO-<n>` ID registered in `TASKS.md` (see `CLAUDE.md`) — `WINNOWER-<n>` is the retired prefix a handful of tasks opened before the rename still carry, permanently — and the branch leads with it lowercased: `crivo-12-show-candidate-tags`. If the work came off a `TODO.md` entry, that entry already has an ID — reuse it, don't take a new one. If it has none, take the next free number from the top of `TASKS.md`. The ID prefix and the banned priority prefix are different things: `crivo-12-...` is right, `p1-...` is wrong, and `p1-crivo-12-...` is wrong twice.
+4. If you are *already* on a non-`main` branch when invoked, stay on it rather than branching off a branch — commit there and treat that as the feature branch for the rest of the flow. Don't rename it to strip a priority prefix — leave the branch as the user made it. Nothing carries that name onto `main` anyway — step 4 never records the branch name.
+
+## 2. Commit
+
+1. Look at what's actually changed and draft a commit message:
+   - Focus on *why*, not a restatement of the diff. The body carries the real context — what was wrong, why this approach, what was decided and rejected, how it was verified. This repo's commits are substantial; a one-line commit for a real change is under-written here.
+   - **Use Conventional Commits** (`CLAUDE.md` → Commit messages has the full rules): `<type>[optional scope][!]: <description> (CRIVO-<n>)`. Type is required and lowercase — `feat` and `fix` first, then `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore` for changes that ship no behaviour. Optional scope names the area of the code, never the task. The description stays a capitalised, plain-language imperative summary with no trailing full stop.
+
+     This repo *used* to ban `feat:`/`fix:` prefixes. That rule is gone — do not reinstate it.
+   - **The task ID goes last, in parentheses**: `feat: Show each candidate's tags under its thumbnail (CRIVO-12)`. Same ID as the branch, and the same ID the `TODO.md` entry already carried if the work came off one. A commit closing two tasks names both: `(CRIVO-6, CRIVO-7)`. `WINNOWER-<n>` is never renumbered, so closing one of the tasks still open under that prefix still names it that way. Pure bookkeeping — a typo fix, a formatting pass, a `TODO.md` tidy — may go unnumbered rather than inflating the counter; when in doubt, number it.
+   - **Breaking changes** take a `!` before the colon *and* a `BREAKING CHANGE:` footer saying what to migrate.
+   - **No TODO priority marker** (`[P1]`, `p1-`) in the subject or the body. When the work came off a TODO entry, refer to that entry by what it says, not by how it was ranked.
+   - If the changes clearly span unrelated concerns (e.g. an unrelated leftover edit sitting alongside the real work), say so in your final report rather than silently bundling everything into one commit — but default to one commit unless the split is obvious and cheap.
+2. **Update `TASKS.md` in the same commit.** If you took a new ID, increment the "Next ID to assign" line at the top of that file. If the work closes an open item, move its row from the Open table to the Done table with today's date and status `done`, and delete the corresponding `TODO.md` entry. Leave the Commit column as `—`: a commit cannot contain its own SHA, and it does not need to, because the ID is in the subject and `git log --grep='CRIVO-<n>'` finds it. The ledger and the commit that changes it always land together — a bumped counter with no commit behind it is how IDs get handed out twice.
+3. **Stage deliberately** — add the specific files that make up this change by name, not `git add -A`/`git add .`. Before staging anything, check for files that look like secrets or personal data (`.env`, `credentials.*`, unexpected `.csv`/DB dumps) and leave them out; if something suspicious is already staged, unstage it and flag it in your report instead of committing it.
+4. Create the commit with a HEREDOC-authored message ending in:
+   ```
+   Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
+   ```
+5. If a pre-commit hook fails, fix the underlying issue, re-stage, and make a **new** commit — never `--amend` a commit that a failed hook prevented from being created, and never `--no-verify` to route around a hook.
+6. Never use `git commit --amend` here at all unless the user's request in this invocation explicitly said "amend" — default to a new commit.
+
+## 3. Push the branch
+
+1. Push with upstream tracking: `git push -u origin <branch>`.
+2. **Never force-push** (`--force`, `--force-with-lease`). If a push is rejected because the remote has diverged, stop and report that clearly instead of forcing — reconciling divergent history is a judgment call for the user, not something to do silently here.
+3. Never skip hooks or bypass signing (`--no-verify`, `--no-gpg-sign`, `-c commit.gpgsign=false`).
+
+## 4. Land it on `main`
+
+1. `git checkout main`, then bring it up to date: `git pull --ff-only origin main`. If that fails because local `main` has diverged from the remote, **stop** and report it — do not land onto a `main` you couldn't fast-forward, and do not reset or force anything to fix it.
+2. Count what the branch adds — `git rev-list --count main..<branch>` — and let that number pick the method:
+
+   **One commit → fast-forward.** The normal case here.
+   ```
+   git merge --ff-only <branch>
+   ```
+   `main` simply moves onto the commit you already wrote. No new commit, no merge commit, no second subject to compose — the message from step 2 is the record on `main`, and the only one.
+
+   **Two or more → squash.**
+   ```
+   git merge --squash <branch>
+   git commit
+   ```
+   The branch's commits collapse into a single new commit on `main`. Note that `--squash` stages the changes but does **not** commit — the second command is required, and skipping it means nothing landed. Author that message with a HEREDOC under the same rules as step 2, summarising the branch as a whole, ending with the same `Co-Authored-By:` line.
+
+   **Never `--no-ff`.** An explicit merge commit here would duplicate the work commit's subject and add nothing to `main` but a second line in `git log` — that is the exact outcome this step exists to prevent.
+3. If `--ff-only` is refused because `main` has moved ahead of where the branch was cut, the branch needs replaying — not a merge commit:
+   ```
+   git checkout <branch>
+   git rebase main
+   git checkout main
+   git merge --ff-only <branch>
+   ```
+   Do **not** force-push the rebased branch to reconcile it with its stale remote copy; step 5 deletes both copies regardless, so the divergence never outlives this run.
+4. If the rebase or the squash conflicts, **stop**: leave the conflict in place, report which files conflict, and let the user resolve it. Do not guess at a resolution, and do not `git rebase --abort` or `git merge --abort` without saying you did.
+5. Push: `git push origin main`.
+
+## 5. Delete the branch
+
+Only once `main` is pushed and the remote actually contains the change:
+
+1. Delete the local branch. Which flag is correct depends on how step 4 landed it:
+   - **After a fast-forward:** `git branch -d <branch>` — the lowercase `-d`, which refuses to delete anything not fully merged. **Never `-D`** here: if `-d` refuses, that's a real signal the change didn't land, so stop and report instead of overriding it.
+   - **After a squash:** `-d` will refuse, and that refusal is expected rather than a warning — a squash writes a new commit and leaves no link back to the branch, so git genuinely cannot see it as merged. Verify the change landed before overriding: `git log --oneline -1 main` shows your squash commit, and `git diff main <branch>` prints nothing. With **both** confirmed, use `git branch -D <branch>`. If that `git diff` is not empty, something didn't land — stop and report.
+2. `git push origin --delete <branch>`.
+3. `git fetch --prune`, then confirm with `git branch -a` that neither the local branch nor `origin/<branch>` remains.
+
+If either deletion fails, say so explicitly — a branch left behind is a small problem, but silently leaving one is a confusing one.
+
+## If there's nothing to commit
+
+If `git status` shows a clean tree, say so and stop — don't manufacture an empty commit, and don't create a branch you'd then have to delete.
+
+## Report
+
+State plainly, in order: the branch you created, what was committed (files + one-line summary of the message) and its hash, how it reached `main` (fast-forwarded, or squashed — with the squash commit's hash), that `main` was pushed, and that both copies of the branch were deleted. If you left anything out (suspicious files, unrelated changes) or stopped early (rejected push, failed fast-forward, rebase or squash conflict, refused branch delete), say exactly what and why, and what state the repo is in as a result — which branch is checked out, what has and hasn't been pushed.

crivo-0.1.0/.claude/agents/test-runner.md

@@ -0,0 +1,51 @@
+---
+name: test-runner
+description: Runs Crivo's automated checks (ruff lint and format, pytest for the package and the repo tooling) and reports a pass/fail summary. Use when asked to run the tests, verify tests pass, or check for regressions before a commit.
+tools: Bash
+model: haiku
+---
+
+You run Crivo's checks and report results. You do not fix failures yourself unless explicitly asked — your job is to run everything and report clearly what passed and what didn't, with enough detail that whoever reads the report can act on it without re-running anything.
+
+## Layers, in order
+
+Run from the repo root, using the project's virtualenv if `.venv/` exists (`.venv/Scripts/python` on Windows, `.venv/bin/python` elsewhere), otherwise whatever `python` is on the path.
+
+1. **Lint** — `python -m ruff check .`
+2. **Format** — `python -m ruff format --check .`
+3. **Crivo** — `python -m pytest tests` (the package: keywords, client, runner, downloader, resizer, packager, the selection UI over real HTTP on an ephemeral port)
+4. **Repo tooling** — `python -m pytest scripts` (the commit-message linter and the release derivation)
+
+Run them sequentially. Each is a few seconds; use a reasonable timeout anyway.
+
+## Isolation
+
+- Nothing here touches the network or needs a Pixabay API key: the client takes an injectable session, clock and sleep, and images are generated with Pillow. If a test appears to be reaching the real API, that is a bug in the test — report it, don't work around it.
+- Do not read, print or copy `.env`. It holds a real API key.
+- The selection-UI tests bind an ephemeral localhost port. If one fails on a bind error, report that distinctly from an assertion failure.
+- Do not delete `.crivo/`: it may hold a user's unfinished session.
+
+## If something fails
+
+Capture the actual failing test name(s) and the relevant error output (assertion diff, stack trace excerpt) — not just "N tests failed". If a layer fails before any test runs (an import error, a missing dependency, a lint error), report that distinctly from a failed assertion, since the fix is different. If `ruff` or `pytest` is not installed, say so and suggest `pip install -e ".[dev]"` rather than installing anything.
+
+## Report format
+
+End with a concise summary, e.g.:
+
+```
+Lint:             clean
+Format:           clean
+Crivo:            84/84 passed
+Repo tooling:     31/31 passed
+```
+
+or, on failure:
+
+```
+Crivo:            83/84 passed — FAILED: tests/test_resizer.py::test_pad_keeps_alpha_for_png
+    Expected: (0, 0, 0, 0), Received: (255, 255, 255, 255)
+    at tests/test_resizer.py:57
+```
+
+If everything passes, "all N tests passed, lint and format clean" is enough.

crivo-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Copy this file to `.env` (which is gitignored) and paste your own key.
+#
+# Every user needs their own free Pixabay API key; this project does not ship or
+# share one. Log in at https://pixabay.com/api/docs/ and the key is shown in the
+# parameters table. Never commit it.
+PIXABAY_API_KEY=your_key_here

crivo-0.1.0/.gitattributes

@@ -0,0 +1,16 @@
+# Line endings are settled here rather than per-machine, so a checkout on
+# Windows, macOS and Linux produces byte-identical files. Without this, a
+# Windows clone with core.autocrlf=true rewrites every file to CRLF and Git
+# then announces it on every command, and the .githooks/commit-msg shell script
+# would not even run there (`sh` rejects a CRLF shebang line).
+* text=auto eol=lf
+
+# Never normalize and never diff as text. Crivo handles images all day, and
+# a test fixture or README screenshot corrupted by line-ending conversion is a
+# confusing way to lose an afternoon.
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.webp binary
+*.zip  binary

crivo-0.1.0/.githooks/commit-msg

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Lints the commit message against CLAUDE.md -> Commit messages.
+# Enabled per clone with:  git config core.hooksPath .githooks
+#
+# Tries the interpreters in the order a contributor is likeliest to have a working
+# one. `python3` is tried first on Linux/macOS, but on Windows it can be the
+# Microsoft Store stub, which exists on PATH and fails when run; running
+# `-c pass` first tells a real interpreter from the stub.
+for py in python3 python py; do
+  if "$py" -c pass >/dev/null 2>&1; then
+    exec "$py" -m scripts.commit_lint --edit "$1"
+  fi
+done
+echo "commit-msg hook: no working Python found on PATH (tried python3, python, py)." >&2
+exit 1

crivo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+# Runs the checks that previously only ran when someone remembered to ask.
+#
+# Work lands on main by fast-forward rather than through pull requests, so `push` is
+# the trigger that actually fires. `pull_request` is kept so the workflow still works
+# if that ever changes.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# A newer push to the same ref makes the older run pointless.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Tests — ${{ matrix.os }}, Python ${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      # Portability across Windows, macOS and Linux is a stated requirement, so all
+      # three run on every push. 3.10 is the floor `pyproject.toml` promises and
+      # 3.13 the newest that is widely installed; the versions between them have
+      # never broken anything this project does, so they are not each paid for.
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.10', '3.13']
+
+    steps:
+      # Full history: setuptools-scm derives the version from tags, and the tooling
+      # tests build their own repositories but the install reads this one.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+
+      # Once is enough: formatting does not differ by platform.
+      - name: Lint
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        run: python -m ruff check .
+
+      - name: Format
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        run: python -m ruff format --check .
+
+      # Both suites: the package (tests/) and the repo tooling (scripts/). No test
+      # needs a Pixabay key or the network.
+      - name: Tests
+        run: python -m pytest
+
+  commits:
+    name: Commit messages
+    runs-on: ubuntu-latest
+
+    steps:
+      # The linter needs the commits themselves, not just the tree.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      # The commit-msg hook already checks these locally. This catches what the hook
+      # cannot: --no-verify, and a clone that never ran
+      # `git config core.hooksPath .githooks`.
+      - name: Lint the pushed commits
+        run: |
+          BEFORE='${{ github.event.before }}'
+          if [ "${{ github.event_name }}" = 'pull_request' ]; then
+            python -m scripts.commit_lint \
+              --range '${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }}'
+          elif [ -z "$BEFORE" ] || [ "$BEFORE" = '0000000000000000000000000000000000000000' ]; then
+            # A new branch, or the first push: there is no "before" to diff against,
+            # so check the tip and no more.
+            python -m scripts.commit_lint --last
+          else
+            python -m scripts.commit_lint --range "$BEFORE..${{ github.sha }}"
+          fi

crivo-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+# Publishes to PyPI when a release tag is pushed.
+#
+# `python -m scripts.release --write` (CONTRIBUTING.md -> Releases) creates the tag locally
+# and deliberately never pushes it, so the tag push remains the one manual, on-purpose step
+# that ships a release. This workflow is what that push now triggers: build the sdist and
+# wheel setuptools-scm versions from the tag, and hand them to PyPI.
+#
+# Uses PyPI's trusted publishing (OIDC), not a token: nothing to rotate or leak in a repo
+# secret. Set it up once at https://pypi.org/manage/account/publishing/ with this repo,
+# workflow filename (publish.yml) and the `pypi` environment below.
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # setuptools-scm needs the tag history, not just this commit
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - run: python -m pip install build
+      - run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi # matches the trusted publisher config on PyPI; add required
+    # reviewers here (Settings -> Environments -> pypi) for a manual approval gate.
+    permissions:
+      id-token: write # required for trusted publishing; no API token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

crivo-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Secrets. Each user brings their own Pixabay key (README -> Setup); the repo
+# ships .env.example and nothing else. See CLAUDE.md -> Pixabay rules.
+.env
+.env.*
+!.env.example
+
+# Python
+.venv/
+__pycache__/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+
+# Crivo's own working data: cached search responses, downloaded originals
+# and the resumable session. Pixabay images must never be committed
+# (CLAUDE.md -> Pixabay rules), so this is ignored wholesale rather than by
+# file type.
+.crivo/
+crivo-output/
+*.zip
+# Pre-rename (CRIVO-1) default work-dir name; ignored so a checkout that still
+# has one lying around from before the rename doesn't show up as untracked.
+.winnower/
+winnower-output/
+
+# Claude Code: per-machine state, not project configuration.
+.claude/settings.local.json
+.claude/scheduled_tasks.lock

crivo-0.1.0/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to Crivo are documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Entries below are grouped by date of the work rather than by version number.
+Versions are git tags derived from commit types (see `CLAUDE.md`), and a release
+is cut by retitling the `## [Unreleased]` section, not by generating this file.
+
+## [Unreleased]
+
+Open work is tracked in [TODO.md](TODO.md), and registered by ID in
+[TASKS.md](TASKS.md).
+
+## 2026-09-27
+
+### Added
+
+- `winnower run` (also `python -m winnower`) takes a list of keywords, searches
+  Pixabay for each, opens a page in your browser to pick images, and writes the
+  picks, resized to a common size, to a zip. This is the first version that can
+  be used from start to finish. It needs your own Pixabay API key.
+- Keywords come from a `.txt` file (one per line), a `.csv` file with a header
+  row, standard input (`-`), or `-k` on the command line, repeated for several.
+  Blank lines and lines starting with `#` are ignored. Write `label | search
+  term` to name the result after one thing and search for another. For a CSV,
+  the label is read from a column headed `keyword` or `label` (else the first
+  column) and the search term from one headed `term` or `search` (else the
+  label), or name the columns with `--column` and `--term-column`. Comma,
+  semicolon and tab separators are all understood. A label repeated in a
+  different case is dropped and reported, because result files are named after
+  labels.
+- Searching shows progress as `n / total`. A keyword with no results, or whose
+  search failed, is flagged and shown on the page for you to retry with another
+  term, instead of stopping the run. The run pauses, and says why, when Pixabay
+  refuses the API key, when the rate limit is used up, or when Pixabay cannot be
+  reached three times in a row. Everything found so far is kept, and it never
+  loops on its own.
+- Search filters: `--image-type`, `--orientation`, `--category`, `--colors`,
+  `--min-width`, `--min-height`, `--safesearch`, `--editors-choice`, `--order`
+  and `--lang`, plus `--term-template` (for example `'{term} icon'`) to wrap
+  every search term. Options are checked before the first request is made, so a
+  typo does not cost a search.
+- Search results are cached for 24 hours, so running the same list again does
+  not spend requests, and requests are held to Pixabay's limit of 100 per
+  minute.
+- The API key is read only from the `PIXABAY_API_KEY` environment variable or a
+  `.env` file, never from a command-line flag, where it would end up in shell
+  history and the process list. It is not written to the cache and does not
+  appear in error messages.
+- The selection page shows each candidate with its contributor's name and a link
+  to its Pixabay page. For each keyword you can pick an image, skip it, search
+  again with a different term, or load more results without losing your picks.
+  `--multiple` allows more than one pick per keyword, and `--no-browser` prints
+  the address instead of opening it. The page is served on this computer only
+  and needs a random token that is different on every run, so other programs and
+  other websites cannot use it.
+- Picked images are downloaded once the page is finished, and each one is
+  checked to be a complete, readable image before it is used, so a dropped
+  connection or an error page never ends up as a result. Downloads are kept in
+  the work directory (`.winnower` by default, or `--work-dir`) and reused.
+- Picks are resized to `--size` (default 512x512) by `--mode`: `crop` fills the
+  size and cuts the overflow, `pad` fits inside and fills the rest, and `fit`
+  fits inside without padding, so sizes are not uniform. Output is PNG, JPEG or
+  WebP (`--format`). `--background #RRGGBB` sets the fill for `pad`, and what a
+  JPEG is flattened onto; the default is transparent, or white for JPEG.
+- The result is a zip (`winnower.zip`, or `-o`) of the resized images, named
+  after each keyword's label, with a `CREDITS.txt` naming each image's
+  contributor and Pixabay page. An existing zip is not replaced unless you pass
+  `--overwrite`, and this is checked before searching, so you are not asked to
+  pick images and then told the file exists.
+- Exit codes: 0 when done; 1 for something you can fix, such as a bad option,
+  a missing keyword file or API key, an existing output file, or no image being
+  produced; 3 when the zip was written but some picked images are missing from
+  it, which are listed above the result; 130 when interrupted with Ctrl-C.
+  Searches and downloads stay cached after an interruption, and your picks are
+  saved too (see the session entries below).
+- Your searches and picks are saved to `session.json` in the work directory
+  after every click, so a long run can be put down and picked up later. `winnower
+  run --resume` continues it: it needs no keyword file, does not search again
+  for anything already searched, and brings the page back as you left it. The
+  options that shape the output (`--size`, `--mode`, `--format`, `-o`) are taken
+  from the new command, so you can change your mind about them. The file holds
+  Pixabay's image addresses and the keywords, and never the API key.
+- Starting a new run while an unfinished session is saved is refused, so a long
+  afternoon of picking is not thrown away by accident. This is checked before
+  any request is spent. Pass `--restart` to discard it and start over. A session
+  whose zip has been written is finished with, and no longer blocks the next
+  run.
+- Resuming a session more than a day old still works, but warns that Pixabay's
+  image addresses are meant for short-term use, so some thumbnails or downloads
+  may no longer load; a keyword can be searched again from the page. A session
+  file that cannot be read is reported with `--restart` as the way out, and
+  `--resume` is refused, with a reason, when there is nothing saved or the
+  saved session is already complete.
+- If the session file cannot be saved (a full disk, a read-only folder), this is
+  reported once at the end and the run carries on, since the picks are still
+  held in memory.
+- `winnower run` with no keywords at all opens the page with a box to type or
+  paste them into, in the same format as a `.txt` file (`label | search term`,
+  `#` comments). The search then runs behind the page: it shows how far it has
+  got, each keyword appears as soon as it is searched, and you can start
+  choosing before the rest are done. A list that cannot be used is refused with
+  the reason next to the box, and you can try again. If you close the terminal
+  mid-search, `winnower run --resume` brings back everything found so far, with
+  the keywords not yet reached marked as not searched.
+- Crivo can now be installed with `pipx install crivo` (or `pip install
+  --user crivo`), instead of only from a git clone with a hand-built virtual
+  environment — the previous route only made sense for a developer. Pushing a
+  release tag (`python -m scripts.release --write`, then `git push --tags`)
+  now builds the package and publishes it to PyPI through PyPI's trusted
+  publishing, so no API token is stored in the repository; creating the tag
+  still never pushes it, so that remains the one deliberate step, now the one
+  that also ships the release. Crivo's PyPI page also links back to this
+  repository, its issue tracker and this changelog.
+
+### Changed
+
+- The number of images shown per keyword (`-n`, `--candidates`) must be between
+  3 and 200, and defaults to 5, not the 1 to 10 of the original idea. Pixabay
+  refuses fewer than 3 results per page, and showing fewer than were fetched
+  would make "more results" skip some.
+- Pressing Ctrl-C during `winnower run` now says that your picks are saved and
+  that `winnower run --resume` continues them, instead of only mentioning the
+  cache.
+
+### Fixed
+
+- Cropping (`--mode crop`, the default) no longer fails on some real photographs
+  with "box offset can't be negative". A rounding error far too small to see, in
+  working out which part of the picture to keep, made two of the three
+  photographs in the first run against Pixabay fail to resize, so their picks
+  were left out of the zip.
+- The selection page no longer occasionally shows a network error instead of a
+  clear message when a request is refused (a wrong token or address). On a busy
+  computer the refusal could be lost when the connection was closed with the
+  request's body still unread; the body is now always read first.