Some cleanup

Author: dbutenhof

docs/Agent/agent.md

@@ -1,8 +1,11 @@
 # Pbench Agent
 
-The Pbench Agent manages performance experiments, controlling artificial
-benchmark execution and gathering additional performance data while they
-run.
+The Pbench Agent manages performance experiments and collects the data for
+analysis. The Agent CLI controls the execution of predefined synthetic
+benchmarks (such as fio and uperf) and allows execution of generic workloads
+(via [pbench-user-benchmark](user-guide/man_page.md#pbench-user-benchmark))
+while gathering and managing additional selected performance data
+([pbench-register-tool-set](user-guide/man_page.md#pbench-register-tool-set)).
 
 For more information, see [Getting Started](user-guide/getting_started.md)
 and [Man Page](user-guide/man_page.md).

docs/Dashboard/user_guide.md

@@ -17,7 +17,7 @@ It has three components.
 
 ![Overview](assets/images/Overview.png)
 
-The *User Profile* page can be used to view profile information from the OIDC authentication as well as to view and manage Pbench Server API keys. This page is accessed by selecting the *My profile* option from the dropdown menu activated by clicking on the username at the right end of the header bar.
+The _User Profile_ page can be used to view profile information from the OIDC authentication as well as to view and manage Pbench Server API keys. This page is accessed by selecting the *My profile* option from the dropdown menu activated by clicking on the username at the right end of the header bar.
 
 From this page, Pbench Server API keys can be created by clicking on the *New API Key* button; existing keys are listed with their labels and creation dates; and, the keys can be copied or deleted using the icon buttons.
 

docs/Server/API/access_model.md

@@ -19,12 +19,12 @@ the administrator *role*, can UPDATE or DELETE the dataset.
 
 ## User Identity
 
-The Pbench Server works with an external OIDC identity provider, for example
-Red Hat, Google, or GitHub SSO. The Pbench Server authenticates user access using
-the OIDC JWT tokens. The token's encoded `sub` field is the primary "user ID"
-controlling ownership of and access to data. The token's `preferred_username`
-field will be remembered and used when trying to report the "user ID" in human
-readable form.
+The Pbench Server must be configured with an external OIDC identity provider,
+such as Red Hat, Google, or GitHub. The Pbench Server authenticates user access
+by validating signed OIDC JWT tokens. The token's encoded `sub` field is the
+primary "user ID" controlling ownership of and access to data. The Pbench
+Server caches each token's `sub` UUID and `preferred_username` to translate
+user ID values back into human readable form.
 
 ## Roles
 

docs/Server/API/api.md

@@ -1,24 +1,24 @@
 # Pbench Server API documentation
 
-The Pbench Server API provides the interface to Pbench data for use by the UI
-dashboard as well as any other web clients.
+The Pbench Server API provides a RESTful HTTPS interface to curated Pbench
+performance data for use by the UI dashboard as well as any other web clients.
 
-The Pbench Server provides a set of HTTP endpoints to manage user
-authentication and curated performance information, called "dataset resources"
-or just "datasets". A dataset represents the aggregation of server artifacts
-associated with the results of a performance experiment, for example the
-benchmarked workload and tool data collected from `pbench-fio` or from
-`pbench-user-benchmark`.
+The performance results data associated with an experiment is collectively
+referred to as a "dataset". The dataset resource is initially defined by the
+".tar.xz" tar ball uploaded to the Pbench Server. The server extracts and
+creates metadata describing the dataset, and (if appropriate) indexes synthetic
+benchmark data in Elasticsearch to support later analysis.
 
-The [V1 API](V1/README.md) provides a RESTful functional interface oriented
-around the "dataset" resource.
+The [V1 API](V1/README.md) provides access to the original tar ball, the
+original performance results file structure within the tarball, Pbench Server
+[metadata](metadata.md), and the Elasticsearch indexed data.
 
 The Pbench Server APIs accept parameters from a variety of sources. See the
 individual API documentation for details.
 1. Some parameters, especially "resource ids", are embedded in the URI, such as
 `/api/v1/datasets/<resource_id>`;
 2. Some parameters are passed as query parameters, such as
-`/api/v1/datasets?name:fio`;
+`/api/v1/datasets?filter=server.benchmark:fio`;
 3. For `PUT` and `POST` APIs, some parameters may be passed as a JSON
 (`application/json` content type) request payload, such as
 `{"metadata": {"dataset.name": "new name"}}` or as an `application/octet-stream`