Refresh README and move detail into docs#13
Merged
OneNoted merged 11 commits intouinput-foundationsfrom Apr 15, 2026
Merged
Conversation
Move install, CLI, and troubleshooting detail out of the README so the front page stays focused while the deeper docs remain aligned with the current command surface and distribution paths.
Constraint: README should stay concise without hiding operational guidance
Constraint: Documentation claims must match the current CLI, release workflow, and package metadata
Rejected: Keep all reference material in README | harder to scan and easier to let drift
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Re-check README install claims against release assets, AUR packages, and CLI help before future doc refreshes
Tested: cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test; markdown local link check; verified GitHub release v0.2.2 and AUR package pages for whispers{-bin,-git,-cuda-bin,-cuda-git}
Not-tested: GitHub web markdown rendering
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3ad819b3c2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ``` | ||
|
|
||
| Use these when you want the CUDA-enabled local path from the AUR. | ||
| For the full package matrix, prerequisites, and post-install notes, see [docs/install.md](docs/install.md). |
There was a problem hiding this comment.
This link now points users to docs/install.md, but the release/packaging outputs that most users read do not ship the docs/ directory: scripts/build-release-bundle.sh only copies README.md and config.example.toml into share/doc/whispers (lines 66-69), and Cargo.toml’s include list also omits docs/** (lines 12-23). As a result, the install/CLI/troubleshooting links in the packaged README are dead for release bundles and downstream packages that install that README, removing the detailed instructions that were moved out of the README in this commit.
Useful? React with 👍 / 👎.
Record whether the udev reload step actually succeeded and only give the relogin-only setup message when that prerequisite is met. Also wait for udev to settle before the immediate post-setup readiness probe so fresh setups are judged against the updated device node state. Constraint: Setup should not tell users that relogging alone will fix paste injection after a failed udev reload Constraint: The post-setup readiness probe runs immediately after the helper returns Rejected: Trust the follow-up readiness probe alone | it cannot distinguish a stale device node from a reload failure Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep setup messaging tied to the actual side effects that completed, not just the current readiness snapshot Tested: cargo test setup::tests:: -- --nocapture; cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test Not-tested: End-to-end sudo/udev behavior on a live system
Remove duplicated relogin-guidance branching from the setup reporting path so the immediate setup output and the final completion message both derive from the same recorded outcome. This keeps the recent udev-readiness fix easier to follow without changing the guarded behavior. Constraint: Cleanup stays scoped to the recent setup readiness fix files Constraint: Group-change guidance must still reflect whether the udev reload succeeded Rejected: Leave the branching duplicated in each reporting callsite | easier for the messages to drift again Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep setup messaging decisions attached to InjectionSetupOutcome instead of recomputing them ad hoc in each UI path Tested: cargo test setup::tests:: -- --nocapture; cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test Not-tested: End-to-end sudo/udev behavior on a live system
Treat a setup rerun the same as a same-run group change when the user is already configured for the uinput group and the current run successfully reloads udev. This keeps the final setup summary aligned with the real remaining recovery step without reviving the earlier failed-reload bug. Constraint: Relogin-only guidance must stay blocked after a failed group membership change or failed udev reload Constraint: The fix should stay scoped to the setup outcome/report path and regression tests Rejected: Infer group readiness from changed_groups alone | misses reruns and manual prior membership Confidence: high Scope-risk: narrow Reversibility: clean Directive: Track whether setup left the user correctly configured for the uinput group instead of inferring that only from whether this run changed group membership Tested: cargo test setup::tests:: -- --nocapture; cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test Not-tested: Live sudo/udev behavior
Require read-write access when probing /dev/uinput so preflight matches the real virtual-device builder, and resolve existing uinput groups through NSS instead of only /etc/group. This keeps setup guidance accurate on systems with stricter device permissions or non-local group sources. Constraint: Injection preflight must reflect the same access mode the virtual keyboard actually needs Constraint: Group discovery must honor NSS-backed sources used by the rest of setup Rejected: Keep a write-only probe and /etc/group scan | both can report false readiness in real environments Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep setup and preflight environment checks aligned with the runtime code paths and NSS-backed identity lookups Tested: cargo test inject::tests:: -- --nocapture; cargo test setup::tests:: -- --nocapture; cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test Not-tested: Live sudo/udev behavior and NSS-backed groups outside the local test environment
Suppress stale manual fix steps when setup has already reached the relogin-only state, and make username lookup retry when NSS reports the passwd buffer hint was too small. This keeps the automatic uinput setup path consistent across reruns and larger NSS-backed passwd records. Constraint: Relogin-only guidance must not repeat manual setup steps that already succeeded Constraint: Username lookup must retry when NSS says the passwd buffer hint was too small Rejected: Keep printing readiness fix lines unconditionally | contradicts the final setup summary when only relogin remains Rejected: Trust a single getpwuid_r buffer attempt | NSS backends can still return ERANGE after the size hint Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep setup reporting aligned with the actual remaining recovery step, and treat NSS buffer-size hints as advisory Tested: cargo test setup::tests:: -- --nocapture; cargo test inject::tests:: -- --nocapture; cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test Not-tested: Live sudo/udev behavior and large NSS passwd records outside the test environment
Only activate the new uinput rule once the user is actually ready for it, and keep relogin-only guidance gated on the rule being in place. This prevents partial setup failures from regressing access or hiding the remaining manual work. Constraint: Reloading udev must not switch /dev/uinput to the new group before membership is ready Constraint: Relogin-only guidance must stay blocked when the udev rule still is not in place Rejected: Always reload udev after touching setup files | can activate the new group rule before membership exists Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep setup outcome state explicit enough to distinguish relogin-only cases from incomplete privileged setup Tested: cargo test setup::tests:: -- --nocapture; cargo test inject::tests:: -- --nocapture; cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test Not-tested: Live sudo/udev behavior on a host that still relies on legacy input-group access
Prevent `whispers setup` from short-circuiting on root-only `/dev/uinput` readiness, which can otherwise report success without configuring the actual desktop user. Constraint: Automatic uinput setup should be evaluated for the real desktop user, not sudo-root permissions Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep setup privilege checks explicit so root-only readiness can never masquerade as user readiness Tested: cargo test setup::tests:: -- --nocapture Not-tested: Live sudo invocation
Keep the bundled and packaged README links valid by shipping the docs pages it references in release bundles and Cargo package contents. Constraint: Packaged README links should not point to files that are omitted from shipped artifacts Confidence: high Scope-risk: narrow Reversibility: clean Directive: If README starts linking to new local docs, add those files to package and release artifact manifests in the same change Tested: cargo package --list --allow-dirty; scripts/build-release-bundle.sh with temp dist dir (verified docs in tarball) Not-tested: GitHub release workflow end-to-end
Reject `whispers setup` at the start of the setup flow when it is launched as root so it cannot mutate config or starter files before reporting the privilege error. Constraint: Root-only setup runs must fail before any local state is written Rejected: Leave the root guard inside the later injection setup helper | config and starter files can already be mutated before that point Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep the root guard at the top of `run_setup()` so later helpers cannot become the first failing point again Tested: cargo test setup::tests:: -- --nocapture; cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test Not-tested: Live sudo invocation
Make the non-zero clipboard test consume stdin before exiting so CI reliably exercises the intended non-zero exit path instead of racing into a broken-pipe write. Constraint: The test should still cover the non-zero exit path, not the broken-pipe write path Confidence: high Scope-risk: narrow Reversibility: clean Directive: Keep subprocess tests deterministic by making the child process consume the expected I/O before exiting Tested: cargo test inject::tests:: -- --nocapture; cargo fmt --all -- --check; cargo check --all-targets; cargo clippy --all-targets -- -D warnings; cargo test Not-tested: GitHub Actions rerun still pending
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/Verification
cargo fmt --all -- --checkcargo check --all-targetscargo clippy --all-targets -- -D warningscargo testStacked on #12.