docs: update README (#23)

* Simplify language around registering to use the Phylum app
* Update the examples to use long form options instead of short ones
  * Use literal block style and line continuation characters to be consistent
* Use more link references and format for line length

README.md

@@ -16,7 +16,7 @@ A GitHub Action using Phylum to automatically analyze Pull Requests for changes
 Phylum provides a complete risk analyis of "open-source packages" (read: untrusted software from random Internet
 strangers). Phylum evolved forward from legacy SCA tools to defend from supply-chain malware, malicious open-source
 authors, and engineering risk, in addtion to software vulnerabilities and license risks. To learn more, please see
-[our website](https://phylum.io)
+[our website](https://phylum.io).
 
 Once configured for a repository, this action will provide analysis of project dependencies from a lockfile during a
 Pull Request (PR) and output the results as a comment on the PR.
@@ -29,7 +29,7 @@ to meet the project risk thresholds for any of the five Phylum risk domains:
 * License (aka `lic`)
 * Author (aka `aut`)
 
-See [Phylum Risk Domains documentation](https://docs.phylum.io/docs/phylum-package-score#risk-domains) for more detail.
+See [Phylum Risk Domains documentation][risk_domains] for more detail.
 
 **NOTE**: It is not enough to have the total project threshold set. Individual risk domain threshold values must be set,
 either in the UI or with `phylum-ci` options, in order to enable analysis results for CI. Otherwise, the risk domain is
@@ -40,6 +40,8 @@ If one or more dependencies are still processing (no results available), then th
 job will only fail if dependencies that have _completed analysis results_ do not meet the specified project risk
 thresholds.
 
+[risk_domains]: https://docs.phylum.io/docs/phylum-package-score#risk-domains
+
 ## Prerequisites
 
 The GitHub Actions environment is primarily supported through the use of a Docker image.
@@ -54,30 +56,37 @@ The pre-requisites for using this image are:
     * Needs at least write access for `pull-requests` scope - see [documentation][scopes]
   * Can be a personal access token (PAT) - see [documentation][PAT]
     * Needs the `repo` scope or minimally the `public_repo` scope if private repositories are not used
-* A [Phylum token](https://docs.phylum.io/docs/api-keys) with API access
-  * [Contact Phylum](https://phylum.io/contact-us/) or create an account and register to gain access
-    * See also [`phylum auth register`](https://docs.phylum.io/docs/phylum_auth_register) command documentation
+* A [Phylum token][phylum_tokens] with API access
+  * [Contact Phylum][phylum_contact] or [register][app_register] to gain access
+    * See also [`phylum auth register`][phylum_register] command documentation
   * Consider using a bot or group account for this token
 * Access to the Phylum API endpoints
   * That usually means a connection to the internet, optionally via a proxy
   * Support for on-premises installs are not available at this time
 * A `.phylum_project` file exists at the root of the repository
-  * See [`phylum project`](https://docs.phylum.io/docs/phylum_project) and
-    [`phylum project create`](https://docs.phylum.io/docs/phylum_project_create) command documentation
+  * See [`phylum project`][phylum_project] and
+    [`phylum project create`][phylum_project_create] command documentation
 
 [container]: https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action
 [package]: https://github.com/phylum-dev/phylum-ci/pkgs/container/phylum-ci
 [gh_token]: https://docs.github.com/en/actions/security-guides/automatic-token-authentication
 [scopes]: https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes
 [PAT]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+[phylum_contact]: https://phylum.io/contact-us
+[app_register]: https://app.phylum.io/register
+[phylum_tokens]: https://docs.phylum.io/docs/api-keys
+[phylum_register]: https://docs.phylum.io/docs/phylum_auth_register
+[phylum_project]: https://docs.phylum.io/docs/phylum_project
+[phylum_project_create]: https://docs.phylum.io/docs/phylum_project_create
 
 ## Supported lockfiles
 
 If not explicitly specified, an attempt will be made to automatically detect the lockfile. Some lockfile types
 (e.g., Python/pip `requirements.txt`) are ambiguous in that they can be named differently and may or may not contain
 strict dependencies. In these cases, it is best to specify an explicit lockfile path by using the `phylum-ci --lockfile`
-option. The list of currently supported lockfiles can be found in the
-[Phylum Knowledge Base](https://docs.phylum.io/docs/analyzing-dependencies).
+option. The list of currently supported lockfiles can be found in the [Phylum Knowledge Base][supported_lockfiles].
+
+[supported_lockfiles]: https://docs.phylum.io/docs/analyzing-dependencies
 
 ## Getting Started
 
@@ -204,9 +213,9 @@ the local working copy is always pristine and history is available to pull the r
 
 The action inputs are used to ensure the `phylum-ci` tool is able to perform it's job.
 
-A [Phylum token](https://docs.phylum.io/docs/api-keys) with API access is required to perform analysis on project
-dependencies. [Contact Phylum](https://phylum.io/contact-us/) or create an account and register to gain access.
-See also [`phylum auth register`](https://docs.phylum.io/docs/phylum_auth_register) command documentation and consider
+A [Phylum token][phylum_tokens] with API access is required to perform analysis on project dependencies.
+[Contact Phylum][phylum_contact] or [register][app_register] to gain access.
+See also [`phylum auth register`][phylum_register] command documentation and consider
 using a bot or group account for this token.
 
 A [GitHub token][gh_token] with API access is required to use the API (e.g., to post comments).
@@ -216,7 +225,7 @@ Alternatively, it can be a [personal access token (PAT)][PAT] with the `repo` sc
 scope, if private repositories are not used.
 
 The values for the `phylum_token` and `github_token` action inputs can come from repository, environment, or
-organizational [encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets).
+organizational [encrypted secrets][encrypted_secrets].
 Since they are sensitive, **care should be taken to protect them appropriately**.
 
 The `cmd` arguments to the Docker image are the way to exert control over the execution of the Phylum analysis. The
@@ -225,6 +234,7 @@ defaulted to secure values. To view the arguments, their description, and defaul
 output as specified in the [Usage section of the `phylum-dev/phylum-ci` repository's README][usage] or more simply
 view the [script options output][script_options] for the latest release.
 
+[encrypted_secrets]: https://docs.github.com/en/actions/security-guides/encrypted-secrets
 [usage]: https://github.com/phylum-dev/phylum-ci#usage
 [script_options]: https://github.com/phylum-dev/phylum-ci/blob/main/docs/script_options.md
 
@@ -233,8 +243,8 @@ view the [script options output][script_options] for the latest release.
       - name: Analyze lockfile
         uses: phylum-dev/phylum-analyze-pr-action@v2
         with:
-          # Contact Phylum (https://phylum.io/contact-us/) or create an account and register to gain access.
-          # See also `phylum auth register` (https://docs.phylum.io/docs/phylum_auth_register) command docs.
+          # Contact Phylum (phylum.io/contact-us) or register (app.phylum.io/register) to gain access.
+          # See also `phylum auth register` (docs.phylum.io/docs/phylum_auth_register) command docs.
           # Consider using a bot or group account for this token.
           phylum_token: ${{ secrets.PHYLUM_TOKEN }}
 
@@ -265,13 +275,25 @@ view the [script options output][script_options] for the latest release.
           cmd: phylum-ci --lockfile requirements-prod.txt
           # Thresholds for the five risk domains may be set at the Phylum project level.
           # They can be set differently for CI environments to "fail the build."
-          # NOTE: The shortened form is used here for brevity, but the long form might be more
-          #       descriptive for future readers. For instance `--vul-threshold` instead of `-u`.
-          cmd: phylum-ci -u 60 -m 60 -e 70 -c 90 -o 80
+          cmd: |
+            phylum-ci \
+              --vul-threshold 60 \
+              --mal-threshold 60 \
+              --eng-threshold 70 \
+              --lic-threshold 90 \
+              --aut-threshold 80
           # Install a specific version of the Phylum CLI.
           cmd: phylum-ci --phylum-release 3.5.0 --force-install
           # Mix and match for your specific use case.
-          cmd: phylum-ci -u 60 -m 60 -e 70 -c 90 -o 80 --lockfile requirements-prod.txt --all-deps
+          cmd: |
+            phylum-ci \
+              --vul-threshold 60 \
+              --mal-threshold 60 \
+              --eng-threshold 70 \
+              --lic-threshold 90 \
+              --aut-threshold 80 \
+              --lockfile requirements-prod.txt \
+              --all-deps
 ```
 
 ## Example Comments