docs: update Arch Linux installation instructions in README

[SelfRef]

Type

• Hardware quirk (contrib/hw/*.toml)
• Bug fix
• Distribution packaging
• Documentation
• Other:

Description

This pull request updates the installation instructions for Arch Linux in the README.md to clarify package names, improve setup steps, and correct PAM configuration guidance.

Installation and setup improvements:

• Updated the AUR installation instructions to specify cloning the correct package (visage-git, visage, or visage-bin for release), and clarified the usage of makepkg and systemctl commands.
• Enhanced the enroll command to include the --user <your_username> option and added an explicit verification step with visage verify.

Configuration correction:

• Updated the PAM configuration example to use [success=done default=ignore] instead of [success=end default=ignore] for the pam_visage.so line.

[ccross2]

Thanks for picking this up — there's a real catch buried in here.

The success=end → success=done change is correct, and it's bigger than this PR: pam.conf(5) documents exactly ignore | bad | die | ok | done | reset | N. end isn't a valid PAM control keyword, which means libpam logs a warning and treats it as ignore — the visage auth result is silently dropped and the stack continues to pam_unix.so, so users get prompted for a password even on a successful face match. We've been shipping this since v0.1.0.

It appears in 9 places across the repo:

README.md:153
docs/operations-guide.md:117
docs/operations-guide.md:419
docs/architecture.md:603
docs/research/architecture-review-and-roadmap.md:176
docs/research/architecture-review-and-roadmap.md:321
docs/research/domain-audit.md:283
docs/research/howdy-analysis-and-visage-design.md:528
packaging/nix/module.nix:187
packaging/nix/module.nix:192
packaging/debian/pam-auth-update

A README-only fix would leave Debian (via pam-auth-update) and NixOS (via module.nix) users still hitting the bug. I'd like to land the PAM fix as a fleet sweep across all 9 sites in a separate PR rather than spread the correction over multiple commits. I'll open that this session and attribute the catch to you in the commit message.

Two more changes I'd push back on:

• git clone visage-git.git (or visage/visage-bin for release) — we only publish the stable visage PKGBUILD (packaging/aur/PKGBUILD). visage-git and visage-bin may exist as third-party AUR entries but aren't maintained by us; recommending them in our README without verifying they're current would be misleading. If you can point me at the AUR maintainers I'll happily document them, but until then I'd keep the visage package as the recommended path.
• visage enroll --label default --user <your_username> — --user defaults to $USER (crates/visage-cli/src/main.rs:35: "User to enroll for (defaults to $USER)"), so adding it as the default-shown form is noise rather than clarification. I'd drop the --user annotation unless we want to explain it's there for the cross-account enrollment case.

Two changes I'd be happy to land in this PR:

• The sudo systemctl enable --now visaged visage-resume line — solid, the resume unit exists and users should enable it.
• The visage verify step — good closing verification.

Proposal: would you mind amending to drop the --user annotation and the visage-git/visage-bin alternates? I'll land the PR with the PAM-keyword catch credited to you (Reported-by:), plus the resume-enable line and the verify step. Separately I'll do the fleet PAM sweep.

If you'd rather not amend, no problem — I can land your three good changes as a clean follow-up and credit you the same way. Either path closes this out cleanly; just want to make sure your catch lands properly.

[ccross2]

Follow-up — I owe you a correction on one part of my review.

I checked AUR and confirmed you're the maintainer of all three packages: visage, visage-git, and visage-bin. That makes you the de facto AUR maintainer of the whole Visage distribution lane on Arch — not a random third party recommending sibling packages. My pushback on "we only publish the stable visage PKGBUILD" was a categorical mistake on my part: while only the source PKGBUILD lives in our packaging/aur/ tree, the trust relationship for what we should recommend in the README is the AUR maintainer relationship, and that's you.

So the visage-git / visage-bin mention in the README is fine to land — please leave that part of your diff in. Apologies for the noise on that point.

The --user <your_username> ask still stands as the only request: crates/visage-cli/src/main.rs:35 documents --user as defaulting to $USER, so the default-shown form is genuine noise rather than a clarification. Either drop the --user annotation from the README example, or — if you want it documented — call out explicitly that it's only needed when enrolling for a different user (e.g., admin enrolling on behalf of someone). Your call.

Separately, if you'd be open to it: would you want to be added to CODEOWNERS for packaging/aur/ so future packaging changes route to your review automatically? You're already doing the work of keeping the AUR side current; would just make the trust relationship explicit in the repo.

The success=end → success=done catch from your PR is correct and going out in #31 (fleet sweep across all 9 sites). Credit preserved in that commit via Reported-by:. PR #31 has all-green CI and will land shortly.

[ccross2]

@SelfRef no rush on this — the PAM keyword fix from your review already landed in v0.3.2 via #31 (with credit to you). The remaining items in this PR are still useful; whenever you have time to look at the --user annotation question, we'll land it. If you'd rather we close + redo with Reported-by: credit, just say.

[SelfRef]

@ccross2 Thank you for the review.

I'm glad the PAM issue was fixed globally!

Separately, if you'd be open to it: would you want to be added to CODEOWNERS for packaging/aur/ so future packaging changes route to your review automatically? You're already doing the work of keeping the AUR side current; would just make the trust relationship explicit in the repo.

I'll be glad to help! Since I use this project personally, I'm actively maintain the packages anyway.

About the PR:
I've improved the instruction as you requested, clarifying packages and --user option. However, I've added this on purpose. I'm not sure if this is Arch-specific, but when I call sudo visage enroll --label default command I get:

Enrolling face model 'default' for user 'root'...
...

That's why in my case at least the --user option is mandatory to use during setup, since sudo apparently overrides what $USER is and enrolls model for root and not for user.

Shouldn't the app use $SUDO_USER as a main source instead and fallback to $USER? This variable stores the original login name of the user who invoked sudo.