diff --git a/apps/gittensory-ui/public/sitemap.xml b/apps/gittensory-ui/public/sitemap.xml index 769cdd5267..0e666adfa3 100644 --- a/apps/gittensory-ui/public/sitemap.xml +++ b/apps/gittensory-ui/public/sitemap.xml @@ -13,6 +13,7 @@ https://gittensory.aethereal.dev/docs/miner-workflow https://gittensory.aethereal.dev/docs/maintainer-workflow https://gittensory.aethereal.dev/docs/github-app + https://gittensory.aethereal.dev/docs/maintainer-install-trust https://gittensory.aethereal.dev/docs/branch-analysis https://gittensory.aethereal.dev/docs/scoreability https://gittensory.aethereal.dev/docs/upstream-drift @@ -21,4 +22,4 @@ https://gittensory.aethereal.dev/docs/ai-summaries https://gittensory.aethereal.dev/api https://gittensory.aethereal.dev/changelog - \ No newline at end of file + diff --git a/apps/gittensory-ui/src/components/site/docs-nav.tsx b/apps/gittensory-ui/src/components/site/docs-nav.tsx index 3e011f10b9..4d2ff28ad6 100644 --- a/apps/gittensory-ui/src/components/site/docs-nav.tsx +++ b/apps/gittensory-ui/src/components/site/docs-nav.tsx @@ -21,6 +21,7 @@ export const docsNav: DocsGroup[] = [ { to: "/docs/miner-workflow", label: "Miner workflow" }, { to: "/docs/maintainer-workflow", label: "Maintainer workflow" }, { to: "/docs/github-app", label: "GitHub App" }, + { to: "/docs/maintainer-install-trust", label: "Maintainer install & trust" }, ], }, { diff --git a/apps/gittensory-ui/src/routeTree.gen.ts b/apps/gittensory-ui/src/routeTree.gen.ts index 38b93e1b4f..5730353049 100644 --- a/apps/gittensory-ui/src/routeTree.gen.ts +++ b/apps/gittensory-ui/src/routeTree.gen.ts @@ -30,6 +30,7 @@ import { Route as DocsPrivacySecurityRouteImport } from './routes/docs.privacy-s import { Route as DocsMinerWorkflowRouteImport } from './routes/docs.miner-workflow' import { Route as DocsMcpClientsRouteImport } from './routes/docs.mcp-clients' import { Route as DocsMaintainerWorkflowRouteImport } from './routes/docs.maintainer-workflow' +import { Route as DocsMaintainerInstallTrustRouteImport } from './routes/docs.maintainer-install-trust' import { Route as DocsGithubAppRouteImport } from './routes/docs.github-app' import { Route as DocsBranchAnalysisRouteImport } from './routes/docs.branch-analysis' import { Route as DocsBetaOnboardingRouteImport } from './routes/docs.beta-onboarding' @@ -152,6 +153,12 @@ const DocsMaintainerWorkflowRoute = DocsMaintainerWorkflowRouteImport.update({ path: '/maintainer-workflow', getParentRoute: () => DocsRoute, } as any) +const DocsMaintainerInstallTrustRoute = + DocsMaintainerInstallTrustRouteImport.update({ + id: '/maintainer-install-trust', + path: '/maintainer-install-trust', + getParentRoute: () => DocsRoute, + } as any) const DocsGithubAppRoute = DocsGithubAppRouteImport.update({ id: '/github-app', path: '/github-app', @@ -260,6 +267,7 @@ export interface FileRoutesByFullPath { '/docs/beta-onboarding': typeof DocsBetaOnboardingRoute '/docs/branch-analysis': typeof DocsBranchAnalysisRoute '/docs/github-app': typeof DocsGithubAppRoute + '/docs/maintainer-install-trust': typeof DocsMaintainerInstallTrustRoute '/docs/maintainer-workflow': typeof DocsMaintainerWorkflowRoute '/docs/mcp-clients': typeof DocsMcpClientsRoute '/docs/miner-workflow': typeof DocsMinerWorkflowRoute @@ -296,6 +304,7 @@ export interface FileRoutesByTo { '/docs/beta-onboarding': typeof DocsBetaOnboardingRoute '/docs/branch-analysis': typeof DocsBranchAnalysisRoute '/docs/github-app': typeof DocsGithubAppRoute + '/docs/maintainer-install-trust': typeof DocsMaintainerInstallTrustRoute '/docs/maintainer-workflow': typeof DocsMaintainerWorkflowRoute '/docs/mcp-clients': typeof DocsMcpClientsRoute '/docs/miner-workflow': typeof DocsMinerWorkflowRoute @@ -336,6 +345,7 @@ export interface FileRoutesById { '/docs/beta-onboarding': typeof DocsBetaOnboardingRoute '/docs/branch-analysis': typeof DocsBranchAnalysisRoute '/docs/github-app': typeof DocsGithubAppRoute + '/docs/maintainer-install-trust': typeof DocsMaintainerInstallTrustRoute '/docs/maintainer-workflow': typeof DocsMaintainerWorkflowRoute '/docs/mcp-clients': typeof DocsMcpClientsRoute '/docs/miner-workflow': typeof DocsMinerWorkflowRoute @@ -377,6 +387,7 @@ export interface FileRouteTypes { | '/docs/beta-onboarding' | '/docs/branch-analysis' | '/docs/github-app' + | '/docs/maintainer-install-trust' | '/docs/maintainer-workflow' | '/docs/mcp-clients' | '/docs/miner-workflow' @@ -413,6 +424,7 @@ export interface FileRouteTypes { | '/docs/beta-onboarding' | '/docs/branch-analysis' | '/docs/github-app' + | '/docs/maintainer-install-trust' | '/docs/maintainer-workflow' | '/docs/mcp-clients' | '/docs/miner-workflow' @@ -452,6 +464,7 @@ export interface FileRouteTypes { | '/docs/beta-onboarding' | '/docs/branch-analysis' | '/docs/github-app' + | '/docs/maintainer-install-trust' | '/docs/maintainer-workflow' | '/docs/mcp-clients' | '/docs/miner-workflow' @@ -627,6 +640,13 @@ declare module '@tanstack/react-router' { preLoaderRoute: typeof DocsMaintainerWorkflowRouteImport parentRoute: typeof DocsRoute } + '/docs/maintainer-install-trust': { + id: '/docs/maintainer-install-trust' + path: '/maintainer-install-trust' + fullPath: '/docs/maintainer-install-trust' + preLoaderRoute: typeof DocsMaintainerInstallTrustRouteImport + parentRoute: typeof DocsRoute + } '/docs/github-app': { id: '/docs/github-app' path: '/github-app' @@ -791,6 +811,7 @@ interface DocsRouteChildren { DocsBetaOnboardingRoute: typeof DocsBetaOnboardingRoute DocsBranchAnalysisRoute: typeof DocsBranchAnalysisRoute DocsGithubAppRoute: typeof DocsGithubAppRoute + DocsMaintainerInstallTrustRoute: typeof DocsMaintainerInstallTrustRoute DocsMaintainerWorkflowRoute: typeof DocsMaintainerWorkflowRoute DocsMcpClientsRoute: typeof DocsMcpClientsRoute DocsMinerWorkflowRoute: typeof DocsMinerWorkflowRoute @@ -807,6 +828,7 @@ const DocsRouteChildren: DocsRouteChildren = { DocsBetaOnboardingRoute: DocsBetaOnboardingRoute, DocsBranchAnalysisRoute: DocsBranchAnalysisRoute, DocsGithubAppRoute: DocsGithubAppRoute, + DocsMaintainerInstallTrustRoute: DocsMaintainerInstallTrustRoute, DocsMaintainerWorkflowRoute: DocsMaintainerWorkflowRoute, DocsMcpClientsRoute: DocsMcpClientsRoute, DocsMinerWorkflowRoute: DocsMinerWorkflowRoute, diff --git a/apps/gittensory-ui/src/routes/docs.index.tsx b/apps/gittensory-ui/src/routes/docs.index.tsx index d8f09e3db9..56f031edc5 100644 --- a/apps/gittensory-ui/src/routes/docs.index.tsx +++ b/apps/gittensory-ui/src/routes/docs.index.tsx @@ -69,6 +69,7 @@ const AUDIENCES: Audience[] = [ description: "Confirmed-miner context, sanitized comments, no noisy checks.", primary: { to: "/docs/beta-onboarding", label: "Beta onboarding" }, links: [ + { to: "/docs/maintainer-install-trust", label: "Install & trust guide" }, { to: "/docs/github-app", label: "Install the GitHub App" }, { to: "/docs/maintainer-workflow", label: "Maintainer workflow" }, { to: "/docs/upstream-drift", label: "Upstream drift" }, diff --git a/apps/gittensory-ui/src/routes/docs.maintainer-install-trust.tsx b/apps/gittensory-ui/src/routes/docs.maintainer-install-trust.tsx new file mode 100644 index 0000000000..e52220ca36 --- /dev/null +++ b/apps/gittensory-ui/src/routes/docs.maintainer-install-trust.tsx @@ -0,0 +1,236 @@ +import { createFileRoute, Link } from "@tanstack/react-router"; + +import { DocsPage } from "@/components/site/docs-page"; +import { Callout, CodeBlock, FeatureRow } from "@/components/site/primitives"; + +export const Route = createFileRoute("/docs/maintainer-install-trust")({ + head: () => ({ + meta: [ + { title: "Maintainer install and trust guide — Gittensory docs" }, + { + name: "description", + content: + "Install Gittensory as a maintainer, verify trust boundaries, preview public output, and decide when GitHub App checks are safe to enable.", + }, + { + property: "og:title", + content: "Maintainer install and trust guide — Gittensory docs", + }, + { + property: "og:description", + content: + "Install Gittensory as a maintainer, verify trust boundaries, preview public output, and decide when GitHub App checks are safe to enable.", + }, + { property: "og:url", content: "/docs/maintainer-install-trust" }, + ], + links: [{ rel: "canonical", href: "/docs/maintainer-install-trust" }], + }), + component: MaintainerInstallTrust, +}); + +function MaintainerInstallTrust() { + return ( + + + Gittensory is advisory-first. It may help you review contribution readiness, but it does not + replace human maintainer judgment, expose private scoreability signals, or make reward, + payout, wallet, hotkey, or trust-score claims in public surfaces. + + +

Install the GitHub App

+

+ Start from GitHub App setup, then keep the first rollout + narrow until the repo owner has verified permissions, webhook delivery, and public copy. +

+
    +
  1. Install Gittensory on one test repository or a selected repository set.
  2. +
  3. + Approve Metadata: read, Pull requests: read, and{" "} + Issues: write. Add Checks: write only when Context or Gate check + runs are enabled for the repository. +
  4. +
  5. + Keep webhook events enabled for issues, issue_comment,{" "} + pull_request, and repository. +
  6. +
  7. + Leave comments, labels, Context checks, and Gate checks in advisory mode until preview + output matches the repo's maintainer policy. +
  8. +
+ + +

Launch verification flow

+

+ Treat launch as a controlled trust review. Do not enable public comments or required checks + until every step below has a maintainer-visible result. +

+ verify installation health and webhook delivery + -> preview public panel and command output + -> confirm private signals stay private + -> enable advisory Context, labels, or comments + -> capture screenshots/recordings for UI or extension changes + -> decide whether Gate should be required in branch protection`} + /> + +

Maintainer controls

+ + +

Command authorization

+

+ Maintainer commands should be treated like privileged review actions. Use them to fetch + context on demand, not to create always-on public scoring. +

+ +

+ If a command would include private reviewability, private scoreability, duplicate-risk, or + contributor-history context, the result must stay in maintainer-visible surfaces. Public + replies should only contain sanitized actions a contributor can safely use. +

+ +

Public-safe previews

+

+ Preview every public output path before enabling it. The same public-safety boundary applies + to GitHub comments, issue bodies, PR bodies, extension-visible public panels, and copied + snippets. +

+
    +
  • No wallet or hotkey identifiers.
  • +
  • No reward, payout, or emission estimates.
  • +
  • No trust-score, public score prediction, or private scoreability language.
  • +
  • No private reviewability blockers or maintainer-only duplicate-risk notes.
  • +
  • No farming instructions, bounty gaming language, or rank-chasing advice.
  • +
+

+ For the full boundary, keep Privacy & security as + the source of truth. For AI-written text, use the{" "} + AI summaries policy before posting generated copy. +

+ +

Browser extension states

+

+ The extension is a maintainer review aid. It should make state and scope obvious instead of + implying that a contributor or public viewer can see private packets. +

+ no repo context, no private packet +Signed in without repo scope + -> prompt for authorized GitHub App installation or browser session +Authorized maintainer on PR page + -> public-safe PR panel + private maintainer blockers +Unauthorized viewer or stale session + -> public-safe state only, no private blockers +API unavailable or stale data + -> degraded state with retry guidance, never guessed scores`} + /> +

+ UI, frontend, browser-extension, or GitHub-overlay pull requests need maintainer-reviewable + screenshots or a short recording that shows the relevant states. A checked template box is + not enough evidence. +

+ +

Audit expectations

+

+ A healthy installation should leave an audit trail that maintainers can reason about without + exposing repository source or contributor secrets. +

+
    +
  • Installation health shows permissions and webhook readiness.
  • +
  • Settings preview shows the exact public copy before posting.
  • +
  • Command previews identify the maintainer action that produced them.
  • +
  • Extension sessions are scoped to authorized review context.
  • +
  • Failures are inspectable through diagnostics instead of silent public output.
  • +
+ +

CI checks are not reviewer approval

+

+ Keep GitHub CI/check state separate from reviewer and mergeability state. A green CI run or + advisory Context check can prove automation completed, but it does not prove the PR is + acceptable, non-duplicative, or safe to merge. Human maintainers still decide whether the + contribution fits the repo, issue, and subnet goals. +

+

+ If the repo enables Gittensory Gate, document which blockers are enforced + and why. Otherwise, treat Gittensory output as reviewer context only. +

+ +

Reject weak Gittensory-driven PRs

+

+ Maintainers should request changes or close PRs that misuse Gittensory output. The tool is a + contribution operating layer, not a guarantee that work deserves merge. +

+
    +
  • Reject PRs with no linked issue, no reproduction, or no validation evidence.
  • +
  • Reject UI or extension PRs that omit screenshots or recordings of changed flows.
  • +
  • + Reject copied snippets that leak private scoring, reward, trust, wallet, or hotkey text. +
  • +
  • Reject duplicated work when the PR does not explain overlap and maintainer value.
  • +
  • + Reject generated broad rewrites that are not scoped to the issue acceptance criteria. +
  • +
  • Reject PRs that confuse passing CI with maintainer approval.
  • +
+ +

Next docs

+

+ Continue with Maintainer workflow for daily PR + review, Troubleshooting for install diagnostics, and{" "} + Browser extension for overlay behavior. +

+
+ ); +}