docs(launch): miner quickstart by contribution lane (#252)

apps/gittensory-ui/src/routeTree.gen.ts

@@ -25,9 +25,10 @@
 import { Route as DocsUpstreamDriftRouteImport } from './routes/docs.upstream-drift'
 import { Route as DocsTroubleshootingRouteImport } from './routes/docs.troubleshooting'
 import { Route as DocsScoreabilityRouteImport } from './routes/docs.scoreability'
 import { Route as DocsQuickstartRouteImport } from './routes/docs.quickstart'
 import { Route as DocsPrivacySecurityRouteImport } from './routes/docs.privacy-security'
 import { Route as DocsMinerWorkflowRouteImport } from './routes/docs.miner-workflow'
+import { Route as DocsMinerQuickstartRouteImport } from './routes/docs.miner-quickstart'
 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'
@@ -144,6 +145,11 @@
   path: '/miner-workflow',
   getParentRoute: () => DocsRoute,
 } as any)
+const DocsMinerQuickstartRoute = DocsMinerQuickstartRouteImport.update({
+  id: '/miner-quickstart',
+  path: '/miner-quickstart',
+  getParentRoute: () => DocsRoute,
+} as any)
 const DocsMcpClientsRoute = DocsMcpClientsRouteImport.update({
   id: '/mcp-clients',
   path: '/mcp-clients',
@@ -277,6 +283,7 @@
   '/docs/maintainer-install-trust': typeof DocsMaintainerInstallTrustRoute
   '/docs/maintainer-workflow': typeof DocsMaintainerWorkflowRoute
   '/docs/mcp-clients': typeof DocsMcpClientsRoute
+  '/docs/miner-quickstart': typeof DocsMinerQuickstartRoute
   '/docs/miner-workflow': typeof DocsMinerWorkflowRoute
   '/docs/privacy-security': typeof DocsPrivacySecurityRoute
   '/docs/quickstart': typeof DocsQuickstartRoute
@@ -315,6 +322,7 @@
   '/docs/maintainer-install-trust': typeof DocsMaintainerInstallTrustRoute
   '/docs/maintainer-workflow': typeof DocsMaintainerWorkflowRoute
   '/docs/mcp-clients': typeof DocsMcpClientsRoute
+  '/docs/miner-quickstart': typeof DocsMinerQuickstartRoute
   '/docs/miner-workflow': typeof DocsMinerWorkflowRoute
   '/docs/privacy-security': typeof DocsPrivacySecurityRoute
   '/docs/quickstart': typeof DocsQuickstartRoute
@@ -357,6 +365,7 @@
   '/docs/maintainer-install-trust': typeof DocsMaintainerInstallTrustRoute
   '/docs/maintainer-workflow': typeof DocsMaintainerWorkflowRoute
   '/docs/mcp-clients': typeof DocsMcpClientsRoute
+  '/docs/miner-quickstart': typeof DocsMinerQuickstartRoute
   '/docs/miner-workflow': typeof DocsMinerWorkflowRoute
   '/docs/privacy-security': typeof DocsPrivacySecurityRoute
   '/docs/quickstart': typeof DocsQuickstartRoute
@@ -400,6 +409,7 @@
     | '/docs/maintainer-install-trust'
     | '/docs/maintainer-workflow'
     | '/docs/mcp-clients'
+    | '/docs/miner-quickstart'
     | '/docs/miner-workflow'
     | '/docs/privacy-security'
     | '/docs/quickstart'
@@ -438,6 +448,7 @@
     | '/docs/maintainer-install-trust'
     | '/docs/maintainer-workflow'
     | '/docs/mcp-clients'
+    | '/docs/miner-quickstart'
     | '/docs/miner-workflow'
     | '/docs/privacy-security'
     | '/docs/quickstart'
@@ -479,6 +490,7 @@
     | '/docs/maintainer-install-trust'
     | '/docs/maintainer-workflow'
     | '/docs/mcp-clients'
+    | '/docs/miner-quickstart'
     | '/docs/miner-workflow'
     | '/docs/privacy-security'
     | '/docs/quickstart'
@@ -638,6 +650,13 @@
       preLoaderRoute: typeof DocsMinerWorkflowRouteImport
       parentRoute: typeof DocsRoute
     }
+    '/docs/miner-quickstart': {
+      id: '/docs/miner-quickstart'
+      path: '/miner-quickstart'
+      fullPath: '/docs/miner-quickstart'
+      preLoaderRoute: typeof DocsMinerQuickstartRouteImport
+      parentRoute: typeof DocsRoute
+    }
     '/docs/mcp-clients': {
       id: '/docs/mcp-clients'
       path: '/mcp-clients'
@@ -835,6 +854,7 @@
   DocsMaintainerInstallTrustRoute: typeof DocsMaintainerInstallTrustRoute
   DocsMaintainerWorkflowRoute: typeof DocsMaintainerWorkflowRoute
   DocsMcpClientsRoute: typeof DocsMcpClientsRoute
+  DocsMinerQuickstartRoute: typeof DocsMinerQuickstartRoute
   DocsMinerWorkflowRoute: typeof DocsMinerWorkflowRoute
   DocsPrivacySecurityRoute: typeof DocsPrivacySecurityRoute
   DocsQuickstartRoute: typeof DocsQuickstartRoute
@@ -852,6 +872,7 @@
   DocsMaintainerInstallTrustRoute: DocsMaintainerInstallTrustRoute,
   DocsMaintainerWorkflowRoute: DocsMaintainerWorkflowRoute,
   DocsMcpClientsRoute: DocsMcpClientsRoute,
+  DocsMinerQuickstartRoute: DocsMinerQuickstartRoute,
   DocsMinerWorkflowRoute: DocsMinerWorkflowRoute,
   DocsPrivacySecurityRoute: DocsPrivacySecurityRoute,
   DocsQuickstartRoute: DocsQuickstartRoute,

apps/gittensory-ui/src/routes/docs.index.tsx

@@ -55,9 +55,10 @@
     icon: <Compass className="size-4" />,
     title: "Miners",
     description: "Plan better work, preflight branches, prepare PR packets.",
     primary: { to: "/docs/beta-onboarding", label: "Beta onboarding" },
     links: [
       { to: "/docs/quickstart", label: "Quickstart" },
+      { to: "/docs/miner-quickstart", label: "Quickstart by lane" },
       { to: "/docs/miner-workflow", label: "Miner workflow" },
       { to: "/docs/branch-analysis", label: "Branch analysis" },
       { to: "/docs/scoreability", label: "Scoreability" },

apps/gittensory-ui/src/routes/docs.miner-quickstart.tsx

@@ -0,0 +1,191 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { DocsPage } from "@/components/site/docs-page";
+import { CodeBlock, Callout } from "@/components/site/primitives";
+
+export const Route = createFileRoute("/docs/miner-quickstart")({
+  head: () => ({
+    meta: [
+      { title: "Miner quickstart by lane — Gittensory docs" },
+      {
+        name: "description",
+        content:
+          "Pick a contribution lane, install @jsonbored/gittensory-mcp, sign in, and run plan → preflight → packet. Lane-by-lane commands with JSON output and redaction notes.",
+      },
+      { property: "og:title", content: "Miner quickstart by lane — Gittensory docs" },
+      {
+        property: "og:description",
+        content:
+          "Pick a contribution lane, install @jsonbored/gittensory-mcp, sign in, and run plan → preflight → packet. Lane-by-lane commands with JSON output and redaction notes.",
+      },
+      { property: "og:url", content: "/docs/miner-quickstart" },
+    ],
+    links: [{ rel: "canonical", href: "/docs/miner-quickstart" }],
+  }),
+  component: MinerQuickstart,
+});
+
+function MinerQuickstart() {
+  return (
+    <DocsPage
+      eyebrow="Get started"
+      title="Miner quickstart by contribution lane"
+      description="Choose how you want to contribute, then follow the same loop — install, sign in, doctor, plan, preflight, packet — with the flags that fit your lane. About five minutes per lane."
+    >
+      <p>
+        Gittensory is copilot-only. It ranks and explains your options and drafts public-safe PR
+        packets. It does not edit code, open PRs, or post comments for you, it makes no earnings
+        promises, and it never predicts a public number. Every command below also accepts{" "}
+        <code>--json</code> for machine-readable output, and your source never leaves your machine —
+        only branch metadata (changed file paths, commit messages) is sent to authenticated
+        Gittensory MCP/API responses.
+      </p>
+
+      <h2>0. Install and sign in (every lane)</h2>
+      <p>
+        The MCP is published as <code>@jsonbored/gittensory-mcp</code>. Run it with <code>npx</code>{" "}
+        or install it globally, then authenticate with GitHub Device Flow — Gittensory never asks
+        for a Personal Access Token.
+      </p>
+      <CodeBlock
+        code={`# install (one-off, or global)
+npx -y @jsonbored/gittensory-mcp@latest --help
+npm i -g @jsonbored/gittensory-mcp@latest
+
+# sign in, confirm identity, check the session
+gittensory-mcp login
+gittensory-mcp whoami --json
+gittensory-mcp status --json
+
+# verify API, auth, and the local scorer before any analysis
+gittensory-mcp doctor --json`}
+      />
+      <Callout variant="safety">
+        Session tokens are <strong>Gittensory tokens backed by GitHub identity</strong>, not your
+        GitHub PATs. Source upload stays disabled (<code>GITTENSORY_UPLOAD_SOURCE=false</code>) and
+        local absolute paths are redacted from anything that leaves your machine. Log out anytime
+        with <code>gittensory-mcp logout</code>.
+      </Callout>
+
+      <h2>1. Choose your lane</h2>
+      <p>
+        Lanes describe <em>how</em> you contribute. Pick the one that matches the work in front of
+        you, then read what the target repo actually supports: <code>agent plan</code> and{" "}
+        <code>repo-decision</code> report the repo&apos;s configured lane so you can align before
+        you start.
+      </p>
+      <CodeBlock
+        code={`# what should I work on next, and what lane does this repo support?
+gittensory-mcp agent plan --login your-login --repo owner/repo --json
+gittensory-mcp repo-decision --login your-login --repo owner/repo --json`}
+      />
+      <p>
+        The repo&apos;s configured lane comes back as one of these (it is set by the repo&apos;s
+        registry config, not by you):
+      </p>
+      <ul>
+        <li>
+          <code>direct_pr</code> — implementation PRs only. Prefer focused PRs with clear evidence,
+          linked context, and low review churn.
+        </li>
+        <li>
+          <code>issue_discovery</code> — discovery work only. Focus on high-proof issue reports and
+          avoid self-resolved issue loops.
+        </li>
+        <li>
+          <code>split</code> — both paths are active. Pick one intentionally: issue discovery for
+          reports, direct PR for implementation.
+        </li>
+        <li>
+          <code>inactive</code> — registered but with no current allocation. Treat it as normal
+          upstream contribution work unless the registry changes.
+        </li>
+        <li>
+          <code>unknown</code> — not registered (or no config yet). Do not assume the repo is ready
+          for Gittensor-specific contribution guidance.
+        </li>
+      </ul>
+
+      <h2>2. Direct PR lane</h2>
+      <p>
+        You are implementing a change and opening a PR directly. Use this in a{" "}
+        <code>direct_pr</code> or <code>split</code> repo. Plan, preflight your branch metadata,
+        then generate the public-safe packet to paste into the PR body.
+      </p>
+      <CodeBlock
+        code={`gittensory-mcp agent plan --login your-login --repo owner/repo --json
+gittensory-mcp preflight --login your-login --repo owner/repo --base origin/main --validation "passed|npm test|summary" --json
+gittensory-mcp agent packet --login your-login --repo owner/repo --base origin/main --json`}
+      />
+
+      <h2>3. Issue-solving PR lane</h2>
+      <p>
+        You are fixing a specific open issue. Same loop as a direct PR, but link the issue in your
+        branch so preflight can credit the linked context. Confirm the linked-issue signal in the
+        preflight output before opening the PR.
+      </p>
+      <CodeBlock
+        code={`# branch named/described so the linked issue is detected, e.g. "Fixes #123"
+gittensory-mcp agent plan --login your-login --repo owner/repo --json
+gittensory-mcp preflight --login your-login --repo owner/repo --base origin/main --branch-eligibility eligible --validation "passed|npm test|summary" --json
+gittensory-mcp agent packet --login your-login --repo owner/repo --base origin/main --json`}
+      />
+
+      <h2>4. Issue discovery lane</h2>
+      <p>
+        You are reporting a high-proof issue rather than opening a PR. Use this in an{" "}
+        <code>issue_discovery</code> or <code>split</code> repo. Start from the plan to see which
+        discovery work is worth it, and keep reports specific and reproducible — avoid self-resolved
+        loops.
+      </p>
+      <CodeBlock
+        code={`gittensory-mcp agent plan --login your-login --repo owner/repo --objective "find a high-proof issue" --json
+gittensory-mcp decision-pack --login your-login --json`}
+      />
+
+      <h2>5. Docs and context work</h2>
+      <p>
+        Documentation and context contributions still ship as PRs, so they follow the direct PR
+        loop. Run preflight on the branch metadata and generate a packet — the packet is the same
+        public-safe artifact regardless of whether the change is code or docs.
+      </p>
+      <CodeBlock
+        code={`gittensory-mcp agent plan --login your-login --repo owner/repo --json
+gittensory-mcp preflight --login your-login --repo owner/repo --base origin/main --validation "passed|docs build|summary" --json
+gittensory-mcp agent packet --login your-login --repo owner/repo --base origin/main --json`}
+      />
+
+      <h2>6. Repo-specific lanes</h2>
+      <p>
+        Some repos run their own lane policy. Always let the repo tell you:{" "}
+        <code>repo-decision</code> returns the configured lane plus contributor guidance, and{" "}
+        <code>analyze-branch</code> lets you model a scenario (pending merges, expected open PRs)
+        before you commit to a path.
+      </p>
+      <CodeBlock
+        code={`gittensory-mcp repo-decision --login your-login --repo owner/repo --json
+gittensory-mcp analyze-branch --login your-login --repo owner/repo --base origin/main --pending-merged-prs 3 --expected-open-prs 0 --scenario-note "after the queue clears" --json`}
+      />
+
+      <h2>Validation expectations (every lane)</h2>
+      <p>
+        Before you open anything, the loop should be clean: <code>doctor</code> green, your branch
+        metadata preflighted, and a validation note attached. Pass what you actually ran via{" "}
+        <code>--validation &quot;status|command|summary&quot;</code> (for example{" "}
+        <code>&quot;passed|npm test|all green&quot;</code>) so the preflight verdict reflects real
+        validation, not a guess.
+      </p>
+      <CodeBlock
+        code={`gittensory-mcp doctor --json
+gittensory-mcp preflight --login your-login --repo owner/repo --base origin/main --validation "passed|npm test|summary" --json`}
+      />
+      <Callout variant="safety">
+        The PR packet from <code>agent packet</code> is <strong>public-safe</strong>: it is scrubbed
+        of economic and identity signals (wallet/hotkey, payout, trust-score, ranking, and
+        public-prediction language) before it can be pasted into a public GitHub surface. Pair this
+        page with the <a href="/docs/miner-workflow">miner workflow</a> for the full loop and{" "}
+        <a href="/docs/privacy-security">privacy &amp; security</a> for the boundary details.
+      </Callout>
+    </DocsPage>
+  );
+}

test/unit/docs-miner-quickstart.test.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const MINER_QUICKSTART_PATH = resolve(
+  import.meta.dirname,
+  "../../apps/gittensory-ui/src/routes/docs.miner-quickstart.tsx",
+);
+
+describe("docs miner quickstart page", () => {
+  const source = readFileSync(MINER_QUICKSTART_PATH, "utf8");
+  const normalizedSource = source.replace(/\s+/g, " ");
+
+  it("documents the full miner loop: install, auth, doctor, plan, preflight, packet", () => {
+    expect(source).toMatch(/@jsonbored\/gittensory-mcp/);
+    expect(source).toMatch(/gittensory-mcp login/);
+    expect(source).toMatch(/gittensory-mcp whoami/);
+    expect(source).toMatch(/gittensory-mcp status/);
+    expect(source).toMatch(/gittensory-mcp doctor/);
+    expect(source).toMatch(/agent plan --login/);
+    expect(source).toMatch(/gittensory-mcp preflight --login/);
+    expect(source).toMatch(/agent packet --login/);
+  });
+
+  it("uses CLI commands that match the current MCP package syntax", () => {
+    // Real flags from `gittensory-mcp --help` — guards against drift in documented syntax.
+    expect(source).toMatch(/--repo owner\/repo/);
+    expect(source).toMatch(/--base origin\/main/);
+    expect(source).toMatch(/--branch-eligibility eligible/);
+    expect(source).toMatch(/--pending-merged-prs/);
+    expect(source).toMatch(/--expected-open-prs/);
+    expect(source).toMatch(/repo-decision --login/);
+    expect(source).toMatch(/decision-pack --login/);
+    expect(source).toMatch(/analyze-branch --login/);
+  });
+
+  it("organizes the quickstart by contribution lane", () => {
+    expect(source).toMatch(/Direct PR lane/);
+    expect(source).toMatch(/Issue-solving PR lane/);
+    expect(source).toMatch(/Issue discovery lane/);
+    expect(source).toMatch(/Docs and context work/);
+    expect(source).toMatch(/Repo-specific lanes/);
+    expect(source).toMatch(/Choose your lane/);
+  });
+
+  it("maps lanes to the repo's configured participation lane from code", () => {
+    // These must match ParticipationLane in src/signals/engine.ts so the doc reflects real config.
+    expect(source).toMatch(/direct_pr/);
+    expect(source).toMatch(/issue_discovery/);
+    expect(source).toMatch(/split/);
+    expect(source).toMatch(/inactive/);
+    expect(source).toMatch(/unknown/);
+  });
+
+  it("includes JSON-output notes for automation on every command", () => {
+    expect(source).toMatch(/--json/);
+    expect(normalizedSource).toMatch(/machine-readable output/i);
+  });
+
+  it("documents the local privacy boundary and packet redaction", () => {
+    expect(normalizedSource).toMatch(/source never leaves your machine/i);
+    expect(source).toMatch(/GITTENSORY_UPLOAD_SOURCE=false/);
+    expect(source).toMatch(/local absolute paths are redacted/i);
+    expect(source).toMatch(/public-safe/i);
+    expect(normalizedSource).toMatch(/scrubbed of economic and identity signals/i);
+  });
+
+  it("documents validation expectations with the real --validation flag", () => {
+    expect(source).toMatch(/Validation expectations/);
+    expect(source).toMatch(/--validation/);
+  });
+
+  it("avoids reward guarantees and public score-prediction language", () => {
+    expect(source).toMatch(/makes no earnings\s+promises/i);
+    expect(source).toMatch(/never predicts a public number/i);
+    expect(source).not.toMatch(/you will (earn|receive|get)/i);
+    expect(source).not.toMatch(/guaranteed (reward|payout|score)/i);
+    expect(source).not.toMatch(/predict(s|ed)?\s+your\s+score/i);
+    // Identity secrets must never appear in onboarding copy or examples.
+    expect(source).not.toMatch(/seed phrase|mnemonic|private key/i);
+  });
+});