diff --git a/README.md b/README.md
index 70a6976..88128be 100644
--- a/README.md
+++ b/README.md
@@ -57,8 +57,8 @@ The PR's `pulumi preview` comment shows the repository create. Once merged, the
 - Repository names are lowercase kebab-case (`ext-*` for extensions, `experimental-ext-*` while experimental).
 - At least one team or user must have `admin` permission (validated), so a managed repository is never ownerless.
 - Removing the entry **archives** the repository rather than deleting it; deletion stays a manual org-owner action.
-- Entries without `settings` are access-only: the repository pre-dates this config and Pulumi manages only its collaborators. Adding `settings` to such an entry does not adopt the repository — the deploy fails with a name-already-exists error. Adopt it with `pulumi import` first; that is out of scope for the PR flow above.
-- The `repository` key of a managed entry is also the Pulumi resource name. Renaming it in place archives the old repository and creates a new one: rename on GitHub first, then move the state (`pulumi state mv`) before changing the key.
+- Entries without `settings` are access-only: the repository pre-dates this config and Pulumi manages only its collaborators. Adding `settings` to such an entry does not adopt the repository. The deploy fails with a name-already-exists error. Adopt it with `pulumi import` first; that is out of scope for the PR flow above.
+- The `repository` key of a managed entry is also the Pulumi resource name. Renaming it in place archives the old repository and creates a new one. To rename, do three things in order: rename the repository on GitHub, rename the resources in state with `pulumi state rename` (`repository-<old>` to `repository-<new>`, and `repo-<old>` to `repo-<new>`), then change the key.
 - A repository archived by hand in GitHub stays archived (`archived` is ignored on refresh); un-archiving is a manual org-owner action.
 
 ## Cloudflare Access (security-room)
diff --git a/src/config/repoAccess.ts b/src/config/repoAccess.ts
index 1415b93..3bf2052 100644
--- a/src/config/repoAccess.ts
+++ b/src/config/repoAccess.ts
@@ -39,9 +39,11 @@ export interface RepositoryAccess {
    * that already exists does not adopt it: the deploy fails with a
    * name-already-exists error. Adopt it with `pulumi import` first. The
    * `repository` key of a managed entry is also the Pulumi resource name, so
-   * renaming it in place archives the old repository and creates a new one:
-   * rename on GitHub first, then move the state (`pulumi state mv`) before
-   * changing the key.
+   * renaming it in place archives the old repository and creates a new one.
+   * To rename, do three things in order: rename the repository on GitHub,
+   * rename the resources in state with `pulumi state rename`
+   * (`repository-<old>` to `repository-<new>`, and `repo-<old>` to
+   * `repo-<new>`), then change the key.
    */
   settings?: RepositorySettings;
   teams?: Array<{