diff --git a/docs/design/claude-bot-account.md b/docs/design/claude-bot-account.md
index 4b88e35..dc37cb1 100644
--- a/docs/design/claude-bot-account.md
+++ b/docs/design/claude-bot-account.md
@@ -169,8 +169,11 @@ A GitHub App is the right auth surface for this — not a personal access token.
    |---|---|---|
    | Contents | Read & Write | Push branches |
    | Pull requests | Read & Write | Create/edit PRs |
+   | Workflows | Read & Write | Add or modify files under `.github/workflows/`. Without this, GitHub will reject pushes that touch a workflow file with `refusing to allow a GitHub App to create or update workflow ... without 'workflows' permission`. Required for any repo where Claude manages CI/CD config (i.e. all of them, in practice) |
    | Metadata | Read (mandatory) | Required by GitHub |
 
+   > After adding or changing permissions on the App, the existing installation also has to **accept** the new scope: *Settings → Installations → Configure → Review permissions*. The App can declare new permissions all it wants; until the installation acknowledges them, the runtime token still has the old scope.
+
 7. Account permissions: none needed.
 8. "Where can this GitHub App be installed?" → **Only on this account**.
 9. Create the App, generate a **private key** (`.pem`), download and store it in **Apple Passwords** (secure note attachment) as `amcheste-ai-agent GitHub App private key`.