fix(docs): clarify MCP metadata upload boundary

[JSONbored]

Motivation

• The beta onboarding page incorrectly implied that all metadata stays local, while MCP commands (analyze-branch, preflight, agent packet) send branch metadata to authenticated MCP/API endpoints for analysis and packet preparation.

Description

• Replaced the misleading sentence in apps/gittensory-ui/src/routes/docs.beta-onboarding.tsx to state that source contents remain local but branch metadata (branch names, SHAs, changed file paths, commit messages, validation details, labels, body text, linked issues, and scenario notes) is uploaded to authenticated MCP/API flows.
• Added a unit assertion in test/unit/docs-beta-onboarding.test.ts that checks for the clarified privacy boundary and ensures the old phrase Metadata stays on your machine does not reappear.

Testing

• Ran the unit test file with npm run test:unit -- docs-beta-onboarding.test.ts, and the test run completed successfully with all unit tests passing (55 test files, 703 tests passed).

---

Codex Task

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	gittensory-ui	5a1f665	Commit Preview URL Branch Preview URL	Jun 02 2026, 06:39 AM

[dosubot]

Related Knowledge

2 documents with suggested updates are ready for review.

gittensory

Architecture

View Suggested Changes

@@ -6,7 +6,7 @@
 
 The system is designed around a few core principles:
 
-- **Privacy by default** — source code never leaves the developer's machine; only metadata is transmitted to the backend [[1]](https://gittensory.aethereal.dev/docs/quickstart)
+- **Privacy by default** — source code contents never leave the developer's machine; branch metadata (branch names, SHAs, changed file paths, commit messages, validation details, labels, body text, linked issues, and scenario notes) is transmitted to authenticated Gittensory MCP/API endpoints for analysis and packet preparation [[1]](https://gittensory.aethereal.dev/docs/quickstart)
 - **Serverless edge deployment** — the entire backend runs on Cloudflare Workers for global low-latency access [[2]](https://github.com/JSONbored/gittensory/blob/f63f125e2126dc58ac5a63e88f4f33d1e13b2979/wrangler.jsonc)
 - **Queue-driven architecture** — all heavy computation is decoupled into background jobs processed asynchronously [[3]](https://github.com/JSONbored/gittensory/blob/f63f125e2126dc58ac5a63e88f4f33d1e13b2979/src/index.ts)
 - **Full type safety** — TypeScript end-to-end, from the database schema through Drizzle ORM to the API layer and frontend

✅ Accepted

Gittensory Architecture

View Suggested Changes

@@ -4,7 +4,7 @@
 
 Gittensory is the deterministic base-agent layer for Gittensor OSS contribution mining [[1]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L3). It helps miners and contributors make better decisions before they open work, and helps maintainers review Gittensor-driven PRs with less noise [[2]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L5). The product is the signal: role-aware contributor context, official Gittensor stats, local MCP preflight, queue health, collision risk, reviewability, repo configuration quality, and copilot-only next-action planning [[2]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L5). Gittensory is not a Gittensor frontend, not a public leaderboard, and not an autonomous PR bot [[3]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L7). It ranks, explains, preflights, and drafts public-safe packets; it does not edit code, open PRs, post comments, close, merge, or label without an explicit user or maintainer-triggered flow [[3]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L7).
 
-The architecture follows a deterministic and auditable design philosophy [[4]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L28). Core decisions are rule-based rather than AI-generated, with Cloudflare Workers AI optional and disabled by default [[5]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L28-L30). The system maintains a strict public/private boundary: metadata-only I/O through MCP means source code is never transmitted [[6]](https://gittensory.aethereal.dev/), and private scoring context never leaks into public GitHub output. All operations are Worker-safe, favoring async snapshots over inline computation to fit within Cloudflare Workers constraints.
+The architecture follows a deterministic and auditable design philosophy [[4]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L28). Core decisions are rule-based rather than AI-generated, with Cloudflare Workers AI optional and disabled by default [[5]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/README.md#L28-L30). The system maintains a strict public/private boundary: source contents remain local while branch metadata (branch names, SHAs, changed file paths, commit messages, validation details, labels, body text, linked issues, scenario notes) is sent to authenticated Gittensory MCP/API endpoints [[6]](https://gittensory.aethereal.dev/), and private scoring context never leaks into public GitHub output. All operations are Worker-safe, favoring async snapshots over inline computation to fit within Cloudflare Workers constraints.
 
 Gittensory serves three primary audiences with distinct use cases [[6]](https://gittensory.aethereal.dev/):
 
@@ -51,7 +51,7 @@
 
 Core signal types are defined in `engine.ts`: `ParticipationLane` enumerates contributor paths (direct_pr, issue_discovery, split, inactive, unknown), `LaneAdvice` provides lane-specific guidance for contributors and maintainers, `CollisionReport` groups collision clusters by risk level (low, medium, high), and `QueueHealth` quantifies burden score, risk level, and open issues/PRs metrics [[15]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/src/signals/engine.ts#L1-L79).
 
-The engine generates nine signal types per registered repo: queue-health, config-quality, label-audit, maintainer-lane, maintainer-cut-readiness, contributor-intake-health, issue-quality, contributor-outcome-history, and repo-outcome-patterns [[16]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/src/queue/processors.ts#L394-L471). Supporting modules include `data-quality.ts` for freshness SLO reporting, `reward-risk.ts` for PR reviewability scoring, and `local-branch.ts` for pre-PR diff analysis using metadata-only input.
+The engine generates nine signal types per registered repo: queue-health, config-quality, label-audit, maintainer-lane, maintainer-cut-readiness, contributor-intake-health, issue-quality, contributor-outcome-history, and repo-outcome-patterns [[16]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/src/queue/processors.ts#L394-L471). Supporting modules include `data-quality.ts` for freshness SLO reporting, `reward-risk.ts` for PR reviewability scoring, and `local-branch.ts` for pre-PR diff analysis that sends branch metadata to the API while keeping source code contents local.
 
 ### **C. Scoring System (`src/scoring/`)**
 
@@ -99,7 +99,7 @@
 
 It also provides 13 CLI commands including login, logout, whoami, status, changelog, doctor, init-client, analyze-branch, preflight, and agent plan/status/explain/packet. Core dependencies are `@modelcontextprotocol/sdk` 1.26.0 and `zod` ^3.25.76 [[29]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/packages/gittensory-mcp/package.json#L40-L42).
 
-Local branch analysis uses metadata only — no source code is uploaded to the Worker API.
+Local branch analysis sends branch metadata (branch names, SHAs, changed file paths, commit messages, validation details, labels, body text, linked issues, scenario notes) to the Worker API; source code contents remain local.
 
 ### **I. Database Layer (`src/db/`)**
 
@@ -117,7 +117,7 @@
 
 ## Data Flow
 
-Gittensory moves data through the system via two primary input pathways: a local metadata-only path through the MCP client, and a remote path through the GitHub App and Worker API. The MCP client reads git metadata locally without uploading source code, then calls the Worker API with metadata-only payloads [[6]](https://gittensory.aethereal.dev/). The remote path begins with GitHub webhooks that trigger queue jobs, which invoke processors to backfill data from the GitHub API into D1 storage [[37]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/src/index.ts#L12-L29).
+Gittensory moves data through the system via two primary input pathways: a local path through the MCP client, and a remote path through the GitHub App and Worker API. The MCP client reads git metadata locally, then sends branch metadata (branch names, SHAs, changed file paths, commit messages, validation details, labels, body text, linked issues, scenario notes) to authenticated Worker API endpoints while keeping source code contents on the local machine [[6]](https://gittensory.aethereal.dev/). The remote path begins with GitHub webhooks that trigger queue jobs, which invoke processors to backfill data from the GitHub API into D1 storage [[37]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/src/index.ts#L12-L29).
 
 ### Scheduled Data Pipeline
 
@@ -274,7 +274,7 @@
 ### Communication Paths
 
 **MCP communication**  
-Coding agents (Claude, Cursor, Codex) or CLI users interact with the Worker API via `@jsonbored/gittensory-mcp` [[63]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/packages/gittensory-mcp/package.json#L2-L3). The MCP package exposes 21 tools and 13 CLI commands over stdio or remote transport using `@modelcontextprotocol/sdk` [[29]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/packages/gittensory-mcp/package.json#L40-L42). Each tool calls a specific Worker API endpoint at `gittensory-api.aethereal.dev` [[64]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/wrangler.jsonc#L32), transmitting metadata-only payloads. Authentication uses GitHub Device Flow, embedding session tokens in API requests.
+Coding agents (Claude, Cursor, Codex) or CLI users interact with the Worker API via `@jsonbored/gittensory-mcp` [[63]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/packages/gittensory-mcp/package.json#L2-L3). The MCP package exposes 21 tools and 13 CLI commands over stdio or remote transport using `@modelcontextprotocol/sdk` [[29]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/packages/gittensory-mcp/package.json#L40-L42). Each tool calls a specific Worker API endpoint at `gittensory-api.aethereal.dev` [[64]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/wrangler.jsonc#L32), sending branch metadata to authenticated endpoints. Authentication uses GitHub Device Flow, embedding session tokens in API requests.
 
 **GitHub App communication**  
 GitHub events (PR opened/updated/commented, issue activity) trigger webhook POST requests to the Worker [[65]](https://github.com/JSONbored/gittensory/blob/40c019c82d87568c232fbe7fabf50212e983075a/src/index.ts#L12). The handler enqueues a job for asynchronous processing. `processors.ts` routes data events to `github/backfill.ts` for state synchronization and command events to `github/commands.ts`, which parses @gittensory mentions and dispatches to appropriate services. Public-safe responses are written via `github/comments.ts`.

✅ Accepted

^{How did I do? Any feedback?}