[cli] Update docs

Author: paolino

cli/README.md

@@ -93,13 +93,13 @@ export ANTI_WALLET_PASSPHRASE
 You can create a wallet file with the `anti wallet create` command:
 
 ```bash
-anti wallet create
+antij wallet create
 ```
 
 It will fail to re-create the file if it already exists. You can review this wallet info anytime with
 
 ```bash
-anti wallet info
+antij wallet info
 ```
 
 Remember to read your wallet passphrase into the `ANTI_WALLET_PASSPHRASE` environment variable before running any command that requires the wallet.
@@ -126,13 +126,48 @@ To do that, you can set the `ANTI_WAIT` environment variable to the number of se
 export ANTI_WAIT=120
 ```
 
+## Querying the token state
+
+You can query the state of the Antithesis token with the following command:
+
+```bash
+antij token
+```
+
+This will show
+- the token owner a.k.a. the oracle identity
+- the pending change requests
+- the root of the mpf tree
+- the current UTxO of the state
+
 ## Querying facts of the Antithesis token
 
 You can always query the Antithesis token and its facts
 
 ```bash
-anti facts | jq '.result'
+antij facts
+```
+
+Will query all facts
+
+But you can also query specific facts, for example:
+
+```bash
+antij facts user
+```
+will report the GitHub registered users.
+
+Or
+
+```bash
+antij facts test-run pending
+```
+will report the pending test runs.
+
+```bash
+anti facts --help
 ```
+will show you all the available facts you can query.
 
 ## Design
 

cli/docs/oracle-role.md

@@ -1,8 +1,30 @@
 # Oracle role
 
-This is the role of the user that wants to run an oracle service for the Antithesis platform. There will be only one token and so there will be only one oracle service running at a time, but we document it here for completeness.
+This is the role of the user that wants to run a service to control access to the Antithesis platform. There will be only one token and so there will be only one oracle service running at a time, but we document it here for completeness.
 
-## Creating the anti token (only for testing)
+## 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.
+
+You can create a wallet with the `anti wallet create` command.
+
+```bash
+antij wallet create
+```
+
+The current oracle wallet reports
+
+```bash
+antij wallet info
+```
+
+```json
+{
+  "address": "addr_test1vq04e6lvknx3ettppz5xq9x7nk8j87w5gaammke7z2ymyfqtkl4vv",
+  "filePath": "tmp/oracle.json",
+  "owner": "1f5cebecb4cd1cad6108a86014de9d8f23f9d4477bbddb3e1289b224"
+}
+```
 
 To create the Antithesis token, you can use the `anti oracle token create` command.
 
@@ -12,19 +34,43 @@ anti oracle token boot
 
 It will create the Antithesis token. This token is a unique identifier for the Antithesis platform and will be used by all users to interact with the platform. You have to distribute it so that users can set the `ANTI_TOKEN_ID` environment variable to point to it.
 
-To test the role change the ANTI_TOKEN_ID environment variable to the new create token id
-
 You can review the token info anytime with
 
+```bash
+antij token | jq .state
+```
+
+Critically the owner matches the wallet owner.
+
+## Publishing the oracle configuration
+
+Before requesters can request test-runs, the oracle should select the agent identity and in general expose validation parameters so that the requesters and the agent can pre-validate their requests.
+
+This is done with the `anti oracle config set` command.
+
 
 ```bash
-anti token | jq '.result'
+anti oracle config set  --min-test-duration MIN_TEST_HOURS --max-test-duration MAX_TEST_HOURS --agent-pkh PUBLIC_KEY_HASH
 ```
-In the requests field you will notice the `validation` field, which will be set to `validated` for all requests that have been validated .
 
+This will end up in a fact and so  we can inspect it with the `anti facts` command.
+
+```bash
+antij facts config
+```
 
 ## Updating the anti token
 
+The main responsibility of the oracle is to include change requests in the Antithesis token.
+
+Pending change requests can be queried with the `antij token` command.
+
+```bash
+antij token | jq '.requests'
+```
+
+In the requests field you will notice the `validation` field, which will be set to `validated` for all requests that have been validated .
+
 Once you decided what to include in the Antithesis token, you can commit the requests to the token.
 
 Updating the token with new requests is done with the `anti oracle token update` command. As with retract you have to provide the `outputRefId` of the request you want to update. Multiple requests can be updated at once, so you can provide multiple `-o` options.
@@ -33,10 +79,10 @@ Updating the token with new requests is done with the `anti oracle token update`
 anti oracle token update -o b6fc7cca5bcae74e6a5983f7922d0e0985285f1f19e62ccc9cb9fd4d3766a81b-0
 ```
 
-## Deleting the anti token (only for testing)
+## Deleting the anti token (DANGEROUS)
 
 To delete the Antithesis token, you can use the `anti oracle token delete` command.
 
 ```bash
 anti oracle token delete
-```
+```