feat(github-app): add maintainer trust checklist

[bitloi]

Summary

• Adds a maintainer trust checklist to the repo settings preview response and control-panel preview.
• Summarizes install permissions, public outputs, private-only context, command authorization, audit behavior, sanitizer boundaries, and manual-control expectations before repo command enablement.
• Updates OpenAPI plus unit/integration coverage for ready, blocked, needs-attention, missing permission, missing webhook, and public-output safety paths.

Closes #245

Screenshots

Screenshots captured against npm run ui:preview with mocked API fixtures. Click a thumbnail to open the full-size screenshot in GitHub.

Ready state	Needs-attention state
Compact checklist with all trust areas ready and the scope/control details collapsed.	Compact checklist with attention rows grouped into a single review-before-enabling callout.

Scope

• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; global coverage stays at or above 97% for lines, statements, functions, and branches (aim for 98%+ branch coverage locally so CI variance does not fail near the threshold)
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:version-audit
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• None. npm run test:ci passed on the rebased branch.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include screenshots or a short recording.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

• OpenAPI is regenerated for the new installPreview response contract.
• No migrations, deploy configuration, dependencies, secrets, or changelog updates are included.
• Screenshot thumbnails link to full-size GitHub image pages; PNGs are hosted from a screenshot-only helper branch in the fork so binary assets are not part of this PR diff.

[dosubot]

Related Knowledge

1 document with suggested updates is ready for review.

gittensory

For Maintainers

View Suggested Changes

@@ -127,6 +127,60 @@
 - Dry-run decision (skip, comment, label, or check run)
 - Preview label and check-run state
 - Sanitized public comment preview
+- **installPreview**: A maintainer trust checklist covering permissions, public outputs, private context, command authorization, audit behavior, sanitizer boundaries, and manual controls
+
+#### Install Preview Checklist
+
+The `installPreview` field provides a comprehensive pre-enablement checklist for maintainers. It includes:
+
+**Overall status**: `ready`, `needs_attention`, or `blocked`
+
+**Summary**: Human-readable install readiness summary
+
+**Read scope**: What data is accessed from the cached repository
+
+**Computed context**: What context is computed for the preview
+
+**Preview behavior**: Notes about the read-only nature of the preview
+
+**Permissions**: Nested object containing:
+- `status`: Permission readiness status (`ready`, `needs_attention`, `blocked`)
+- `required`: List of required permissions for the previewed behavior
+- `missing`: List of missing permissions
+- `missingEvents`: List of missing webhook events
+- `summary`: Permission status summary
+
+**Public outputs**: Array describing what will be publicly visible (e.g., "One sanitized sticky PR comment", "Configured label \"gittensor\"", "Minimal GitHub check run")
+
+**Private-only context**: Array of data that remains authenticated-only (decision packs, blocker details, maintainer packet evidence, scoring evidence)
+
+**Command authorization**: Array describing authorization rules for commands (maintainer-only, confirmed PR author, private API access)
+
+**Audit behavior**: Array describing audit logging behavior (read-only preview, webhook skip logging, command handling logs)
+
+**Sanitizer boundaries**: Array describing what content gets sanitized (public comments, credential/key material, compensation estimates, trust metrics, score-prediction claims, private review evidence, gaming language)
+
+**Manual controls**: Array of settings that remain under maintainer control (public surface mode, comment mode, label name, check-run mode, maintainer-author inclusion, linked-issue requirements)
+
+**Checklist**: Array of checklist items, each containing:
+- `id`: Unique identifier
+- `category`: One of `permissions`, `public_outputs`, `private_context`, `command_authorization`, `audit`, `sanitizer`, `manual_control`
+- `status`: Item status (`ready`, `needs_attention`, `blocked`)
+- `label`: Display label
+- `summary`: Description of the item
+- `action`: What the maintainer should do
+
+The checklist covers seven key areas that maintainers should review before enabling repo commands:
+
+1. **Permissions and webhook events** — Verifies required GitHub App permissions and webhook event subscriptions are in place
+2. **Public outputs** — Shows what will be posted publicly (comments, labels, check runs) and warns if all-PR mode is enabled
+3. **Private-only context** — Confirms that decision packs, blocker details, maintainer packet evidence, and scoring evidence stay authenticated-only
+4. **Command authorization** — Describes who can invoke commands (maintainer-only commands, confirmed PR author commands, private API commands)
+5. **Audit behavior** — Clarifies that the preview is read-only and explains what gets logged in production
+6. **Sanitizer boundaries** — Ensures maintainers understand what content gets sanitized before public posting
+7. **Manual controls** — Lists the repo settings that remain under maintainer control
+
+This information helps maintainers understand what will happen when they enable Gittensory for their repository, particularly around security, privacy, and permission requirements.
 
 ### Repository Configuration Options
 

✅ Accepted

^{How did I do? Any feedback?}  

[JSONbored]

@bitloi hmm, i like the concept but i think we need to tighten up the design aspects a lot/make this visually much simpler/more consolidated - thoughts?

[bitloi]

@bitloi hmm, i like the concept but i think we need to tighten up the design aspects a lot/make this visually much simpler/more consolidated - thoughts?

Thanks, agreed. I tightened this up in the latest push:

• consolidated the checklist into a single compact row/table layout
• moved remediation into one “Review before enabling” callout
• collapsed the longer scope/control details behind a single details section
• updated the PR screenshots to show the simpler version

The branch is updated and CI is green now. Curious if this direction feels closer.

[JSONbored]

@bitloi this is still in request-changes state.

A few notes:

• The maintainer trust checklist concept is useful.
• OpenAPI and test coverage are in the right surfaces.
• The remaining blocker is presentation/evidence: the screenshots should be compact clickable thumbnails with clear state captions, and the UI should be simplified per the existing maintainer review.

Required changes:

• Convert the screenshots to a compact captioned thumbnail table/grid in the PR description. (you can drag and drop screenshots directly into the PR description, then properly format following our contribution guidelines - I should be able to click and expand them without having to download raw PNG files, as happened in another PR).
• Address the requested visual simplification/consolidation pass.
• Re-request review after updating the evidence and UI.

Validation expected:

• Keep CI green.
• Reconfirm npm run ui:build and npm run ui:lint after UI changes.

[bitloi]

@bitloi this is still in request-changes state.

A few notes:

• The maintainer trust checklist concept is useful.
• OpenAPI and test coverage are in the right surfaces.
• The remaining blocker is presentation/evidence: the screenshots should be compact clickable thumbnails with clear state captions, and the UI should be simplified per the existing maintainer review.

Required changes:

• Convert the screenshots to a compact captioned thumbnail table/grid in the PR description. (you can drag and drop screenshots directly into the PR description, then properly format following our contribution guidelines - I should be able to click and expand them without having to download raw PNG files, as happened in another PR).
• Address the requested visual simplification/consolidation pass.
• Re-request review after updating the evidence and UI.

Validation expected:

• Keep CI green.
• Reconfirm npm run ui:build and npm run ui:lint after UI changes.

I updated the evidence and presentation:

• converted the screenshots into a compact captioned thumbnail grid in the PR description
• kept the images clickable/expandable in GitHub instead of raw PNG download-style links
• tightened the checklist presentation further around the consolidated layout
• reran npm run ui:lint and npm run ui:build