gitcontribute - npm Package Compare versions

Comparing version

0.13.0

0.14.0

+1

-1

package.json

		{
		"name": "gitcontribute",
		"version": "0.13.0",
		"version": "0.14.0",
		"description": "Local-first GitHub contribution research workbench",
		@@ -5,0 +5,0 @@ "license": "MIT",

+172

-608

README.md

		@@ -5,7 +5,4 @@ <div align="center">

		### Find better open-source contributions—with evidence, not guesswork.
		Local research and validation for GitHub contributions.

		GitContribute is a local-first research workbench for discovering, investigating,
		validating, and preparing focused GitHub contributions.

		[![CI](https://github.com/morluto/gitcontribute/actions/workflows/ci.yml/badge.svg)](https://github.com/morluto/gitcontribute/actions/workflows/ci.yml)
		@@ -15,35 +12,31 @@ [![npm](https://img.shields.io/npm/v/gitcontribute?logo=npm&color=CB3837)](https://www.npmjs.com/package/gitcontribute)
		[![License](https://img.shields.io/github/license/morluto/gitcontribute)](LICENSE)
		[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-5C6AC4)](#-platform-support)
		[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-5C6AC4)](#platform-support)

		[Quick start](#-quick-start) · [How it works](#-how-it-works) · [CLI guide](#-cli-guide) · [MCP](#-use-with-ai-agents) · [Safety](#-safety-by-design) · [Contributing](CONTRIBUTING.md)
		[Quick start](#quick-start) · [Workflow](#contribution-workflow) · [CLI](#cli) · [MCP](#mcp) · [Safety](#side-effect-boundaries) · [Documentation](#documentation)

		![GitContribute contribution workbench](docs/assets/gitcontribute-tui-workbench.png)

		</div>

		---
		`gitcontribute` is available as a CLI, terminal UI, and MCP server for coding
		agents.

		> [!IMPORTANT]
		> GitContribute never writes to GitHub. It syncs public or authenticated read-only
		> data, keeps research on your machine, and prepares local drafts for you to review.
		GitHub can show you open issues. It cannot tell you whether an issue is still
		relevant, already being implemented, appropriate for an outside contributor,
		or supported by enough evidence to work on safely.

		## Why GitContribute?
		GitContribute collects repository guidance, related issues and pull requests,
		code context, accepted contribution patterns, and validation results in a local
		SQLite corpus. Results identify missing or stale coverage.

		Finding an issue is easy. Finding a contribution that is useful, unclaimed,
		appropriately scoped, and backed by evidence is the hard part.
		```text
		find work -> understand it -> check competing work -> prove the change -> prepare the handoff
		```

		GitContribute gives developers and coding agents a durable SQLite corpus of
		repositories, issues, pull requests, reviews, code snapshots, and research
		artifacts. Network access is always explicit. Once data is synced, search,
		inspection, health analysis, dossiers, and investigations run entirely offline.
		> [!IMPORTANT]
		> GitContribute never writes to GitHub. It prepares local research and drafts
		> for you to review.

		\| \| Capability \| What it gives you \|
		\| :---: \| --- \| --- \|
		\| 🔎 \| Typed offline search \| Search repositories, issues, PRs, threads, and indexed code with transparent ranking. \|
		\| 📡 \| Contribution Radar \| Rank promising open issues with explicit positives, risks, blockers, confidence, and missing-evidence warnings. \|
		\| 🗂️ \| Durable research corpus \| Keep observations, coverage, investigations, evidence, and outcomes in local SQLite. \|
		\| 🧭 \| Contribution workflow \| Move from hypothesis to opportunity, workspace, validation, readiness checks, and a prepared issue, PR, or review. \|
		\| 🤖 \| Agent-ready MCP server \| Give Codex or Claude Code structured tools and resources with explicit capability boundaries. \|
		\| 🛡️ \| Safe by default \| Separate network reads, local writes, process execution, and GitHub mutation. \|
		## Quick start

		## ⚡ Quick start

		Run the guided setup with Node.js 18 or newer:
		@@ -55,63 +48,20 @@

		The wizard shows the resolved GitContribute version before any choice.
		The explicit `@latest` selects the current stable bootstrap even when the
		current project has an older `gitcontribute` dependency. Setup then persists
		the resolved exact version as an immutable private runtime.
		Choose MCP to use GitContribute from a supported coding agent, CLI for
		the terminal and TUI, or Both. The wizard shows every planned change before
		applying it. Adding a repository during setup does not contact GitHub or start
		a sync.

		The interactive wizard offers three access modes:
		After setup, start with a repository or an exact issue:

		- MCP — installs a private native runtime and configures selected coding agents;
		- CLI — installs the persistent `gitcontribute` command and TUI;
		- Both — installs the CLI and uses that verified executable for MCP.
		\| Task \| Coding agent \| CLI \|
		\| --- \| --- \| --- \|
		\| Find candidates \| `Find contribution candidates in owner/repo. Rank them by contribution fit, evidence, scope, and coordination risk.` \| `gitcontribute archive sync owner/repo`<br>`gitcontribute radar owner/repo --limit 10` \|
		\| Research an issue \| `Investigate owner/repo#42. Check guidance, discussion, code, prior fixes, competing work, and missing evidence.` \| `gitcontribute archive sync owner/repo --numbers 42`<br>`gitcontribute research brief issue:owner/repo#42` \|

		The wizard displays detected coding agents without treating detection as
		permission to modify them. Existing GitContribute registrations may be
		preselected; new targets require an explicit selection. GitHub authentication
		is chosen from described options rather than typed internal identifiers. A
		dry-run plan shows every effect before final confirmation, which defaults to
		apply.
		Results include source references, coverage gaps, and suggested next steps.

		`npx` only bootstraps the wizard. MCP configuration never records `npx`, an npm
		cache path, or `@latest`: it points to an absolute native executable managed by
		GitContribute.

		If you chose MCP, restart the selected coding agent and use GitContribute
		there. If you chose CLI or Both, launch the TUI, sync a repository, rank
		contribution candidates, and search the local corpus:

		```sh
		gitcontribute tui
		gitcontribute archive sync-context owner/repo
		gitcontribute archive sync owner/repo
		gitcontribute radar owner/repo --limit 10
		gitcontribute search threads "connection timeout" \
		--repo owner/repo --json
		gitcontribute dossier build owner/repo --json
		```

		`setup` initializes the corpus, helps select a GitHub authentication source,
		can install the CLI or a private MCP runtime, and can register the MCP server
		with Codex and Claude Code. Adding a repository during setup does not
		contact GitHub or begin a sync.

		For non-interactive setup, select the access mode explicitly:

		```sh
		# Both: CLI and Codex MCP
		npx --yes gitcontribute@latest setup --mode both --codex --token-source none --yes

		# CLI only
		npx --yes gitcontribute@latest setup --mode cli --token-source none --yes

		# MCP only; installs a private runtime without a global command
		npx --yes gitcontribute@latest setup --mode mcp --codex --token-source none --yes
		```

		MCP-only setup is used through the configured coding agent. Run setup again and
		choose CLI or Both if you also want the `gitcontribute` terminal command.

		<details>
		<summary><strong>Other installation options</strong></summary>

		### Install a persistent command
		Install a persistent command:

		@@ -123,9 +73,4 @@ ```sh

		To remove a global npm installation later, run
		`npm uninstall --global gitcontribute`. The `gitcontribute remove` command only
		removes selected MCP registrations. It does not delete versioned private
		runtimes, uninstall the CLI, or remove application configuration or corpus data.
		Pin GitContribute to a project:

		### Pin a project version

		```sh
		@@ -136,594 +81,224 @@ npm install --save-dev gitcontribute

		This form intentionally uses the project-pinned dependency. The npm package
		has no install lifecycle and performs no download during installation. Native
		binaries are included for macOS ARM64/x64, Linux ARM64/x64, and Windows x64.
		Build from source with Go 1.26 or newer:

		### Build from source

		Developers with Go 1.26 or newer can install or build the CLI directly:

		```sh
		go install github.com/morluto/gitcontribute/cmd/gitcontribute@latest
		go build -o gitcontribute ./cmd/gitcontribute
		```

		Native npm binaries are included for macOS ARM64/x64, Linux ARM64/x64, and
		Windows x64. You also need `git`. The `gh` CLI is optional and can provide
		authentication through `gh auth token`.

		</details>

		You need `git`. The `gh` CLI is optional and can provide authentication through
		`gh auth token`; `ripgrep` is optional and adds an extra `doctor` check.
		## Contribution workflow

		## 🧩 How it works
		### 1. Find a candidate

		Search a repository or rank its open issues by available evidence, scope,
		risks, blockers, and signs that maintainer coordination is needed.

		```text
		GitHub read APIs Local checkout
		│ │
		│ explicit sync / hydrate │ explicit index / acquire
		▼ ▼
		┌──────────────────────────────────────────┐
		│ Local SQLite corpus │
		│ observations · projections · coverage │
		│ investigations · evidence · outcomes │
		└────────────────────┬─────────────────────┘
		│ offline reads
		┌────────────┼─────────────┐
		▼ ▼ ▼
		CLI / TUI MCP agents JSON exports
		Find contribution candidates in golang/go. Exclude issues with active
		implementation work and explain why each remaining candidate is worth
		investigating.
		```

		### 1. Discover
		The ranking only covers stored observations. Results report incomplete
		coverage.

		Track explicit repositories, GitHub search results, or GH Archive event streams.
		Sync only when you ask, then search locally as often as you like.
		### 2. Research an issue

		```sh
		gitcontribute source add repos --name my-go "golang/go" "cli/cli" --json
		gitcontribute crawl my-go --since 720h --budget 500 --json
		gitcontribute radar golang/go --limit 20 --json
		gitcontribute search issues "data race" --repo golang/go --state open --json
		gitcontribute search code "context.WithTimeout" --repo golang/go
		```
		Build a research brief from the issue, repository guidance, discussion, linked
		work, indexed code, and historical contributions. Extracted maintainer text and
		checkboxes are not presented as complete acceptance criteria.

		### 2. Investigate

		Build a dossier or per-thread research brief, inspect repository health, record
		a hypothesis, and check for duplicate or competing work before committing time.

		```sh
		gitcontribute dossier build owner/repo
		gitcontribute research brief issue:owner/repo#42 --format markdown
		gitcontribute health owner/repo --json
		gitcontribute investigation start-thread issue:owner/repo#42 --json
		gitcontribute duplicates check <hypothesis-id>
		gitcontribute collisions check <hypothesis-id>
		```text
		Investigate issue owner/repo#42. Summarize the confirmed problem, likely scope,
		relevant code, maintainer guidance, and open questions.
		```

		### 3. Validate
		### 3. Check related work

		Promote promising research into an opportunity, create an isolated worktree,
		record evidence, and compare a baseline with your candidate change.
		Look for duplicate reports, linked pull requests, closing relationships, and
		semantically overlapping work before investing in an implementation.

		```sh
		gitcontribute opportunity promote --problem="Retry can hang indefinitely" \
		--scope=small --impact="reduces flakes" --effort=1h \
		--confidence=0.8 <hypothesis-id>
		gitcontribute workspace create <investigation-id>
		gitcontribute validation define --kind=test --command="go test ./..." \
		--working-dir=/path/to/workspace <investigation-id>
		gitcontribute validation run <validation-id> --kind=base --execute
		gitcontribute validation run <validation-id> --kind=candidate --execute
		gitcontribute validation repeat <validation-id> --kind=both --runs=5 \
		--concurrency=2 --execute
		gitcontribute validation compare <base-run-id> <candidate-run-id>
		```text
		Check whether owner/repo#42 has duplicate reports or competing implementation
		work. Tell me what you checked and identify any missing coverage.
		```

		Repeat validation stores bounded per-attempt results plus stable/flaky/
		inconclusive aggregates. CPU time, peak RSS, child count, process identity, and
		post-shutdown cleanup are sampled through `gopsutil`; unsupported metrics stay
		explicitly unavailable. To measure MCP readiness without parsing stdout, define
		the validation with `--protocol=mcp_stdio --readiness-timeout=30s`. The official
		MCP Go SDK then records initialize and tools/list milestones.
		Incomplete coverage is reported instead of being treated as proof that no
		competing work exists.

		### 4. Check readiness
		### 4. Validate a change

		Run a deterministic local readiness gate before turning a candidate into a
		public submission:
		Record a reproduction, test, benchmark, or other validation and compare the
		unmodified baseline with a candidate. Validation commands run only after
		explicit approval.

		```sh
		gitcontribute readiness opportunity <opportunity-id>
		gitcontribute readiness explain <opportunity-id>:evidence_freshness
		```text
		Validate my candidate change against the baseline. Run the approved checks,
		record both results, and explain whether the evidence supports the change.
		```

		Readiness reports `pass`, `warn`, `block`, or `unknown` per rule. It only reads
		stored corpus and draft metadata: it does not fetch GitHub, execute validation,
		write state, or infer that missing coverage is a hard blocker.
		Stored runs include the command, outcome, timing, and available process
		metrics.

		### 5. Prepare
		### 5. Prepare a draft

		Create a local contribution draft from the evidence and workspace diff:
		Create a local issue, pull-request, or review draft tied to the research and
		validation evidence already collected.

		```sh
		gitcontribute prepare issue <opportunity-id>
		gitcontribute prepare pr --approach="Bound retries with context" \
		--workspace <workspace-id> <opportunity-id>
		gitcontribute prepare review <opportunity-id>
		```text
		Prepare a pull-request draft for this contribution. Tie its claims to the
		recorded evidence, include the validation results, and do not post anything.
		```

		Nothing is posted. You decide what leaves your machine.
		Draft revisions retain their exact rendered bytes and provenance.

		## 🤖 Use with AI agents
		## Interfaces and storage

		The MCP server gives agents structured access to the same corpus and workflow:
		GitContribute stores repositories, threads, code snapshots, investigations,
		evidence, validation results, and contribution outcomes in SQLite. Network
		access is explicit; once information has been synced, corpus search and
		inspection work offline.

		```sh
		gitcontribute setup --mode mcp --codex --token-source none --yes
		gitcontribute setup --mode mcp --all-clients --token-source none --yes
		```

		Or start the stdio server directly:

		```sh
		gitcontribute mcp serve --transport=stdio
		```

		MCP capabilities are deliberately separate:

		The CLI advertises the focused `contribute` toolset by default. Add specialized
		surfaces only when needed: `mcp serve --toolsets=contribute,code`,
		`--toolsets=contribute,research`, `--toolsets=contribute,portfolio`,
		`--toolsets=contribute,advanced`, or `--toolsets=all`. Smaller catalogs reduce
		overlapping choices and agent context cost; toolsets change discovery only,
		not authority or side-effect annotations.
		Add `--read-only` to remove every tool whose MCP annotation permits local
		writes or execution. External read-only lookups remain available when their
		toolset is enabled.

		Tool names use the `<capability>.<action>` namespace. MCP clients qualify them
		with the configured `gitcontribute` server name, producing names such as
		`gitcontribute.corpus.search_repositories`. The server advertises one canonical
		name per operation; unnamespaced compatibility aliases are not registered.

		\| Capability \| Examples \|
		\| --- \| --- \|
		\| Offline reads \| Batch-inspect repositories, threads, and jobs; filter open or closed work; rank opportunities across repositories; prepare evidence for exact issue sets; find historical precedents; and review the authored pull-request portfolio. \|
		\| Network reads \| Batch-sync repository metadata or thread headers, hydrate selected finalists, discover authored pull requests, refresh PR status, and query derived public-repository context through DeepWiki. \|
		\| Local writes \| Start investigations, record hypotheses, promote opportunities, define validations, and prepare drafts. \|
		\| Execution \| Safely acquire and index repository code with Git only, or run a validation only when the request includes `execute: true`. \|

		A scalable discovery flow is:

		```text
		github.search_repositories -> corpus.get_repositories
		github.sync_repository_context -> jobs.get -> corpus.get_repositories
		-> research.query_deepwiki -> github.sync_threads
		-> corpus.rank_threads -> github.hydrate_threads
		-> workflow.prepare_issue_set
		GitHub read APIs Local checkout
		\| \|
		\| explicit sync / hydrate \| explicit index / acquire
		v v
		+------------------------------------------------+
		\| Local SQLite corpus \|
		\| observations · coverage · evidence · outcomes \|
		+------------------------+-----------------------+
		\| offline reads
		+---------+---------+
		v v
		CLI / TUI Coding agents
		```

		For contribution follow-up, use `github.sync_authored_pull_requests`, then
		`github.sync_pull_request_status` and `corpus.list_pull_request_portfolio`.
		Missing coverage is returned as unknown rather than as a false zero or negative.
		PR status currently includes lifecycle, mergeability, head/base revisions, and
		stored reviews. Checks, unresolved review threads, detailed merge state, merge
		queue, and portfolio overlap are deliberately reported as unavailable. See the
		[scalable MCP workflow guide](docs/mcp-scalable-workflows.md) for recovery and
		coverage details.
		The CLI and MCP server use the same application services and side-effect
		boundaries.

		Contribution workflow resources and prompts are available for agents:
		## CLI

		- `corpus.get_readiness` and `gitcontribute://readiness/<opportunity-id>` expose the
		same offline readiness report as the CLI.
		- `gitcontribute://workflow/contribution/<opportunity-id>` links the local
		opportunity, evidence, readiness report, and safe workflow prompts.
		- Prompts such as `review_contribution_readiness` instruct agents to treat
		repository and GitHub-sourced text as untrusted data and to ask before any
		network read, local write, or validation execution.
		The CLI exposes the same workflow without requiring an MCP client:

		Resources are published under `gitcontribute://` and `github-index://` URI
		schemes. See [the architecture guide](docs/architecture.md) for the complete
		application and adapter boundaries.

		## 🛡️ Safety by design

		\| Operation \| Network \| Local write \| Runs a process \| GitHub write \|
		\| --- \| :---: \| :---: \| :---: \| :---: \|
		\| Search, health, dossier, research-brief, and readiness inspection \| — \| — \| — \| — \|
		\| Investigations, evidence, lenses \| — \| ✓ \| — \| — \|
		\| Sync, crawl, hydrate \| ✓ \| ✓ \| — \| — \|
		\| DeepWiki repository context \| ✓ \| — \| — \| — \|
		\| Acquire and batch-index code \| ✓ \| ✓ \| `git` only \| — \|
		\| Acquire or create a workspace \| remote-dependent \| ✓ \| `git` only \| — \|
		\| Validation with explicit execution \| — by default \| ✓ \| ✓ \| — \|

		- No GitHub writes. GitContribute does not open issues, create pull requests,
		push commits, or mutate GitHub.
		- No hidden network access. Corpus reads never fetch data.
		- No hosted service or telemetry. Your corpus and research remain local.
		- No automatic repository execution. Crawling and indexing never execute
		repository-controlled code.
		- No implied sandbox. Explicit validation commands run on your host with the
		permissions of your user and only the environment variables you allowlist.
		- No opaque semantic ranking. Search uses SQLite FTS5 and reports signals
		such as text matches, freshness, and coverage.

		## 📚 CLI guide

		The sections below are a task-oriented reference. Run `gitcontribute --help` or
		`gitcontribute <command> --help` for every flag.

		<details>
		<summary><strong>Setup, configuration, and authentication</strong></summary>

		```sh
		gitcontribute setup # interactive
		gitcontribute setup --mode mcp --codex --token-source none --yes
		gitcontribute setup --mode mcp --all-clients --token-source none --yes
		gitcontribute setup --mode mcp --codex --token-source env \
		--token-source-key GITHUB_TOKEN --yes
		gitcontribute setup --mode mcp --codex --token-source none --dry-run --json
		gitcontribute remove --all-clients --yes # remove MCP registrations only
		gitcontribute upgrade --check
		gitcontribute upgrade --yes
		gitcontribute corpus inspect # no writes or migrations
		gitcontribute corpus backup /safe/path/corpus.db
		gitcontribute corpus migrate --yes # verified backup by default
		gitcontribute corpus restore /safe/path/corpus.db --yes
		gitcontribute corpus list # all repository scopes, bounded summaries
		gitcontribute corpus inventory OWNER/REPO
		gitcontribute corpus prune-code OWNER/REPO --keep-latest 1 # dry-run plan
		gitcontribute corpus prune-code OWNER/REPO --keep-latest 1 --yes
		gitcontribute corpus projections
		gitcontribute corpus rebuild-projection threads_fts --yes
		```

		`gitcontribute init` creates the default database and directories without
		contacting GitHub. `gitcontribute configure` updates `config.toml` atomically:

		```sh
		gitcontribute configure --database /path/to/corpus.db
		gitcontribute configure --token-source env --token-source-key GITHUB_TOKEN
		gitcontribute configure --token-source gh-cli
		gitcontribute configure --crawl-budget 1000
		```

		Authentication sources are `none`, `env`, `gh-cli`, and `keyring`. Tokens are
		resolved at runtime and are never stored in the corpus or logs. Use
		`gitcontribute status`, `metadata`, and `doctor` to inspect the local setup.
		`metadata` reports the schema of an existing corpus through a read-only check;
		it does not create the database or apply migrations when invoked by itself.
		Setup and ordinary corpus reads also never migrate an existing database or
		rebuild derived indexes. When versions differ, `corpus inspect` shows pending
		steps and `corpus migrate` performs the separately authorized upgrade. Stop or
		restart running MCP processes first; cross-process leases reject unsafe overlap
		without waiting on SQLite timeouts.
		Use `gitcontribute doctor --strict` in automation when unhealthy required
		checks should produce a non-zero exit status. Write contention is reported as
		an optional availability warning rather than database corruption.

		See [the onboarding design](docs/onboarding.md) for the full contract and
		environment-variable reference.

		</details>

		<details>
		<summary><strong>Sources, crawling, sync, and hydration</strong></summary>

		Add a source:

		```sh
		gitcontribute source add repos --name my-go "golang/go" "cli/cli" --json
		gitcontribute source add search --name go-network \
		--query "language:go stars:>100" --json
		gitcontribute source add gharchive --name golang-events \
		--events "IssuesEvent,PullRequestEvent" --json
		```

		Run it once or continuously:

		```sh
		gitcontribute crawl golang-events --since 720h --budget 500 --json
		gitcontribute tail golang-events --since 2h --budget 500 --interval 1h
		```

		Sync and selectively hydrate repository archives:

		```sh
		# Sync repository context and current threads
		gitcontribute archive sync-context owner/repo
		gitcontribute archive sync owner/repo
		gitcontribute archive sync owner/repo --since 168h --state open --max-requests 100
		gitcontribute archive sync owner/repo --numbers 42,108
		gitcontribute archive refresh owner/repo
		gitcontribute archive hydrate owner/repo#42 --with issue_comments
		gitcontribute archive hydrate owner/repo#108 \
		--with pr_reviews,pr_review_comments
		gitcontribute archive coverage owner/repo
		```

		Hydration supports `issue_comments`, `pr_details`, `pr_reviews`, and
		`pr_review_comments`; `issue_timeline` is available only when explicitly
		requested. Fetches are paginated and cancellation-aware; a complete facet
		replaces its previous snapshot atomically.
		# Find and inspect contribution candidates
		gitcontribute radar owner/repo --limit 10
		gitcontribute research brief issue:owner/repo#42

		Complete comment, review, review-comment, and explicitly requested timeline
		snapshots also enrich offline thread search. Results identify the stored facet
		in `match_source` and include a bounded `match_excerpt`; API page boundaries do
		not change matching semantics. Repository-controlled discussion remains
		untrusted evidence and is never executed.

		</details>

		<details>
		<summary><strong>Code indexing and acquisition</strong></summary>

		Index a clean local checkout at its current commit:

		```sh
		gitcontribute index owner/repo /path/to/checkout --json
		```

		Or acquire a repository into a managed mirror, index a clean temporary
		worktree, and remove that worktree afterward:

		```sh
		gitcontribute acquire owner/repo \
		--remote https://github.com/owner/repo.git --json
		```

		The indexer reads blobs directly from Git, skips binaries and non-UTF-8 content,
		enforces size limits, and rejects dirty worktrees. It reuses a stored snapshot
		when the clean commit and index format are unchanged.

		</details>

		<details>
		<summary><strong>Radar, research briefs, search, dossiers, health, seeds, and lenses</strong></summary>

		```sh
		gitcontribute radar owner/repo --limit 20
		gitcontribute search repos "cli" --limit 20 --json
		gitcontribute search issues "data race" --repo owner/repo --state open --json
		gitcontribute search prs "flaky" --repo owner/repo --label bug --json
		gitcontribute search threads "memory leak" --repo owner/repo
		# Search stored threads and indexed code
		gitcontribute search threads "connection timeout" --repo owner/repo
		gitcontribute search code "context.WithTimeout" --repo owner/repo

		gitcontribute dossier build owner/repo
		gitcontribute dossier export owner/repo --format markdown \
		--output owner-repo-dossier.md
		gitcontribute research brief owner/repo#42
		gitcontribute research brief pr:owner/repo#108 --json
		gitcontribute health owner/repo --stale-after 336h --json
		gitcontribute seeds owner/repo --json
		```

		Thread search covers stored titles and bodies plus searchable evidence from
		complete hydrated discussion and timeline snapshots. Facet-backed matches
		report where the term was found instead of returning an unexplained thread.
		For implementation work:

		`seeds` defaults to accepted (`positive`) and constraining (`negative`)
		outcome evidence so recent open issues cannot crowd historical examples out of
		the result limit. Merged PRs are positive; observed closed-unmerged PRs are
		negative. Issues remain `context` unless GitHub records `not_planned` or a
		predefined rejection/supersession label (`duplicate`, `wontfix`, `not planned`,
		`superseded`, `invalid`, or `rejected`). Select context explicitly when you want
		problem statements rather than implementation outcomes:

		```sh
		gitcontribute seeds owner/repo --polarity=context --from=issues --json
		```

		`radar` is a strict offline corpus read. It ranks a bounded population of the
		newest stored open issues and separates the numeric score from four explicit
		eligibility states: `ready_to_code`, `needs_diagnosis`, `needs_coordination`,
		and `blocked`. Its required repository argument is always positional, and one
		run can return up to the complete 500-candidate population. Every candidate
		reports positive signals, risks, blockers, confidence, linked open PRs,
		evidence coverage, and unknowns. An explicit sync ingests a fixed, bounded set
		of conventional CONTRIBUTING and AI-policy files; hydrate comments when you
		want maintainer-direction and recent-claim evidence:

		```sh
		gitcontribute archive hydrate owner/repo#42 --with issue_comments
		gitcontribute radar owner/repo --json
		```

		Radar scores carry a version (`radar.v3`) so saved JSON remains auditable when
		ranking semantics evolve. It never syncs, hydrates, executes repository code,
		or writes to GitHub.

		The cross-repository MCP Radar requires an explicit repository list and is a
		bounded, non-paginated derived ranking. Its `total` and `truncated`
		fields make omitted candidates visible; increase the limit or narrow the
		repository set rather than reusing a search cursor. Per-repository summaries
		separate considered, returned, and internally capped populations.

		Radar's `related_work` facts unify stored PR mentions and closing relationships,
		issue/comment dependencies, timeline cross-references, and duplicate clusters.
		Every relationship keeps its source kind and URL. An open PR that GitHub says
		closes the issue is an implementation blocker; other open dependencies and
		related PRs require coordination instead of being mislabeled as completed work.

		Thread sync stores issue and pull-request headers without implicitly hydrating
		each pull request. A sync has a total GitHub request budget (100 by default),
		reported in JSON and run statistics; page bounds and the request budget both
		prevent broad repository or batch inputs from producing hidden N+1 traffic.
		Generated network remediation commands include explicit request/page bounds.

		`research brief` is also a strict offline read. Its versioned
		`research-brief.v1` output has fixed sections for state, stored problem fields,
		acceptance hints, participants, timeline, explicit/duplicate references,
		linked PRs, indexed code, contribution guidance, health, coverage gaps, and
		next commands. Every section carries source references or an explicit unknown
		reason. Checkboxes and maintainer phrases remain source extracts—not fabricated
		or complete acceptance criteria. Markdown output redacts common credentials and
		quotes untrusted source text; JSON ordering is deterministic.

		Missing child facets and code stay visible instead of triggering hidden work:

		```sh
		gitcontribute archive hydrate owner/repo#42 --with issue_comments
		gitcontribute index owner/repo /path/to/clean-checkout
		gitcontribute research brief issue:owner/repo#42 --json
		```

		Use a lens to apply saved filters and weighted ranking to a bounded population:

		```sh
		gitcontribute lens add my-lens --file lens.json
		gitcontribute search issues "retry" --lens my-lens
		gitcontribute lens explain my-lens issue:owner/repo#42 --query "retry"
		```

		Repository and thread searches use weighted SQLite FTS5 relevance and accept
		`--sort=updated` in the CLI or `sort=updated` through MCP when the task is
		specifically about newest matches.
		Title/name and tags/topics count more than descriptions or bodies; hydrated
		discussion and indexed file contents count less. Search responses are compact
		excerpts, and exact reads provide full details. Most typed searches support
		opaque cursor pagination; lens-ranked searches do not. Cross-kind `search all`
		is intentionally absent because BM25 ranks from separate indexes are not
		comparable.

		</details>

		<details>
		<summary><strong>Investigations, evidence, tracking, and collections</strong></summary>

		Start an investigation and its initial hypothesis from one exact stored thread
		revision:

		```sh
		gitcontribute investigation start-thread issue:owner/repo#42 --json
		gitcontribute workspace create <investigation-id>
		gitcontribute validation define --kind=test --command="go test ./..." \
		--working-dir=/path/to/workspace <investigation-id>
		gitcontribute validation run <validation-id> --kind=base --execute
		gitcontribute validation run <validation-id> --kind=candidate --execute
		gitcontribute validation compare <base-run-id> <candidate-run-id>
		gitcontribute readiness opportunity <opportunity-id>
		gitcontribute prepare pr --approach="Bound retries with context" \
		--workspace <workspace-id> <opportunity-id>
		```

		This is a local-write operation with no network or process execution. The
		investigation saves the immutable observation ID, source update time, sequence,
		and source reference used for its title and bounded description. Repeating the
		command returns the existing open pair with `"created": false`; it never updates
		that baseline silently. The seed category is `other` because the command does
		not infer scope or defect type from untrusted issue text.
		Run `gitcontribute --help` or `gitcontribute <command> --help` for the complete
		command and flag reference. Most non-interactive commands accept `--json`;
		machine-readable output goes to stdout and progress goes to stderr.

		The manual two-command path remains available when no stored thread should be
		the baseline:
		Launch the local TUI with:

		```sh
		gitcontribute investigation start owner/repo --json
		gitcontribute hypothesis add --title="Fix retry timeout" \
		--description="Reproduce and isolate the timeout." \
		--category=bug <investigation-id>
		gitcontribute tui
		```

		Record supporting or contradicting evidence:
		## MCP

		```sh
		gitcontribute evidence add --type=manual_observation --relation=supporting \
		--description="Reproduced on the current default branch." \
		--opportunity <opportunity-id>
		```
		The default `contribute` MCP profile is focused on contribution research.
		Additional `code`, `research`, `diagnostics`, `portfolio`, `advanced`,
		`patterns`, and `concerns` profiles are opt-in so agents do not receive a
		large overlapping tool catalog by default.

		Export a digest-bound contribution evidence manifest from stored facts and an
		optional managed workspace:

		```sh
		gitcontribute export manifest <opportunity-id> \
		--workspace <workspace-id> \
		--pull-request owner/repo#42 \
		--output manifest.json
		gitcontribute setup --mode mcp --codex --token-source none --yes
		gitcontribute setup --mode mcp --all-clients --token-source none --yes
		```

		This command does not contact GitHub. Sync the exact pull request first when
		current checks or reviews matter. Missing or stale facets remain explicit
		manifest gaps. Issue and PR drafts can reference the stored result with
		`--manifest-id` without copying its claims into the rendered body.
		To start the stdio server directly:

		Evidence shown through the CLI, exports, and MCP includes a derived freshness
		status. `github_source` evidence recorded from a started thread carries the
		exact corpus source revision it used, so later issue, pull request, facet, or
		guidance updates can mark it `stale`. Missing source projections are
		`unknown`; local/manual evidence is `not_applicable`. Freshness is evaluated
		from local corpus reads only, and stale evidence is a prompt to re-check, not a
		claim that the evidence is invalid.

		Group typed references and record local decisions:

		```sh
		gitcontribute collection create interesting
		gitcontribute collection add interesting \
		repo:owner/repo issue:owner/repo#42
		gitcontribute triage record issue:owner/repo#42 viewed --reason "..."
		gitcontribute contribution record <opportunity-id> issue \
		"Draft title" --body "..."
		gitcontribute contribution outcome <contribution-id> submitted
		gitcontribute mcp serve --transport=stdio
		```

		Export and restore tracking metadata:
		Add `--read-only` to remove tools that permit local writes or execution. See
		[Scalable MCP workflows](docs/mcp-scalable-workflows.md) for the tool sequence,
		coverage model, partial-result recovery, and specialized toolsets.

		```sh
		gitcontribute tracking export --output tracking.json
		gitcontribute tracking import --file tracking.json
		```
		## Side-effect boundaries

		Tracking exports require schema version 2 for portable evidence provenance.
		Imports reject missing or different schema versions before writing. Exports
		are redacted: they exclude credentials, tokens, and absolute local paths.
		GitContribute separates corpus reads, GitHub reads, local writes, process
		execution, and external mutation.

		</details>
		\| Operation \| Network \| Local write \| Runs a process \| GitHub write \|
		\| --- \| :---: \| :---: \| :---: \| :---: \|
		\| Search and inspect stored research \| No \| No \| No \| No \|
		\| Record investigations and evidence \| No \| Yes \| No \| No \|
		\| Sync or hydrate GitHub context \| Yes \| Yes \| No \| No \|
		\| Acquire and index code \| Yes \| Yes \| `git` only \| No \|
		\| Run an explicitly approved validation \| No by default \| Yes \| Yes \| No \|

		<details>
		<summary><strong>Workspaces, jobs, runs, and TUI</strong></summary>
		- Corpus reads never fetch data.
		- Crawling and indexing never execute repository-controlled code.
		- Explicit validation commands run on your host with your user permissions.
		- GitContribute has no GitHub mutation capability.
		- There is no hosted corpus or product telemetry.

		```sh
		gitcontribute workspace show <workspace-id>
		gitcontribute diff <workspace-id>
		gitcontribute runs --limit 20
		gitcontribute jobs
		gitcontribute job show <id>
		gitcontribute job cancel <id>
		gitcontribute tui owner/repo
		```
		See [Architecture](docs/architecture.md) for the complete boundary definitions.

		`diff` returns the patch, changed files, and suggested review order. The TUI is
		local-only; add `--json` to emit a non-interactive snapshot.
		## Documentation

		MCP's `code` toolset also exposes a read-only semantic commit workflow. An
		agent first calls `workspace.inspect_commit_changes` for stable file/hunk IDs,
		then submits its proposed groups to `workspace.plan_semantic_commits`. The
		second tool verifies exact one-to-one coverage and reports ambiguous, mixed,
		generated, binary, formatting-only, and untracked changes. It does not stage or
		commit anything.
		- [Onboarding and configuration](docs/onboarding.md)
		- [Scalable MCP workflows](docs/mcp-scalable-workflows.md)
		- [Architecture and side-effect boundaries](docs/architecture.md)
		- [Operational runbooks](docs/runbooks.md)
		- [Security policy](SECURITY.md)
		- [Contributing](CONTRIBUTING.md)

		</details>
		## Storage

		<details>
		<summary><strong>JSON and output behavior</strong></summary>
		GitContribute follows platform conventions:

		Most non-interactive commands accept `--json`. Machine-readable output goes to
		stdout; progress and status messages go to stderr. List commands accept
		`--limit`, and paginated searches return an opaque `next_cursor` where supported.
		\| Platform \| Configuration \| Data \|
		\| --- \| --- \| --- \|
		\| Linux \| `$XDG_CONFIG_HOME/gitcontribute` or `~/.config/gitcontribute` \| `$XDG_DATA_HOME/gitcontribute` or `~/.local/share/gitcontribute` \|
		\| macOS \| `~/Library/Application Support/gitcontribute` \| `~/Library/Application Support/gitcontribute/Data` \|
		\| Windows \| `%APPDATA%\gitcontribute` \| `%LOCALAPPDATA%\gitcontribute\Data` \|

		`dossier export`, `export dossier`, `export evidence`, `export manifest`, and `tracking export`
		accept `--output <file>`.
		The default corpus is `gitcontribute.db` in the data directory. Run
		`gitcontribute metadata` or `gitcontribute doctor --json` to inspect the local
		setup.

		</details>
		## Platform support

		## 💾 Storage locations

		\| Platform \| Config \| Data \| Cache \| Logs \|
		\| --- \| --- \| --- \| --- \| --- \|
		\| Linux / Unix \| `$XDG_CONFIG_HOME/gitcontribute` or `~/.config/gitcontribute` \| `$XDG_DATA_HOME/gitcontribute` or `~/.local/share/gitcontribute` \| `$XDG_CACHE_HOME/gitcontribute` or `~/.cache/gitcontribute` \| `$XDG_STATE_HOME/gitcontribute` or `~/.local/state/gitcontribute/logs` \|
		\| macOS \| `~/Library/Application Support/gitcontribute` \| `~/Library/Application Support/gitcontribute/Data` \| `~/Library/Caches/gitcontribute` \| `~/Library/Logs/gitcontribute` \|
		\| Windows \| `%APPDATA%\gitcontribute` \| `%LOCALAPPDATA%\gitcontribute\Data` \| `%LOCALAPPDATA%\gitcontribute\Cache` \| `%LOCALAPPDATA%\gitcontribute\Logs` \|

		The default database is `gitcontribute.db` in the data directory. The
		configuration file is `config.toml` in the config directory.

		## 🖥️ Platform support

		Linux and macOS are the primary development and test targets. Windows builds
		are expected to work with Git for Windows and standard `%APPDATA%` and
		`%LOCALAPPDATA%` paths. For platform-specific problems, open a bug report with
		the output of `gitcontribute doctor --json`.
		are tested in CI and use the standard `%APPDATA%` and `%LOCALAPPDATA%`
		locations.

		## 🛠️ Development
		## Development

		```sh
		make test
		make verify
		go run ./cmd/gitcontribute --help
		@@ -733,14 +308,3 @@ ```
		Before changing package boundaries or side effects, read
		[docs/architecture.md](docs/architecture.md). See [CONTRIBUTING.md](CONTRIBUTING.md)
		for the fast local checks, complete PR validation, generated-output workflow,
		and focused race-test guidance.

		---

		<div align="center">

		Built for contributors who want to understand the problem before writing the patch.

		[Architecture](docs/architecture.md) · [Onboarding](docs/onboarding.md) · [Runbooks](docs/runbooks.md) · [Security](SECURITY.md) · [Contributing](CONTRIBUTING.md) · [License](LICENSE)

		</div>
		[docs/architecture.md](docs/architecture.md). See
		[CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow.

npm/bin/native/darwin-arm64/gitcontribute