docs(selfhost): fill config/env doc gaps and reconcile checkRunDetailLevel default mismatch

[JSONbored]

Summary

Three related gaps in self-host config surfacing, found together during a 2026-07-04 audit and a follow-up conversation about the "Gittensory Context" check:

1. .gittensory.yml.example is missing several real, consumed top-level/settings fields.
2. Several real, working self-host env vars are undocumented in .env.example.
3. checkRunDetailLevel has two different defaults depending on write path, and the self-host docs (README, .env.example) never explain the check-run system (checkRunMode/gateCheckMode/checkRunDetailLevel) at all, which is exactly what caused confusion about whether "Gittensory Context" is the same thing as inline PR review comments (it is not — see Context below).

Part of #1667.

Context

.gittensory.yml.example gaps — these fields are parsed and live-consumed but absent from the example file (not even a commented-out stub):

• settings.closeOwnerAuthors — parsed at src/signals/focus-manifest.ts:991, consumed at src/settings/agent-actions.ts:561 and src/services/agent-approval-queue.ts:131,249.
• The top-level features: block (per-repo overrides of GITTENSORY_REVIEW_* deployment flags — rag/reputation/unifiedComment/safety), CONVERGED_FEATURE_KEYS at focus-manifest.ts:117.
• The top-level contentLane: block, parseContentLaneConfig at focus-manifest.ts:880-898.
• (settings.contributorBlacklist and the moderation-rules block (moderationGateMode, moderationRules, moderationWarningLabel, moderationBannedLabel) are also undocumented, but may be deliberately omitted from the public example since they carry moderation/banned-username-adjacent semantics — confirm with the maintainer before documenting these two rather than just adding them.)

.env.example gaps — all real, working, currently-undocumented env vars:

• SLACK_WEBHOOK_URL (src/services/notify-discord.ts:96-103, typed in src/env.d.ts:151) — has no per-repo map unlike Discord's DISCORD_REPO_WEBHOOKS; confirm that asymmetry is intentional when documenting it.
• AI_EMBED_BASE_URL / AI_EMBED_API_KEY (src/server.ts:421-431) — routes embeddings to a separate OpenAI-compatible endpoint; its sibling AI_EMBED_MODEL is documented but these are not, so the feature is currently undiscoverable.
• BACKUP_ACKNOWLEDGED (src/selfhost/health.ts:173-180, read at src/server.ts:367) — silences a boot-time SQLite-backup-safety warning.
• ORB_COLLECTOR_TOKEN (src/selfhost/orb-collector.ts:8-13,205) — the other 3 Orb env vars in the same source comment are documented, this one is not.
• ORB_RELAY_MODE (src/server.ts:944-972) — push vs. pull deployment mode (pull is the right fit behind NAT/tailnet); currently undiscoverable from the sample env file.
• REVIEW_AUDIT_DIR (src/server.ts:557-562) and SETUP_OUTPUT_PATH (src/server.ts:820) — lower priority, both have safe defaults, but worth a one-line mention each.

checkRunDetailLevel default mismatch — src/db/schema.ts:52 defaults the column to "minimal", but src/api/routes.ts:610's Zod schema defaults to "standard" for the same field. Depending on which code path creates/updates a repo's settings row, the same "unset" state resolves to two different behaviors. gateCheckMode and checkRunMode do NOT have this mismatch (both consistently default to "off" in both places) — only checkRunDetailLevel diverges.

Gittensory Context is not documented for self-host operators, and is easy to mistake for inline review comments — this was a live point of confusion in this project: "Gittensory Context" (src/review/check-names.ts) is a GitHub Check Run, off by default (checkRunMode defaults to "off"), that at checkRunDetailLevel: minimal posts only a static "No detailed findings are published in check runs" body, and at standard/deep can additionally attach GitHub Check Run annotations (line-anchored markers in the Files Changed view, sourced from formatCheckRunOutput/buildCheckRunAnnotations in src/rules/advisory.ts) — but these annotations are not reply-able discussion threads. The feature that posts real, reply-able inline PR review comment threads is a completely separate module, src/review/inline-comments.ts (the CodeRabbit-style line-level layer), gated independently by GITTENSORY_REVIEW_INLINE_COMMENTS (env, default off) + the per-repo .gittensory.yml review.inline_comments toggle + a cutover allowlist — "Default OFF at BOTH layers" per its own doc comment. The hosted-app UI has a reasonable explanation of the Context/Gate split at apps/gittensory-ui/src/routes/docs.github-app.tsx:42-43,148-162, but this is not mirrored anywhere in the self-host README or .env.example/.env.selfhost.example, so a self-host operator has no way to discover any of this without reading source.

Requirements

• Fill the identified .gittensory.yml.example gaps (closeOwnerAuthors, features:, contentLane:); explicitly decide (and note the decision in the PR) whether contributorBlacklist/moderation fields should be documented too or intentionally left out of the public example.
• Add the identified .env.example (and .env.selfhost.example if it's a separately-maintained file — verify) entries with a one-line description each, matching the existing style in those files.
• Fix the checkRunDetailLevel default mismatch — pick one canonical default (recommend "minimal", matching the DB schema and the "public output is intentionally minimal" design intent already documented in formatCheckRunOutput) and make the API route's Zod default match it. Add a regression test asserting the resolved default is consistent across both paths.
• Add a self-host-facing config/feature reference (README section or a new doc file linked from README) that documents, at minimum: checkRunMode, gateCheckMode, checkRunDetailLevel, and explicitly distinguishes the "Gittensory Context" check run from src/review/inline-comments.ts's inline review-comment threads, so this doesn't get re-confused later. This can extend the existing README "Review Capabilities" section rather than creating a whole new doc, if that fits better.
• If scripts/gen-selfhost-env-reference.mjs / apps/gittensory-ui/src/lib/selfhost-env-reference.ts are the generated source of truth for env documentation, regenerate them per the repo's Phase 4 artifact-regeneration rule rather than hand-editing only .env.example.

Deliverables

• A PR filling the documentation gaps above, plus the checkRunDetailLevel default fix with its regression test.
• Regenerated apps/gittensory-ui/src/lib/selfhost-env-reference.ts if applicable.
• No behavior change other than the single default-value reconciliation (which is itself a bug fix, not a new feature).

Expected outcome

Every self-host-relevant .gittensory.yml field and env var that's actually consumed by the code is discoverable from .gittensory.yml.example/.env.example without reading source. The check-run system's three-way default (off/off/consistent-minimal) is unambiguous regardless of which code path sets it. A self-host operator can read one place and understand exactly what "Gittensory Context" does, that it is unrelated to inline review comments, and how to turn either one on.

[linear-code]

JSO-2543