docs: Address README feedback

Author: iinuwa

BUILDING.md

@@ -7,7 +7,7 @@ This project uses Meson, Ninja, and Cargo.
 We use Meson 1.5.0+. If your package manager has an older version, you can
 install a new version [using the pip module][meson-pip-install].
 
-There is currently no documented minimum support Rust version (MSRV), but 1.83+
+There is currently no documented minimum support Rust version (MSRV), but 1.85+
 should work.
 
 [meson-pip-install]: https://mesonbuild.com/Quick-guide.html#installation-using-python
@@ -60,7 +60,9 @@ sudo dnf install \
 
 # For Installing/Testing
 
-If you are interested in installing the program, you can use `meson install` to install the details.
+If you are interested in installing the program, you can use `meson install` to
+install the details. (If you would like to test without installing, you can
+follow the [build instructions for development](#for-development) below.)
 
 ```shell
 git clone https://github.com/linux-credentials/credentialsd
@@ -70,13 +72,22 @@ cd build-release
 meson install
 ```
 
-Note that since it Meson is installing to `/usr/local`, Meson will ask you to use `sudo` to elevate privileges to install.
+Note that since Meson is installing to `/usr/local`, it will ask you to use
+`sudo` to elevate privileges to install.
 
-The first time you run this, you must log out and log back in again to restart the D-Bus session bus for it to automatically start the D-Bus services on-demand.
+## Running the installed server
 
-### Testing with Firefox Web Add-On
+When using the installed server, systemd or D-Bus should take care of starting
+the services on demand, so you don't need to start it manually.
 
-Note: If you are testing the Firefox web extension, you will need to link the native messaging manifest to your home directory, since Firefox does not read from `/usr/local`:
+The first time you install this, though, you must log out and log back in again
+for the service activation files to take effect.
+
+## Testing installed builds with Firefox Web Add-On
+
+Note: If you are testing the Firefox web extension, you will need to link the
+native messaging manifest to your home directory, since Firefox does not read
+from `/usr/local`:
 
 ```shell
 mkdir -p ~/.mozilla/native-messaging-hosts/
@@ -92,7 +103,7 @@ meson setup -Dprofile=development build
 ninja -C build
 ```
 
-## Running the server
+## Running the server for development
 
 To run the required services during development, you need to add some
 environment variables.
@@ -105,6 +116,11 @@ export RUST_LOG=credentialsd=debug,credentials_ui=debug
 ./build/credentialsd-ui/target/debug/credentialsd-ui
 ```
 
+## Testing development builds with Firefox Web Add-On
+
+If you are using the Firefox add-on to build, follow the instructions for
+development in [`webext/README.md`](/webext/README.md#for-development).
+
 # For Packaging
 
 There are a few Meson options to control the build that may be useful for packagers.

GOALS.md

@@ -1,8 +1,23 @@
 # Goals
 
-The goal of this repository is to define a spec for clients (apps, browsers,
-etc.) to retrieve user credentials in a uniform way across Linux desktop
-environments.
+The goal of this repository is to define a spec and implementation for clients
+(apps, browsers, etc.) to retrieve user credentials in a uniform way across
+Linux desktop environments.
+
+## Motivation
+
+Our primary motivation is to get passkey into the hands of users. Passkeys are
+growing as a powerful authentication mechanism for users. As the ecosystem
+becomes more mature, browsers are deferring access to passkeys to OS APIs on
+other platforms, like Windows Hello, Keychain on macOS and iOS, and
+Credential Manager on Android.
+
+On Linux, there is no OS API so handling passkeys is entirely up to the browser,
+which is at a disadvantage to the OS in terms of hardware access and desktop
+integration. This situation also requires each individual browser or application
+to reimplement the same features. We want to change that!
+
+## Direction
 
 Some high-level goals:
 
@@ -25,7 +40,8 @@ Some non-goals:
 
 - Fully integrate with any specific desktop environment. Each desktop
   environment (GNOME, KDE, etc.) has its own UI and UX conventions, as well as
-  system configuration methods (e.g., GNOME Settings), which this API will need to integrate with.
+  system configuration methods (e.g., GNOME Settings), which this API will need
+  to integrate with.
   Because of the variation, we intend to leave integration with these other
   components to developers more familiar with each of the desktop environments.
   For now, we are using bare GTK to build a UI for testing, but any UI
@@ -42,7 +58,7 @@ Some non-goals:
   process is transparent enough that someone else could design something that
   works for BSDs.
 
-## Current Work
+## Progress
 
 - April 2025: Added web extension for testing in Firefox.
 - March 2025: Integrated libwebauthn to support USB authenticators.

README.md

@@ -4,12 +4,18 @@ A Linux Credential Manager API.
 
 (Previously called `linux-webauthn-platform-api`.)
 
+## Goals
+
+The primary goal of this project is to provide a spec and reference
+implementation of an API to mediate access to web credentials, initially local
+and remote FIDO2 authenticators. See [GOALS.md](/GOALS.md) for more information.
+
 ## How to install
 
 ### From packages
 
 We have [precompiled RPM packages for Fedora and openSUSE][obs-packages] hosted
-by Open Build Services (OBS). We also copy these for released versions to the
+by the Open Build Service (OBS). We also copy these for released versions to the
 [release page][release-page].
 
 There are several sub-packages:
@@ -63,12 +69,6 @@ cd demo_client/
 
 There is also a demo web extension that can be used to test the service in Firefox. Instructions are in [/webext/README.md]().
 
-## Goals
-
-The primary goal of this project is to provide a spec and reference
-implementation of an API to mediate access to web credentials, initially local
-and remote FIDO2 authenticators. See [GOALS.md](/GOALS.md) for more information.
-
 ## Mockups
 
 Here are some mockups of what this would look like for a user: