Conversation
A sweep after the update client, the candidate workflow and the bill of materials landed. Every change here is either a claim that had stopped being true or a thing the checkout does that nothing documented. Two statements were actively wrong, both falsified by the SBOM work: that the build inventories are "not a complete third-party license inventory or SBOM", and that a release-ready inventory and SBOM "remain separate work". The release plan still said the in-app check was deferred, and its scope freeze still listed auto-update flatly. That one needed splitting rather than deleting: the check is automatic, installing never is, and a silent background update is still out of scope, which is a more useful sentence than either "deferred" or nothing. The README listed `update` in the commands table and explained it nowhere. It now has a section covering what is verified before anything runs and, more importantly, that an update never closes a running Offloader, which is the guarantee rather than a limitation. The documentation index gains updates.md. The agent guide's code map listed none of the installation or update modules, so a reader looking for where maintenance lives had to grep. It now names installation.py, installation_lock.py, update.py and gui/updates.py together with the rule that binds them: neither may force-close a running transfer. Its start-here list points at build-windows.md and updates.md, and says that a build being implemented is not a release being possible, since that is the distinction the plan keeps having to restate. The roadmap still listed a Windows installer and code signing as future work when the packaging is implemented. Replaced with what is actually left, none of which is code: the hardware token, a clean machine, and the Qt LGPL/GPL decision the notices file flags on every build. Added a dated source-validation record, labelled as exactly that. Nothing was frozen, signed or installed in it, so it establishes none of the gates it sits above. Checked rather than assumed: all 68 relative links across the markdown docs resolve, every CLI subcommand appears in the commands table, and every `offload` flag is mentioned in the README.
owenpkent
left a comment
There was a problem hiding this comment.
Reviewed the five documentation changes against the implementation in this head, including Windows build/release status, updater behavior, profile/media-tool boundaries, and the stated safety limits.
No independent non-sensitive code defect is introduced by this documentation-only diff. One newly repeated updater-protection claim needs to wait for the underlying correction identified on #13; its exact claim and call-path evidence are included in the private updater/documentation notes under SECURITY.md.
Validation: static documentation/code consistency review and git diff --check, which passed. Recorded CI is green. No local test suite was rerun for this documentation-only review, and the review does not treat implemented packaging scripts as evidence that signing or clean-machine qualification has passed.
…ring This branch exists to make the docs describe the checkout, and one of the claims it added does not. README, the release plan and updates.md all present "offloader update finds a release" as working, and the version ordering section explains at length that prereleases are ordered rather than rejected. The endpoint underneath is /releases/latest, which GitHub documents as returning the newest published full release and excluding prereleases. The first packaged release is planned as 0.1.0b1, so an installed beta cannot discover its successor, and a repository holding only the betas the candidate workflow publishes with --prerelease answers with nothing at all. The ordering is right; the endpoint is wrong. All three places now say so and point at the correction pending on #13, and the release plan no longer counts discovery as a gate that can be signed off. Nothing here claims the fix: it states the limit as the checkout currently has it, which is what this branch is for.
Summary
A sweep after the update client, the candidate workflow and the bill of materials. Every change is either a claim that had stopped being true, or something the checkout does that nothing documented. Docs only; no code touched.
Claims that were actively wrong
Both falsified by #16:
build-windows.md: the build inventories are "not a complete third-party license inventory or SBOM"build-windows.md: "A release-ready third-party license inventory and SBOM remain separate work"And in
release-plan.md, the in-app check was still described as deferred after #15 shipped it.One that needed splitting rather than deleting
The scope freeze listed "auto-update" flatly. That is now misleading in both directions, so it reads:
More useful than either "deferred" or silence, and it holds the line that matters.
Gaps where the code had no documentation
updatein the commands table and explained it nowhere. It now has a section: what is verified before anything runs, and that an update never closes a running Offloader — the guarantee, not a limitation.docs/updates.mdadded to the documentation index.installation.py,installation_lock.py,update.pyandgui/updates.pytogether with the rule binding them: neither may force-close a running transfer. Its start-here list points atbuild-windows.mdandupdates.md, and states that a build being implemented is not a release being possible — the distinction the plan keeps having to restate.Validation record
Added a dated source-validation entry (855 passed, 12 skipped, lint clean, sdist checked), labelled as exactly that: nothing was frozen, signed or installed, so it establishes none of the gates it sits above. Per
AGENTS.md, counts come from an actual run and a source run is not bundle qualification.Scope note
shellicon.py,shellmenu.pyandgui/file_list.pyare not in the code map here, because they exist only on the other stack (#11, #12). Documenting them on this branch would describe modules the branch does not contain. They need their own sweep on that stack — happy to do it, but it has to be a separate PR or the two conflict.Checked, not assumed
offload,report,verify,info,gui,update,resolve,control) appears in the commands table--flagofoffloadis mentioned in the README