From afd8cba20f920c998f6d3b38db0abe64242fe042 Mon Sep 17 00:00:00 2001
From: Oli Evans <oli@protocol.ai>
Date: Wed, 17 Jan 2024 16:48:55 +0000
Subject: [PATCH] docs: Update README.md

---
 README.md | 30 ++++++++++++++++++++----------
 1 file changed, 20 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 1d07f20..d812a75 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 Upload files to [web3.storage](https://web3.storage) from a Github Action, and output the IPFS Content ID.
 
-A lightweight wrapper around [w3cli](https://github.com/web3-storage/w3cli). As a [composite](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) github action all it does is configure and call the cli for you. See the steps in [./action.yml](./action.yml).
+A lightweight wrapper around [w3cli]. As a [composite](https://docs.github.com/en/actions/creating-actions/creating-a-composite-action) github action all it does is configure and call the cli for you. See the steps in [./action.yml](./action.yml).
 
 ## Usage
 
@@ -22,12 +22,13 @@ with:
 - run: echo ${{ steps.w3up.outputs.url }}
 ```
 
-Use [w3cli] to generate a `secret_key` and `proof` to allow this action to upload to a space on.
+### Generating a `secret_key` and `proof`
 
-Install it from npm and login as described here https://web3.storage/docs/quickstart/ then:
+On your dev machine, use [w3cli] to generate a `secret_key` and `proof` to allow this action to upload to a space on.
+
+Install it from npm and login as described here https://web3.storage/docs/quickstart/ then create a key like this:
 
 ```shell
-# create a signing key for CI.
 # Use the `did` in the input to the next command. 
 # Use `key` as your `secret_key` for add_to_web3.
 $ w3 key create --json
@@ -35,18 +36,25 @@ $ w3 key create --json
   "did": "did:key:z6Mk...",
   "key": "MgCaT7Se2QX9..."
 }
+```
+
+Keep the `key` safe. Save it as a secret on your repo.
 
-# create a base64 encoded UCAN `proof` 
-# It delegates store and upload permissions to the `did` we created above.
+Copy the `did` for use in the next command. The output is a base64 encoded ucan `proof` that delegates capabilities to `store/add` and `upload/add` on your current space to the key generated above.
+
+```shell
+# Delegate capabilities to the `did` we created above.
 $ w3 delegation create did:key:z6Mk... -c 'store/add' -c 'upload/add' --base64
 mAYIEAP8OEaJlcm9vdHOAZ3ZlcnNpb24BwwUBcRIg+oHTbzShh1WzBo9ISkonCW+KAcy/+zW8Zb...
 ```
 
-- Use the `key` value from the output of `w3 key create --json` as the `secret_key` for this action.
-- Use the `did value from that command as the audience for `w3 delegation create <audience>` shown above.
-- Use the output of `w3 delegation create <audience>` as the `proof` for this action.
+The capabilies `store/add` and `upload/add` are the minimum required to upload files to web3.storage. This proof will not allow that key to list uploads in this space for example.
+
+To recap:
 
-Keep the `secret_key` safe. Save it as a secret on your repo. The `proof` delegates permission from your account to that key to upload to your space. The `proof` can only be used by an agent that holds the `secret_key`.
+- Use the `key` value from the output of `w3 key create --json` as the `secret_key` for this action.
+- Use the `did value from that output as the audience for `w3 delegation create <audience>` shown above.
+- Use the output of `w3 delegation create <audience> --base64` as the `proof` for this action.
 
 ## Inputs
 
@@ -109,3 +117,5 @@ e.g. `https://dweb.link/ipfs/bafkreicysg23kiwv34eg2d7qweipxwosdo2py4ldv42nbaugul
 💌 Considerate contributions welcome! 
 
 <h3 align="center"><a href="https://web3.storage">⁂</a></h3>
+
+[w3cli]: https://github.com/web3-storage/w3cli