doc: update

README.md

@@ -46,17 +46,26 @@ Comment directly on lines in the MR's "Files" tab — opencode receives the file
 - A runner that can run Docker containers (the example below uses `docker-amd64` with `node:lts-bookworm`).
 - A Forgejo PAT (see scopes below) and a Nomyo API key.
 
-### Forgejo PAT scopes
+### Forgejo PATs
 
-Generate the token at *Settings → Applications → Manage Access Tokens* with these scopes:
+The action uses **two** Forgejo PATs with split duties — see [Security](#security) for the rationale. Generate both at *Settings → Applications → Manage Access Tokens* (Forgejo's write scope inherently grants read on the same resource):
+
+**Read PAT** — used by the outer action for fetches and read APIs. Never exposed to the opencode subprocess.
 
 | Scope | Used for |
 |---|---|
 | `read:repository` | Clone, fetch repo info |
+| `read:issue` | Read issue/MR thread, comments, files, commits, reviews |
+| `read:user` | Resolve actor identity (optional, removes log noise) |
+
+**Push PAT** — used only after the agent finishes, for git push and write APIs.
+
+| Scope | Used for |
+|---|---|
 | `write:repository` | Push commits and branches |
-| `read:issue` | Read issue/MR comments and metadata |
 | `write:issue` | Create + update comments, open MRs |
-| `read:user` | Resolve actor info (optional) |
+
+If you only have one PAT, give it the write scopes and use it for both — backward compatible.
 
 ### Secrets
 
@@ -64,7 +73,8 @@ In *Repo Settings → Actions → Secrets* add:
 
 | Secret | Value |
 |---|---|
-| `FORGEJO_TOKEN` | The PAT from above |
+| `FORGEJO_TOKEN` | Read PAT (or your single full-access PAT) |
+| `FORGEJO_PUSH_TOKEN` | Write PAT (omit to share `FORGEJO_TOKEN` for writes too) |
 | `NOMYO_API_KEY` | Your Nomyo API key |
 
 ### Workflow file
@@ -78,12 +88,16 @@ on:
     types: [created]
   pull_request_review_comment:
     types: [created]
+  pull_request_review:
+    types: [submitted]
 
 jobs:
   opencode:
     if: |
       contains(github.event.comment.body, '/oc') ||
-      contains(github.event.comment.body, '/opencode')
+      contains(github.event.comment.body, '/opencode') ||
+      contains(github.event.review.body, '/oc') ||
+      contains(github.event.review.body, '/opencode')
     runs-on: docker-amd64
     container:
       image: node:lts-bookworm
@@ -128,6 +142,7 @@ jobs:
           model: nomyo/unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M
           forgejo_api_url: https://bitfreedom.net/code/
           forgejo_token: ${{ secrets.FORGEJO_TOKEN }}
+          forgejo_push_token: ${{ secrets.FORGEJO_PUSH_TOKEN }}
 ```
 
 ### Why the manual clone?
@@ -142,7 +157,8 @@ jobs:
 | `nomyo_api_key` | Yes | — | API key for the OpenAI-compatible backend. |
 | `nomyo_api_url` | No | `https://chat.nomyo.ai/api` | Base URL of the OpenAI-compatible endpoint. The adapter calls `${baseURL}/chat/completions`. |
 | `forgejo_api_url` | No | `https://bitfreedom.net/code/` | Forgejo instance base URL. |
-| `forgejo_token` | No | — | Forgejo PAT (see scopes above). |
+| `forgejo_token` | No | — | Forgejo PAT used by the outer action for read ops (clone, fetch, read APIs). Stripped from the opencode subprocess env. |
+| `forgejo_push_token` | No | falls back to `forgejo_token` | Optional separate write PAT used only after the agent finishes (git push, comment write, MR create). |
 | `agent` | No | — | Primary agent name to use. |
 | `share` | No | auto | Share the opencode session (`true`/`false`). Defaults to `true` for public repos. |
 | `prompt` | No | — | Custom prompt override. |
@@ -155,6 +171,7 @@ jobs:
 |---|---|---|
 | `issue_comment` | Comment on an issue or MR | Body must contain a mention phrase |
 | `pull_request_review_comment` | Comment on a specific line in an MR's Files tab | Receives file path, line number, and diff hunk |
+| `pull_request_review` | Whole-review submission (Approve / Request changes / Comment) on an MR | Mention must appear in the review body |
 
 ## Architecture
 
@@ -168,6 +185,15 @@ This action is a **composite action**. On each run it:
 
 There is no compiled `dist/` artifact — `index.ts` is executed directly by Bun.
 
+## Security
+
+The agent runs untrusted-ish code (model output executes shell commands, edits files, etc.). The action takes the following defensive measures:
+
+- **Two-token model.** `FORGEJO_TOKEN` is read-only, used by the outer process for fetches and read APIs. `FORGEJO_PUSH_TOKEN` is write-capable and is only loaded into the outer process — it is never placed into the opencode subprocess environment, and it is never written to `.git/config`.
+- **Env stripping.** When the action spawns `opencode serve`, the child env is filtered: `FORGEJO_TOKEN`, `FORGEJO_PUSH_TOKEN`, and `GITHUB_TOKEN` are removed. The agent's `bash` tool inherits opencode's env, so these variables are unreachable from any shell the agent runs.
+- **Per-command git auth.** Credentials for `git fetch` / `git push` are passed via `git -c http.<host>.extraheader=...` on each invocation, not persisted in `.git/config`. A jailbroken agent cannot `git push` even with a valid remote.
+- **Nomyo key exposure (unavoidable).** `OPENCODE_AUTH_CONTENT` (containing the Nomyo API key) must be in opencode's env for the model to work; the agent's bash tool can read it. Treat the Nomyo key as compromised from the agent's perspective and rotate accordingly.
+
 ## Development
 
 Local test loop (requires Bun and `opencode` on PATH):
@@ -176,7 +202,8 @@ Local test loop (requires Bun and `opencode` on PATH):
 export NOMYO_API_KEY="..."
 export NOMYO_API_URL="https://chat.nomyo.ai/api"
 export FORGEJO_API_URL="https://bitfreedom.net/code/"
-export FORGEJO_TOKEN="..."
+export FORGEJO_TOKEN="..."         # read-scoped PAT
+export FORGEJO_PUSH_TOKEN="..."    # optional write-scoped PAT; falls back to FORGEJO_TOKEN
 export MODEL="nomyo/unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M"
 export GITHUB_RUN_ID="test-run"
 export GITHUB_RUN_NUMBER="1"