[cli] docs: corrections and improvements after a walk-through

Author: notunrandom

cli/README.md

@@ -2,8 +2,8 @@
 
 ## Context
 
-This is a command line interface (CLI) to track accesses to expensive resources. In particular we are focusing on the Cardano Foundation controlled Antithesis instance. The only command relative to the specific instance  is the `anti agent run-test` command, which is used to run tests on the Antithesis platform. The rest of the commands are independent of the resource. This CLI uses MPFS as a backend meaning all data is stored on the Cardano blockchain. ATM MPFS is only supporting preprod.
-The CLI should be used to book tests on the Antithesis platform. ATM it supports only projects on GitHub.
+This is a command line interface (CLI) to track accesses to expensive resources. In particular we are focusing on the Cardano Foundation controlled Antithesis instance. The only command relative to the specific instance  is the `anti agent run-test` command, which is used to run tests on the Antithesis platform. The rest of the commands are independent of the resource. This CLI uses MPFS as a backend meaning all data is stored on the Cardano blockchain. Currently MPFS is only supporting preprod.
+The CLI should be used to book tests on the Antithesis platform. Currently it supports only projects on GitHub.
 
 ## Prerequisites
 
@@ -61,8 +61,7 @@ export ANTI_PRETTY=1
 
 For scripting purposes you can disable the pretty effect of the env-var by passing `--no-pretty` switch.
 
-
-### Environment variables
+### Environment variables and preliminaries
 
 #### MPFS host
 If you do not want to host your own MPFS service, you can use a public one at `https://mpfs.plutimus.com`.
@@ -75,7 +74,7 @@ export ANTI_MPFS_HOST=https://mpfs.plutimus.com
 
 #### Your wallet
 
-ATM the anti CLI works only by reading a wallet file containing a mnemonic phrase.
+Currently the anti CLI works only by reading a wallet file containing a mnemonic phrase.
 
 The anti command will read the wallet file from the `ANTI_WALLET_FILE` environment variable.
 
@@ -131,21 +130,20 @@ anti wallet decrypt path/to/decrypted/secret/file
 
 For the both cases `ANTI_WALLET_FILE` is set as before.
 
+>  Store a copy of your encrypted/plaintext wallet file in a password manager. Think twice before storing a plaintext wallet file. Store your passphrase in a password manager too. Currently we do not support hardware wallets like Ledger or Trezor.
 
->  Store a copy of your encrypted/plaintext wallet file in a password manager. Think twice before storing a plaintext wallet file. Store your passphrase in a password manager too. ATM we do not support hardware wallets like Ledger or Trezor.
-
-`> Fund your wallet with some tAda tokens on preprod, for example using the [Cardano Testnet Faucet](https://docs.cardano.org/cardano-testnets/tools/faucet/).
+> Fund your wallet with some tAda tokens on preprod, for example using the [Cardano Testnet Faucet](https://docs.cardano.org/cardano-testnets/tools/faucet/).
 
 
-### Antithesis token
+#### Antithesis token
 
 This is the unique token that identifies the Antithesis access interface. You need to refer to it setting the `ANTI_TOKEN_ID` environment variable.
 
 ```bash
 export ANTI_TOKEN_ID=21c523c3b4565f1fc1ad7e54e82ca976f60997d8e7e9946826813fabf341069b
 ```
 
-### Set the timeout for the `anti` command
+#### Set the timeout for the `anti` command
 
 When submitting txs to the chain, it's quite convenient to wait for the transaction to be included in the chain, so that you can immediately use the result of the transaction.
 
@@ -155,7 +153,19 @@ To do that, you can set the `ANTI_WAIT` environment variable to the number of se
 export ANTI_WAIT=120
 ```
 
-## Querying the token state
+#### Configuring access to GitHub
+
+The tool will query the GitHub platform on your behalf in order to obtain (public) information about repositories (where Antithesis test runs are stored) and users (requesting a test run).
+
+In order to make this possible you must provide a GitHub Personal Access Token (PAT) for read-only access to public data. See the GitHub platform's documentation for how to create one.
+
+Provide your GitHub PAT to the tool by setting an environment variable:
+
+```bash
+export ANTI_GITHUB_PAT="github_pat_31A...<snipped>...xL"
+```
+
+### Querying the token state
 
 You can query the state of the Antithesis token with the following command:
 
@@ -169,7 +179,7 @@ This will show
 - the root of the mpf tree
 - the current UTxO of the state
 
-## Querying facts of the Antithesis token
+### Querying facts of the Antithesis token
 
 You can always query the Antithesis token and its facts
 

cli/docs/oracle-role.md

@@ -28,9 +28,13 @@ version=$(nix eval .#version --raw)
 docker run cardano-foundation/anti-oracle:$version
 ```
 
+## Running oracle commands manually
+
+Alternatively, oracle commands can be run manually, using the `anti` CLI. See the [README.md](../README.md) for how to install it.
+
 ## Creating the anti token (only once)
 
-Oracle operations needs a wallet. Given the role aside setting the `ANTI_WALLET_FILE` environment variable to point to the wallet file, you also wanto to set th `ANTI_WALLET_PASSPHRASE` environment variable to encrypt it.
+Oracle operations need a wallet. Since the oracle role is critical, in addition to setting the `ANTI_WALLET_FILE` environment variable to point to the wallet file, you should also set the `ANTI_WALLET_PASSPHRASE` environment variable to encrypt the wallet.
 
 You can create a wallet with the `anti wallet create` command.
 

cli/docs/requester-role.md

@@ -2,46 +2,55 @@
 
 This is the role of the user who wants to run tests using the Antithesis platform.
 
-Before you can request a test run, you need to register yourself as github user with an ed25519 public key.
+Before you can request a test run, you need to register yourself as GitHub user with an SSH ed25519 public key.
 
 ## Registrations
 
 A couple of requests have to be made once before the regular test-run requests can succeed. These requests are used to register the user and the project on the Antithesis platform.
 
-ATM we only support Github as a platform, but we plan to support other platforms in the future.
+Currently we only support GitHub as a platform, but we plan to support other platforms in the future.
 
-Registration and unregistrations can be requested by anyone. The oracle role will simply validate the facts against the Github platform and update the Antithesis token accordingly. You cannot register a user or project that is already registered.
+Registration and unregistrations can be requested by anyone. The oracle role will simply validate the facts against the GitHub platform and update the Antithesis token accordingly. You cannot register a user or project that is already registered.
 
-Be careful that there is no imperativity here, so i.e. you cannot unregister a user public key if it's present in Github.
+Be careful that there is no imperativity here, so i.e. you cannot unregister a user public key if it's present in GitHub.
 
 ### Registering a user public key
 
 To register yourself as a user, you can use the `anti requester register-user` command.
 
+You must provide (using the incorrectly-named `pubkeyhash` flag) the actual (base64-encoded) ed15519 public key (without the ssh-ed25519 prefix and without the optional key-id). So, for example, if your GitHub username is `alice` and you have configured this public key in your GitHub account:
+
+```bash
+$ cat ~/.ssh/id_ed25519.pub
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIO773JHqlyLm5XzOjSe+Q5yFJyLFuMLL6+n63t4t7HR8 [email protected]
+```
+
+then you should copy/paste the second field into the following command:
+
 ```bash
 anti requester register-user --platform github --username alice --pubkeyhash AAAAC3NzaC1lZDI1NTE5AAAAIO773JHqlyLm5XzOjSe+Q5yFJyLFuMLL6+n63t4t7HR8
 ```
 
-As with all other requests, once submitted regularly you have to wait for the oracle to merge your request into the Antithesis token.
+As with all other requests, once submitted you have to wait for the oracle to merge your request into the Antithesis token.
 
 You can use the `anti token` command to inspect your pending requests in the Antithesis token.
 
 You can use the `anti facts` command to query the Antithesis token and see if your user is part of the facts.
 
 ```bash
-anti token | jq '.requests' "
+anti token --no-pretty | jq '.requests'
 ```
 
-Until your requests is there, you cannot proceed with the next steps.
+As long as your request is listed by `anti token`, you cannot proceed with the next steps.
 
-As with all requests to an mpfs you can retract your request using the `anti retract` command, anytime before the oracle merges it into the Antithesis token.
+As with all requests to an MPFS you can retract your request using the `anti retract` command, anytime before the oracle merges it into the Antithesis token.
 
 Get the `outputRefId` of your request from pending requests command output and use it to retract your request
 
 ```bash
 anti retract -o 9ec36572e01bca9f7d32d791a5a6c529ef91c10d536f662735af26311b2c8766-0
 ```
-ATM the oracle is not able to justify a request rejection. But anti cli will apply the oracle validation before submitting it, so rejections will be caught before submitting the request.
+Currently the oracle is not able to justify a request rejection. But anti cli will apply the oracle validation before submitting it, so rejections will be caught before submitting the request.
 
 ### Unregistering a user public key
 
@@ -53,15 +62,15 @@ anti requester unregister-user --platform github --username alice --pubkeyhash A
 
 ### Registering a role
 
-This is necessary to register a user as a github repository antitheisis test requester.
+This is necessary to register a user as a GitHub repository antithesis test requester.
 
 Before you do this make sure your repository CODEOWNERS file contains a line like this:
 
 ```
 antithesis: @your-github-username
 ```
 
-You  can have as many user as you want but registering them as test-run requesters has to be done one by one.
+You can have as many users as you want but registering them as test-run requesters has to be done one by one.
 
 To register a role, you can use the `anti requester register-role` command.