docs(selfhost): document ledger anchoring where operators actually look

[JSONbored]

Closes #9848

.env.selfhost.example covered provider selection and telemetry but never mentioned LOOPOVER_LEDGER_ANCHOR_* — despite anchoring being the one capability a self-host deployment uniquely can run. The hosted deployment retired review execution, so its decision_ledger is empty and there is nothing there to anchor.

The variables were documented in self-hosting-configuration.mdx, but nobody reads a docs table to discover a feature they don't know exists.

Written from actually doing it

Provisioning anchoring on a live instance (1,626 ledger rows) hit three things in sequence, each of which this file is the natural place to prevent:

• All-or-nothing. Setting one half makes anchoring silently never run. Preflight catches it — but only once you knew to set anything at all.
• The PEM must be single-line with \n escapes. A real multi-line value breaks Docker's env_file parsing. pemToBytes handles the escapes, but nothing said so anywhere an operator would look.
• The Rekor shard rotates annually. When the default lags, anchors record status: failed and there was no pointer toward the override that fixes it (orb(anchor): the default Rekor shard was never deployed, and the failure it causes does not name the URL #9844, fixed separately).

Also states plainly that the ledger is per-instance — only your decisions, never other operators' — since that was the first question asked when turning it on.

Validation

docker-compose-env-example-parity and selfhost-preflight suites pass (44 tests). selfhost:config-lint clean. Comments-only addition; every line is commented out, so no default behaviour changes.

[loopover-orb]

Warning

⏸️ LoopOver review result - manual review recommended

_{Review updated: 2026-07-29 14:08:41 UTC}

1 file · 1 AI reviewer · 1 blocker · CI green · clean

⏸️ Suggested Action - Manual Review

Review summary
This is a comments-only documentation addition to `.env.selfhost.example` that adds a new section explaining `LOOPOVER_LEDGER_ANCHOR_*` variables, their all-or-nothing preflight behavior, the PEM single-line requirement, and the Rekor shard rotation issue — closing #9848 and matching the stated intent. The content itself is well-written and grounded in a real deployment experience, but the diff contains a literal, unescaped newline inside what was meant to be a single commented line, leaving a bare uncommented line in the file — ironically reproducing the exact PEM-newline pitfall the PR is trying to warn operators about.

Blockers

• The comment describing the PEM single-line requirement is broken by a literal embedded newline, leaving a bare, non-commented line (' escapes -- a real') in the example file.

Nits — 5 non-blocking

• The new section doesn't mention that `LOOPOVER_LEDGER_ANCHOR_KEYS` and `_PRIVATE_KEY` should never both be pasted as plaintext without also pointing to the secrets/ file convention used in section 1 of this same file, for consistency.
• Consider linking to `src/selfhost/preflight.ts` with a specific check/function name rather than just the file, so operators (and future maintainers) can jump straight to the validation logic.
• Fix .env.selfhost.example around the LOOPOVER_LEDGER_ANCHOR_PRIVATE_KEY line so the multi-line comment is properly re-joined onto commented lines (each continuation line prefixed with `#`), rather than containing a raw newline.
• Double check this file with a lint/parse pass (e.g. `docker-compose config --env-file` or the repo's own `selfhost:config-lint`) specifically around this new block, since the broken line may not have been caught if that lint tool only validates KEY=VALUE lines and ignores free text.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Concerns raised — review before merging

• The comment describing the PEM single-line requirement is broken by a literal embedded newline, leaving a bare, non-commented line (' escapes -- a real') in the example file.

📋 Copy for AI agents — paste into your coding agent

Fix the following blocker(s) from this PR review:

1. The comment describing the PEM single-line requirement is broken by a literal embedded newline, leaving a bare, non-commented line \(' escapes -- a real'\) in the example file.

Decision drivers

• ❌ Code review — 1 blocker (1 reviewer)
• ❌ Gate result — Blocking (Repo-configured hard blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#9848
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 14 registered-repo PR(s), 13 merged, 345 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 14 PR(s), 345 issue(s).
Improvement	ℹ️ Insufficient signal	risk: clean · value: insufficient-signal

Linked issue satisfaction

Addressed
The PR adds a documented, commented-out section in .env.selfhost.example covering all the issue's stated items: what anchoring buys, per-instance ledger scope, the keygen command, the all-or-nothing constraint, the PEM \n-escape requirement, the Rekor shard override with a live default value, and the git backend variables. This directly matches the fix and deliverable described in the issue.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is registered but has no active allocation in the current snapshot.
• Public profile languages: Python, TypeScript, Ruby, Go, MDX, Shell, Solidity, JavaScript
• Official Gittensor activity: 14 PR(s), 345 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Then work through the remaining 1 step in the Signals table above.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

Decision record

• action: hold · clause: ai_consensus_defect
• config: ab45332097dbc61f4eeb1c1141924104da2db965d6eecae5fb3972635d0853c7 · pack: oss-anti-slop · ci: failed
• model: claude-code · prompt: feaefedf68013179f20784c8529ed2c8548151f77076e687ec9b8239d4362bbd · confidence: 0.85
• record: a590cb1515ed0cf1aa7461f7e97581669ac299adb7bb6818cfdcb40e29452926 (schema v5, head 141404f)

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[JSONbored]

Already fixed — that review ran against 60d900aed, which I force-pushed over with de8394059 before it posted.

You're right that it was exactly the pitfall the section warns about: a \n inside my heredoc became a real newline, splitting the comment and leaving a bare uncommented line plus trailing whitespace. The changes job caught it, which is how I noticed.

On the current head:

trailing-whitespace lines: NONE
uncommented lines in section: NONE

'# LOOPOVER_LEDGER_ANCHOR_PRIVATE_KEY=       # SECRET, PKCS8 PEM. Must be ONE line, with the newlines'
'                                            # written as literal backslash-n escapes: a real multi-line'
'                                            # value breaks Docker'\''s env_file parsing.'

Rewritten as prose across three properly-commented lines rather than embedding an escape sequence in a comment that then has to survive every tool between here and the file. All checks green.