diff --git a/CLAUDE.md b/CLAUDE.md
index 552d192..b587ada 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,13 +27,21 @@ git push -u origin feat/my-feature
 gh pr create
 ```
 
-### Agent commit identity
+### Agent pushes and commit identity
 
-`.claude/settings.json` sets `GIT_AUTHOR_*` / `GIT_COMMITTER_*` to
-`goodolclint-claude[bot]`, so commits made from an agent session are attributed to the App
-rather than to the operator. The push itself is an ordinary local `git push` over the
-operator's SSH key — the env vars change authorship, not transport. No `Co-Authored-By`
-trailer is needed when they are in effect.
+**Default: the `github` MCP tools.** Agent-authored branches go up with `create_branch` +
+`push_files`, which commits as the `goodolclint-claude` App and produces a **verified**
+commit. `push_files` re-uploads full file contents, so byte-verify before opening the PR:
+commit the identical change locally, `git fetch`, and `git diff <local-commit>
+origin/<branch> --` must be empty. `push_files` cannot express a removal — use
+`delete_file` for deletions, and a rename is `push_files` of the new path plus
+`delete_file` of the old.
+
+**Fallback: local `git push`, for large pushes only.** Re-uploading full contents inline
+is impractical past a certain size. `.claude/settings.json` sets `GIT_AUTHOR_*` /
+`GIT_COMMITTER_*` to `goodolclint-claude[bot]` so those commits are still attributed to the
+App — but they are **not verified**, because the signature comes from committing through
+the API, not from the author name. Use this path when needed, not by default.
 
 The env block applies at session start, so a session that predates this file still commits
 as the operator.