diff --git a/README.md b/README.md
index ca40705..fa50eb4 100644
--- a/README.md
+++ b/README.md
@@ -37,11 +37,12 @@ Install all of these before setting up. Each one is a hard dependency of a git h
 | `claude` CLI | Required by the `validate-plugins` and `validate-marketplace` pre-push hooks | Claude Code |
 | `go` toolchain | The gitea MCP server runs as `go run gitea.com/gitea/gitea-mcp@v1.7.0`, resolved from `PATH`. Without it the server fails to start and every `gitea-*` skill loses its tools | https://go.dev/dl/ — verify with `go version` |
 
-The gitea MCP server additionally needs two environment variables exported in the shell that launches your agent. They are referenced as `${GITEA_ACCESS_TOKEN}` and `${GITEA_HOST}` in `plugins/gitea/.mcp.json`, and apm passes those references through to the deployed config unexpanded, so the values are resolved at server startup and never committed:
+The gitea MCP server additionally needs two environment variables in the shell that launches your agent — referenced as `${GITEA_ACCESS_TOKEN}` and `${GITEA_HOST}` in `plugins/gitea/.mcp.json`, with apm passing those references through to the deployed config unexpanded so the values are resolved at server startup and never committed. Copy `plugins/gitea/.env.example` to `.env` at the repo root, fill in real values, then export it — nothing in this repo auto-loads a `.env` file:
 
 ```bash
-export GITEA_ACCESS_TOKEN='<your-gitea-token>'
-export GITEA_HOST='https://<your-gitea-host>'
+cp plugins/gitea/.env.example .env
+$EDITOR .env
+set -a; source .env; set +a
 ```
 
 Generate the token in Gitea under Settings, Applications. Scope it to the repositories you want the agent to reach. If the server starts but every call returns an authorization error, that token is the first thing to check.
diff --git a/plugins/gitea/.env.example b/plugins/gitea/.env.example
new file mode 100644
index 0000000..2f3b47e
--- /dev/null
+++ b/plugins/gitea/.env.example
@@ -0,0 +1,20 @@
+# Environment variables required by the gitea MCP server declared in
+# plugins/gitea/.mcp.json. apm passes these ${VAR} references through to the
+# deployed MCP config unexpanded; Claude Code resolves them from the process
+# environment at server startup. Neither value is ever committed to this repo.
+#
+# Nothing in this repo auto-loads a .env file -- apm has no dotenv support.
+# Copy this file to .env at the repo root, fill in real values, then export it
+# into your shell before starting Claude Code, e.g.:
+#
+#   set -a; source .env; set +a
+#
+# Or skip the file and export the two variables directly in your shell
+# profile. Either way, never commit .env -- .gitignore already excludes it.
+
+# A Gitea access token, scoped to the repositories this agent should reach.
+# Generate one in Gitea under Settings > Applications.
+GITEA_ACCESS_TOKEN=<your-gitea-access-token>
+
+# The base URL of your Gitea instance, including scheme.
+GITEA_HOST=https://<your-gitea-host>