docs(settings): document that publicSurface doesn't suppress either check-run

[JSONbored]

Summary

`publicSurface` governs only `shouldPublishPrComment`/`shouldApplyPrLabel` — neither the Context check (`checkRunMode`) nor the Gate check (`reviewCheckMode`) is ANDed with it, confirmed end-to-end in `processors.ts`. This is intentional (#2852: the check-run must keep posting for branch-protection/auto-merge to keep working) and already correctly documented in `registration-readiness.ts`'s maintainer-facing readiness report — but had no doc comment on the field itself, and no caveat on any of the 4 `openapi/schemas.ts` occurrences.

Scope

Docs-only, no behavior change (current behavior is load-bearing per #2852). `src/types.ts`, `src/openapi/schemas.ts` (4 occurrences), regenerated `openapi.json`.

Validation

• `npm run typecheck` — clean
• `npm run ui:openapi:check` / `npm run ui:openapi:settings-parity` — clean
• `npm run docs:drift-check` — clean
• `npm run ui:lint` — clean (0 errors)

Closes #5288

[superagent-security]

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

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	3e1bbf5	Commit Preview URL Branch Preview URL	Jul 12 2026, 01:42 PM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.37%. Comparing base (b7a410d) to head (3e1bbf5).
⚠️ Report is 8 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5311   +/-   ##
=======================================
  Coverage   94.37%   94.37%           
=======================================
  Files         474      474           
  Lines       40128    40128           
  Branches    14631    14631           
=======================================
  Hits        37869    37869           
  Misses       1583     1583           
  Partials      676      676           

Flag	Coverage Δ
shard-1	46.28% <ø> (-0.28%)	⬇️
shard-2	34.74% <ø> (+0.06%)	⬆️
shard-3	32.05% <ø> (-0.04%)	⬇️
shard-4	31.97% <ø> (-0.11%)	⬇️
shard-5	33.45% <ø> (-0.15%)	⬇️
shard-6	45.07% <ø> (+0.23%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/openapi/schemas.ts	100.00% <ø> (ø)
src/types.ts	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gittensory-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-12 13:51:16 UTC}

3 files · 2 AI reviewers · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Docs-only PR adding .describe() annotations and JSDoc comments clarifying that publicSurface doesn't gate checkRunMode/reviewCheckMode, plus regenerated openapi.json. The clarification is accurate and well-grounded (cites #2852), correctly scoped, and CI is green with no schema/behavior changes involved. One clear formatting slip: indentation is broken in three of the four schemas.ts occurrences where the .describe() chain wasn't re-indented under the field key.

Nits — 7 non-blocking

• src/openapi/schemas.ts:867 and :1269 (RepoSettingsPreviewSchema and InstallationRepairSchema publicSurface): the `.enum(...)` and `.describe(...)` lines are indented at the object's top level instead of nested under the property key, inconsistent with the correctly-indented occurrence at line 782 and the codebase's prettier/biome formatting convention — worth a quick format pass.
• Consider extracting the repeated 3-line `.describe("Governs ONLY the PR comment and label -- never ...")` string into a shared constant since it's duplicated verbatim 4 times in schemas.ts plus again in types.ts's JSDoc, so a future edit to the wording risks drifting between copies.
• The magic number `feat(selfhost): configurable review-check publish mode (required/visible/disabled) #2852` in src/types.ts:949 and the repeated description strings would be easier to keep in sync via a single exported constant referenced by both the Zod schema and the TS type doc comment.
• Run the formatter (biome/prettier) over src/openapi/schemas.ts to fix the two misaligned `.describe()` blocks noted above.
• Factor the shared description string into a single `PUBLIC_SURFACE_DESCRIPTION` constant imported by both schemas.ts and referenced in types.ts's JSDoc to avoid four-plus copies drifting apart.
• 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.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Signal	Result	Evidence
Code review	✅ No blockers	2 reviewers, synthesized
Linked issue	✅ Linked	#5288
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: 44 registered-repo PR(s), 36 merged, 476 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 44 PR(s), 476 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	⚠️ ℹ️ None detected	risk: low · value: none — No structural-improvement signals were detected for this PR. LLM value judgment: minor — This is a narrowly-scoped, accurate documentation clarification closing a real doc gap (#5288) with no behavior change, so it's a small but genuine improvement to operator-facing clarity around a previously confusing settings interaction.

Linked issue satisfaction

Addressed
The PR adds a doc comment on publicSurface in types.ts and matching .describe() caveats to all four openapi/schemas.ts enum occurrences, and regenerates openapi.json, matching all three deliverables.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 44 PR(s), 476 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

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.

[BETA] Chat with Gittensory

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

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

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop			—
/	mobile			—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

_{🟩 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 Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review