docs: clarify OpenCode auth state precedence in deployments (#284)

Author: liujuanjuan1984

README.md

@@ -49,6 +49,11 @@ opencode models
 opencode serve --hostname 127.0.0.1 --port 4096
 ```
 
+Treat the deployed OpenCode user's HOME/XDG config directories as part of the
+runtime state. If a packaged or service-managed deployment appears to ignore
+fresh provider env vars, inspect that user's persisted OpenCode auth/config
+files before assuming the A2A adapter layer is overriding credentials.
+
 Then start `opencode-a2a` against that upstream:
 
 ```bash
@@ -132,6 +137,9 @@ This repository improves the service boundary around OpenCode, but it does not
 turn OpenCode into a hardened multi-tenant platform.
 
 - `A2A_BEARER_TOKEN` protects the A2A surface.
+- Provider auth and default model configuration remain on the OpenCode side; deployment-time
+  precedence details and HOME/XDG state impact are documented in
+  [docs/guide.md](docs/guide.md#troubleshooting-provider-auth-state).
 - `A2A_CLIENT_BEARER_TOKEN` is used for outbound peer calls initiated by the
   server-side `a2a_call` tool.
 - Provider auth and default model configuration remain on the OpenCode side.

docs/guide.md

@@ -139,6 +139,12 @@ starting that upstream process:
 If your provider uses environment variables for auth, export them before
 starting `opencode serve`.
 
+Do not assume startup-script env vars always erase previously persisted
+OpenCode auth state for the deployed user. When debugging provider-auth
+surprises, inspect the deployed user's HOME/XDG config directories and the
+OpenCode files stored there before concluding that `opencode-a2a` changed the
+credential selection.
+
 Then start `opencode-a2a` against that explicit upstream URL:
 
 ```bash
@@ -151,6 +157,23 @@ OPENCODE_WORKSPACE_ROOT=/abs/path/to/workspace \
 opencode-a2a serve
 ```
 
+## Troubleshooting Provider Auth State
+
+If one deployment works while another fails against the same upstream provider,
+check the deployed OpenCode user's local state before assuming the difference
+comes from the `opencode-a2a` package itself.
+
+- Provider auth and service-level model defaults belong to `opencode serve`.
+- The deployed user's HOME/XDG config directories are operational input.
+- Existing OpenCode auth/config files may still influence runtime behavior even
+  when you also inject provider env vars from a process manager or shell
+  wrapper.
+- Compare the deployed user's OpenCode auth/config files, HOME/XDG values, and
+  effective workspace directory before blaming the A2A adapter layer.
+- For OpenCode-specific auth/config troubleshooting, inspect files such as
+  `~/.local/share/opencode/auth.json` and `~/.config/opencode/opencode.json`
+  (or the equivalent XDG-resolved paths for that service user).
+
 ## Core Behavior
 
 - The service forwards A2A `message:send` to OpenCode session/message calls.