Miner quickstart by contribution lane

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 --json 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.

0. Install and sign in (every lane)

The MCP is published as @jsonbored/gittensory-mcp. Run it with npx or install it globally, then authenticate with GitHub Device Flow — Gittensory never asks for a Personal Access Token.

# 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

1. Choose your lane

Lanes describe how you contribute. Pick the one that matches the work in front of you, then read what the target repo actually supports: agent plan and repo-decision report the repo's configured lane so you can align before you start.

# 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

The repo's configured lane comes back as one of these (it is set by the repo's registry config, not by you):

• direct_pr — implementation PRs only. Prefer focused PRs with clear evidence, linked context, and low review churn.
• issue_discovery — discovery work only. Focus on high-proof issue reports and avoid self-resolved issue loops.
• split — both paths are active. Pick one intentionally: issue discovery for reports, direct PR for implementation.
• inactive — registered but with no current allocation. Treat it as normal upstream contribution work unless the registry changes.
• unknown — not registered (or no config yet). Do not assume the repo is ready for Gittensor-specific contribution guidance.

2. Direct PR lane

You are implementing a change and opening a PR directly. Use this in a direct_pr or split repo. Plan, preflight your branch metadata, then generate the public-safe packet to paste into the PR body.

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

3. Issue-solving PR lane

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.

# 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

4. Issue discovery lane

You are reporting a high-proof issue rather than opening a PR. Use this in an issue_discovery or split repo. Start from the plan to see which discovery work is worth it, and keep reports specific and reproducible — avoid self-resolved loops.

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

5. Docs and context work

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.

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

6. Repo-specific lanes

Some repos run their own lane policy. Always let the repo tell you: repo-decision returns the configured lane plus contributor guidance, and analyze-branch lets you model a scenario (pending merges, expected open PRs) before you commit to a path.

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

Validation expectations (every lane)

Before you open anything, the loop should be clean: doctor green, your branch metadata preflighted, and a validation note attached. Pass what you actually ran via --validation "status|command|summary" (for example "passed|npm test|all green") so the preflight verdict reflects real validation, not a guess.

gittensory-mcp doctor --json
gittensory-mcp preflight --login your-login --repo owner/repo --base origin/main --validation "passed|npm test|summary" --json