Context
packages/gittensory-miner has no single consolidated example env file today, unlike the repo's existing .env.selfhost.example for ORB/self-host. AMS env vars are scattered across roughly 19 GITTENSORY_MINER_/MINER_ names — state-dir and per-store DB path overrides, GITTENSORY_MINER_KILL_SWITCH, GITTENSORY_MINER_LIVE_MODE, plus the coding-agent-driver vars (MINER_CODING_AGENT_PROVIDER and friends) that are already production-wired per #5131/#5138 but never collected in one copy-pasteable place. README.md's existing storage table (from #4876) documents SQLite files, not env vars, so this is a distinct gap.
Dependencies
None — independently shippable. It complements (but does not require) the README/DEPLOYMENT prose-documentation issue in this same batch ("Document MINER_CODING_AGENT_* env vars in the miner package's README and DEPLOYMENT.md") and the generated, CI-drift-checked env-reference issue (npm run miner:env-reference) — this file is a static, human-curated starter, not a replacement for either.
Requirements
- Create
packages/gittensory-miner/.gittensory-miner.env.example, mirroring the structure and comment style of the repo's existing .env.selfhost.example.
- Enumerate all GITTENSORY_MINER_/MINER_ env vars actually read by the miner package, including at minimum: state-dir path override, per-store DB path overrides (claim ledger, event ledger, governor ledger, plan store, prediction ledger, etc.),
GITTENSORY_MINER_KILL_SWITCH, and GITTENSORY_MINER_LIVE_MODE.
- Add a clearly delimited "pick ONE coding-agent provider" section covering
MINER_CODING_AGENT_PROVIDER (accepted values: noop/claude-cli/codex-cli/agent-sdk), MINER_CODING_AGENT_CLAUDE_MODEL, MINER_CODING_AGENT_CODEX_MODEL, and MINER_CODING_AGENT_TIMEOUT_MS.
- Add an inline comment per var documenting accepted values/type, default (if any), and a one-line description of its effect.
- Use only placeholder values (e.g.
GITHUB_TOKEN=ghp_xxx) — never real-looking secrets or production-shaped values.
- Add a single-line pointer to the new file from both
packages/gittensory-miner/README.md and packages/gittensory-miner/DEPLOYMENT.md, near their existing setup instructions.
- Do not duplicate or contradict the prose documentation added by the separate README/DEPLOYMENT env-var doc issue in this batch — this file is a machine-copyable artifact, not narrative docs.
Deliverables / Acceptance Criteria
Test Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Because the primary artifact here is a static config file rather than executable logic, add: (1) a lightweight test asserting the example file exists, parses cleanly as a dotenv-style file, and contains no syntax errors, (2) an invariant test for "every env-var name enumerated in .gittensory-miner.env.example corresponds to an actual process.env.* read somewhere under packages/gittensory-miner/**" (no stale or invented vars), and (3) a regression test is not applicable since this is a net-new documentation artifact, not a bug fix — state that explicitly in the PR rather than omitting the point.
Expected Outcome
A new operator can copy one file, fill in real values, and have a working .env covering every AMS setting — including the coding-agent-driver choice — without hunting through source for env-var names.
Links & Resources
Context
packages/gittensory-miner has no single consolidated example env file today, unlike the repo's existing
.env.selfhost.examplefor ORB/self-host. AMS env vars are scattered across roughly 19 GITTENSORY_MINER_/MINER_ names — state-dir and per-store DB path overrides, GITTENSORY_MINER_KILL_SWITCH, GITTENSORY_MINER_LIVE_MODE, plus the coding-agent-driver vars (MINER_CODING_AGENT_PROVIDER and friends) that are already production-wired per #5131/#5138 but never collected in one copy-pasteable place. README.md's existing storage table (from #4876) documents SQLite files, not env vars, so this is a distinct gap.Dependencies
None — independently shippable. It complements (but does not require) the README/DEPLOYMENT prose-documentation issue in this same batch ("Document MINER_CODING_AGENT_* env vars in the miner package's README and DEPLOYMENT.md") and the generated, CI-drift-checked env-reference issue (
npm run miner:env-reference) — this file is a static, human-curated starter, not a replacement for either.Requirements
packages/gittensory-miner/.gittensory-miner.env.example, mirroring the structure and comment style of the repo's existing.env.selfhost.example.GITTENSORY_MINER_KILL_SWITCH, andGITTENSORY_MINER_LIVE_MODE.MINER_CODING_AGENT_PROVIDER(accepted values: noop/claude-cli/codex-cli/agent-sdk),MINER_CODING_AGENT_CLAUDE_MODEL,MINER_CODING_AGENT_CODEX_MODEL, andMINER_CODING_AGENT_TIMEOUT_MS.GITHUB_TOKEN=ghp_xxx) — never real-looking secrets or production-shaped values.packages/gittensory-miner/README.mdandpackages/gittensory-miner/DEPLOYMENT.md, near their existing setup instructions.Deliverables / Acceptance Criteria
packages/gittensory-miner/.gittensory-miner.env.examplecreatedTest Coverage Requirements
This PR must ship with full test coverage for every changed line and branch — the repo's Codecov patch gate requires 99%+ coverage and the house standard is to aim for 100%, including both sides of every conditional/nullish-coalescing branch introduced. Because the primary artifact here is a static config file rather than executable logic, add: (1) a lightweight test asserting the example file exists, parses cleanly as a dotenv-style file, and contains no syntax errors, (2) an invariant test for "every env-var name enumerated in
.gittensory-miner.env.examplecorresponds to an actualprocess.env.*read somewhere underpackages/gittensory-miner/**" (no stale or invented vars), and (3) a regression test is not applicable since this is a net-new documentation artifact, not a bug fix — state that explicitly in the PR rather than omitting the point.Expected Outcome
A new operator can copy one file, fill in real values, and have a working
.envcovering every AMS setting — including the coding-agent-driver choice — without hunting through source for env-var names.Links & Resources
.env.selfhost.example