diff --git a/github/README.md b/github/README.md
index 22ce463d..47213a30 100644
--- a/github/README.md
+++ b/github/README.md
@@ -6,21 +6,27 @@ Mention `/opencode` in your comment, and opencode will execute tasks within your
 
 ## Features
 
-#### Triage and explain issues
+#### Explain an issues
 
-```bash
+Leave the following comment on a GitHub issue. `opencode` will read the entire thread, including all comments, and reply with a clear explanation.
+
+```
 /opencode explain this issue
 ```
 
-#### Fix or implement issues - opencode will create a PR with the changes.
+#### Fix an issues
 
-```bash
+Leave the following comment on a GitHub issue. opencode will create a new branch, implement the changes, and open a PR with the changes.
+
+```
 /opencode fix this
 ```
 
 #### Review PRs and make changes
 
-```bash
+Leave the following comment on a GitHub PR. opencode will implement the requested change and commit it to the same PR.
+
+```
 Delete the attachment from S3 when the note is removed /oc
 ```
 
diff --git a/packages/opencode/src/cli/cmd/github.ts b/packages/opencode/src/cli/cmd/github.ts
index b8ce6582..e6b871c1 100644
--- a/packages/opencode/src/cli/cmd/github.ts
+++ b/packages/opencode/src/cli/cmd/github.ts
@@ -156,21 +156,23 @@ export const GithubInstallCommand = cmd({
           step2 =
             "Configure OIDC in AWS - https://docs.github.com/en/actions/how-tos/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services"
         } else {
-          const url = `https://github.com/organizations/${app.owner}/settings/secrets/actions`
-          const env = providers[provider].env
-          const envStr =
-            env.length === 1
-              ? `\`${env[0]}\` secret`
-              : `\`${[env.slice(0, -1).join("\`, \`"), ...env.slice(-1)].join("\` and \`")}\` secrets`
-          step2 = `Add ${envStr} for ${providers[provider].name} - ${url}`
+          step2 = [
+            `    2. Add the following secrets in org or repo (${app.owner}/${app.repo}) settings`,
+            "",
+            ...providers[provider].env.map((e) => `       - ${e}`),
+          ].join("\n")
         }
 
         prompts.outro(
           [
             "Next steps:",
-            `    1. Commit "${WORKFLOW_FILE}" file and push`,
-            `    2. ${step2}`,
-            "    3. Learn how to use the GitHub agent - https://docs.opencode.ai/docs/github/getting-started",
+            "",
+            `    1. Commit the \`${WORKFLOW_FILE}\` file and push`,
+            step2,
+            "",
+            "    3. Go to a GitHub issue and comment `/oc summarize` to see the agent in action",
+            "",
+            "   Learn more about the GitHub agent - https://opencode.ai/docs/github/#usage-examples",
           ].join("\n"),
         )
       }
@@ -320,6 +322,7 @@ jobs:
       contains(github.event.comment.body, '/opencode')
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       id-token: write
     steps:
       - name: Checkout repository
@@ -457,8 +460,9 @@ export const GithubRunCommand = cmd({
               `${response}\n\nCloses #${issueId}${footer({ image: true })}`,
             )
             await updateComment(`Created PR #${pr}${footer({ image: true })}`)
+          } else {
+            await updateComment(`${response}${footer({ image: true })}`)
           }
-          await updateComment(`${response}${footer({ image: true })}`)
         }
       } catch (e: any) {
         exitCode = 1
diff --git a/packages/web/src/content/docs/docs/github.mdx b/packages/web/src/content/docs/docs/github.mdx
index 375a2cff..0a63a353 100644
--- a/packages/web/src/content/docs/docs/github.mdx
+++ b/packages/web/src/content/docs/docs/github.mdx
@@ -77,18 +77,24 @@ This will walk you through installing the GitHub app, creating the workflow, and
 
 - Explain an issue
 
-  ```bash
+  Leave the following comment on a GitHub issue. `opencode` will read the entire thread, including all comments, and reply with a clear explanation.
+
+  ```
   /opencode explain this issue
   ```
 
-- Fix an issue - opencode will create a PR with the changes.
+- Fix an issue
 
-  ```bash
+  Leave the following comment on a GitHub issue. opencode will create a new branch, implement the changes, and open a PR with the changes.
+
+  ```
   /opencode fix this
   ```
 
 - Review PRs and make changes
 
-  ```bash
+  Leave the following comment on a GitHub PR. opencode will implement the requested change and commit it to the same PR.
+
+  ```
   Delete the attachment from S3 when the note is removed /oc
   ```