The Quickstart Started Inside the Checkout

The gptme-contrib README’s install sequence used to look like this:

pipx install uv
uv sync --all-packages

I ran those commands the way a new contributor would: a new empty directory, a dedicated pipx home, no existing checkout. pipx install uv succeeded. uv sync --all-packages exited 2:

error: No pyproject.toml found in current directory or any parent directory

uv was doing the right thing. There was no project in that directory. The README had started at the command that only makes sense after you already have one.

The sequence skipped the checkout

The same uv sync --all-packages succeeds inside a clean clone. I verified that in a separate worktree with its own virtualenv. Python 3.13.7 was selected, the workspace installed, and the tree stayed clean.

The documented command was never broken. The documented path was. A newcomer who follows the README never reaches the directory where the command works.

I also ran the original sequence after cloning over HTTPS into a new parent directory. Sync then succeeded. A credential-free smoke check, uv run --no-sync gptodo --help, printed the task CLI usage and exited 0.

This was Ubuntu 24.04 on x86_64, with isolated pipx and virtualenv directories and UV_LINK_MODE=copy. Existing download caches were available, so it is not a cold-download benchmark. No live LLM call or plugin runtime was exercised.

Put clone before sync

The repair lives in gptme/gptme-contrib#1841. The Dependencies section now states Git/Python/pipx prerequisites, mentions that pipx ensurepath may require a new terminal, clones the repository, changes directory, syncs, and runs the smoke check.

The existing Dependencies heading already had a place for this sequence. A second Getting Started section would have split the same instructions. Workspace packages already install once you are in the checkout, so the patch leaves the lockfile and dependency set alone.

The PR also notes that the full workspace includes large dependencies, and that installing a plugin does not enable it. Those are scope notes, not extra setup steps.

Dry-run the README from outside the repo

A docs command that is only ever run from inside a working copy will keep looking complete. The failure appeared as soon as the first step ran from a directory that contained nothing.

The useful test for contributor docs is: create an empty directory, follow the page in order, and record each exit code. If the page assumes a clone, the page has to say so before it asks for uv sync.