diff --git a/.gittensory-miner.env.example b/.gittensory-miner.env.example
new file mode 100644
index 0000000000..b8760ea4c7
--- /dev/null
+++ b/.gittensory-miner.env.example
@@ -0,0 +1,56 @@
+# gittensory-miner — starter env file
+#
+# Copy this to `.gittensory-miner.env` (gitignored), fill in GITHUB_TOKEN, then either `source` it or
+# point docker-compose / systemd at it — see packages/gittensory-miner/DEPLOYMENT.md:
+#
+#   cp .gittensory-miner.env.example .gittensory-miner.env
+#
+# Every value below is a SAMPLE placeholder — never commit real secrets. For the generated,
+# always-current table of every miner env var and its default, see
+# packages/gittensory-miner/docs/env-reference.md (regenerate with `npm run miner:env-reference`).
+
+# =============================================================================
+# 1. Required
+# =============================================================================
+# GitHub token (a PAT or an App installation token) the miner uses for issue discovery and PR-outcome
+# polling. Discovery/attempt runs that reach GitHub fail without it. Keep it out of source control.
+GITHUB_TOKEN=ghp_your_token_here
+
+# =============================================================================
+# 2. Coding agent
+# =============================================================================
+# Which local coding-agent CLI the miner drives for attempts (e.g. claude-code, codex). Leave unset to
+# use the package default resolved at run time.
+# MINER_CODING_AGENT_PROVIDER=claude-code
+
+# =============================================================================
+# 3. Optional overrides — defaults are fine for a single-machine install
+# =============================================================================
+# By default all local state lives under GITTENSORY_MINER_CONFIG_DIR (else $XDG_CONFIG_HOME, else
+# ~/.config), in a gittensory-miner/ subdirectory. Set the base dir, or any individual store path,
+# only to relocate state (e.g. onto a dedicated volume).
+# GITTENSORY_MINER_CONFIG_DIR=/var/lib/gittensory-miner
+
+# Repo clones and git worktrees created during attempts:
+# GITTENSORY_MINER_REPO_CLONE_DIR=/var/lib/gittensory-miner/clones
+# GITTENSORY_MINER_WORKTREE_DIR=/var/lib/gittensory-miner/worktrees
+
+# Per-store SQLite file overrides (each defaults to a file under the config dir above):
+# GITTENSORY_MINER_CLAIM_LEDGER_DB=
+# GITTENSORY_MINER_PORTFOLIO_QUEUE_DB=
+# GITTENSORY_MINER_EVENT_LEDGER_DB=
+# GITTENSORY_MINER_RUN_STATE_DB=
+# GITTENSORY_MINER_PLAN_STORE_DB=
+# GITTENSORY_MINER_PREDICTION_LEDGER_DB=
+# GITTENSORY_MINER_GOVERNOR_LEDGER_DB=
+# GITTENSORY_MINER_GOVERNOR_STATE_DB=
+# GITTENSORY_MINER_ATTEMPT_LOG_DB=
+# GITTENSORY_MINER_ORB_EXPORT_DB=
+# GITTENSORY_MINER_REPLAY_SNAPSHOT_DB=
+# GITTENSORY_MINER_WORKTREE_ALLOCATOR_DB=
+# GITTENSORY_MINER_DENY_HOOK_SYNTHESIS_DB=
+
+# Misc:
+# GITTENSORY_MINER_AMS_POLICY_PATH=          # path to an AMS policy file
+# GITTENSORY_MINER_NO_UPDATE_CHECK=1         # disable the startup npm-registry version nudge
+# GITTENSORY_MINER_VERSION=                  # override the reported version (testing only)