diff --git a/docs/hacking.md b/docs/hacking.md
--- a/docs/hacking.md
+++ b/docs/hacking.md
@@ -55,16 +55,12 @@
 quite cumbersome. So the nix flake provides a
 `nixosConfiguration` to do so.
 
-To begin, head to `http://localhost:3000/knots` in the browser
-and create a knot with hostname `localhost:6000`. This will
-generate a knot secret. Set `$TANGLED_VM_KNOT_SECRET` to it,
-ideally in a `.envrc` with [direnv](https://direnv.net) so you
-don't lose it.
+To begin, grab your DID from http://localhost:3000/settings.
+Then, set `TANGLED_VM_KNOT_OWNER` and
+`TANGLED_VM_SPINDLE_OWNER` to your DID.
 
-You will also need to set the `$TANGLED_VM_SPINDLE_OWNER`
-variable to some value. If you don't want to [set up a
-spindle](#running-a-spindle), you can use any placeholder
-value.
+If you don't want to [set up a spindle](#running-a-spindle),
+you can use any placeholder value.
 
 You can now start a lightweight NixOS VM like so:
 
@@ -75,8 +71,16 @@
 ```
 
 This starts a knot on port 6000, a spindle on port 6555
-with `ssh` exposed on port 2222. You can push repositories
-to this VM with this ssh config block on your main machine:
+with `ssh` exposed on port 2222.
+
+Once the services are running, head to
+http://localhost:3000/knots and hit verify (and similarly,
+http://localhost:3000/spindles to verify your spindle). It
+should verify the ownership of the services instantly if
+everything went smoothly.
+
+You can push repositories to this VM with this ssh config
+block on your main machine:
 
 ```bash
 Host nixos-shell
@@ -95,14 +99,10 @@
 
 ## running a spindle
 
-You will need to find out your DID by entering your login handle into
-<https://pdsls.dev/>. Set `$TANGLED_VM_SPINDLE_OWNER` to your DID.
-
-The above VM should already be running a spindle on `localhost:6555`.
-You can head to the spindle dashboard on `http://localhost:3000/spindles`,
-and register a spindle with hostname `localhost:6555`. It should instantly
-be verified. You can then configure each repository to use this spindle
-and run CI jobs.
+The above VM should already be running a spindle on
+`localhost:6555`. Head to http://localhost:3000/spindles and
+hit verify. You can then configure each repository to use
+this spindle and run CI jobs.
 
 Of interest when debugging spindles:
 
diff --git a/docs/knot-hosting.md b/docs/knot-hosting.md
--- a/docs/knot-hosting.md
+++ b/docs/knot-hosting.md
@@ -73,14 +73,14 @@
 ```
 
 Create `/home/git/.knot.env` with the following, updating the values as
-necessary. The `KNOT_SERVER_SECRET` can be obtained from the
-[/knots](https://tangled.sh/knots) page on Tangled.
+necessary. The `KNOT_SERVER_OWNER` should be set to your
+DID, you can find your DID in the [Settings](https://tangled.sh/settings) page.
 
 ```
 KNOT_REPO_SCAN_PATH=/home/git
 KNOT_SERVER_HOSTNAME=knot.example.com
 APPVIEW_ENDPOINT=https://tangled.sh
-KNOT_SERVER_SECRET=secret
+KNOT_SERVER_OWNER=did:plc:foobar
 KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
 KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
 ```
@@ -128,8 +128,10 @@
 Remember to use Let's Encrypt or similar to procure a certificate for your
 knot domain.
 
-You should now have a running knot server! You can finalize your registration by hitting the
-`initialize` button on the [/knots](https://tangled.sh/knots) page.
+You should now have a running knot server! You can finalize
+your registration by hitting the `verify` button on the
+[/knots](https://tangled.sh/knots) page. This simply creates
+a record on your PDS to announce the existence of the knot.
 
 ### custom paths
 
diff --git a/docs/migrations/knot-1.7.0.md b/docs/migrations/knot-1.7.0.md
new file mode 100644
--- /dev/null
+++ b/docs/migrations/knot-1.7.0.md
@@ -0,0 +1,39 @@
+# Upgrading from v1.7.0
+
+After v1.7.0, knot secrets have been deprecated. You no
+longer need a secret from the appview to run a knot. All
+authorized commands between services to knots are managed
+via [Service
+Auth](https://atproto.com/specs/xrpc#inter-service-authentication-jwt).
+Knots will be read-only until upgraded.
+
+Upgrading is quite easy, in essence:
+
+- `KNOT_SERVER_SECRET` is no more, you can remove this
+  environment variable entirely
+- `KNOT_SERVER_OWNER` is now required on boot, set this to
+  your DID. You can find your DID in the
+  [settings](https://tangled.sh/settings) page.
+- Restart your knot once you have replace the environment
+  variable
+- Head to the [knot dashboard](https://tangled.sh/knots) and
+  hit the "retry" button to verify your knot. This simply
+  writes a `sh.tangled.knot` record to your PDS.
+
+## Nix
+
+If you use the nix module, simply bump the flake to the
+latest revision, and change your config block like so:
+
+```diff
+ services.tangled-knot = {
+   enable = true;
+   server = {
+-    secretFile = /path/to/secret;
++    owner = "did:plc:foo";
+     .
+     .
+     .
+   };
+ };
+```