docs: clarify local file connector setup

protocols/CONTRIBUTIONS.md

@@ -8,6 +8,16 @@ Require the authenticated principal ID from the operator before capture or propo
 
 For a resumed run, first resolve run_status and reuse its run identity, source references and unchanged pack pins. Work on one bounded learning unit, retain a compact cited draft, then prepare/evaluate/submit it and checkpoint coverage before changing source. A successful read of a new passage is progress even before a checkpoint; measure tool-level progress as well as durable state. After two identical read/status calls without a changed input or a stated recovery reason, stop that loop and checkpoint the exact blocker. On a time/tool budget boundary, checkpoint pending sections and return an honest partial report.
 
+## Capture local files through the connector
+
+GEWU uses two MCP servers for local-file ingestion. The authenticated Streamable HTTP server at `<service-url>/mcp` provides GEWU workflow tools. A separate local stdio server, `gewu-connector`, can read only files the operator explicitly allowlists at process startup and transfers their bytes to the service. The HTTP server cannot read paths on the agent's machine, and a remote service path is never a local-file path.
+
+The host must launch the connector as its own MCP server with the service URL, one or more stable `--file ID=PATH` entries, and `GEWU_TOKEN` supplied through the host's protected environment or secret store. The connector executable is registered by the GEWU package as `gewu-connector`; this is an MCP server command, not a one-shot upload script. Keep the token out of arguments, prompts and checked-in config. Connector paths are resolved on the machine running the stdio process. The connector rejects unavailable, symlinked, non-regular or empty files and enforces the service's 50 MiB file limit.
+
+At runtime, discover both configured servers. Use the local connector's `list_selected_files` to get the configured file IDs, then call its `upload_selected_file` with that exact `file_id` and the authorized `project_id`. Do not pass a filesystem path to the service HTTP tools, serialize file bytes as base64 in a model-visible call, or invent a local upload script. The connector streams and resumes bounded chunks internally; its receipt contains metadata and the staged source candidate, not the path or bytes. A successful upload still requires normal extraction review and proposal registration before the source is registered.
+
+If the connector or selected file is unavailable, stop at capture and report which MCP server/tool or configured file ID is missing, along with the host setup action required. Do not retry discovery loops or claim a source was uploaded. For text the user explicitly supplies in the conversation, `source_capture_text` is a separate path for UTF-8 plain text or Markdown up to 1 MB; it is not a binary-file substitute. Use `source_capture_url` only for public hosts the operator has allowlisted.
+
 ## Compact factual draft contract
 
 Use the advertised tool schema for call arguments. For a factual learning bundle, the proposal operations are `{operation: "register_source", source: <exact returned candidate>}` when the revision is new, `{operation: "upsert_node", node: <complete node>}` for a new stable node, and `{operation: "update_node", target_id: <existing stable node ID>, node: <complete enriched node>}` when new source evidence supports an existing node. The complete proposal envelope is described below. Do not submit incomplete objects to discover their shape.
@@ -20,7 +30,7 @@ Each claim requires `{claim_id, text, evidence_type, evidence, assessment}`; evi
 
 ## Antigravity call argument reminders
 
-Antigravity may expose MCP through a generic `call_mcp_tool` wrapper. Use the discovered server/tool names and its advertised schema; do not infer nested `scope` objects when the operation accepts flat scope fields. The wrapper's outer arguments are `ServerName`, `ToolName` and `Arguments`; `Arguments` contains only the target MCP tool's input object. For example, `get_source` is called as `{ServerName:"gewu-dome-pilot", ToolName:"get_source", Arguments:{project_id:"dome-performance", revision_id:"<exact revision id>"}}`. Do not nest the wrapper object inside `Arguments`. For common GEWU calls, the required arguments are: `gewu-dome-files/list_selected_files` `{}`; `upload_selected_file` `{file_id, project_id}`; `get_project_context` `{project_id}`; `get_source` `{project_id, revision_id}`; `source_extraction_block` `{project_id, extraction_id, block_id, offset, length}`; `list_sources` `{projects, include_shared, all_projects:false, limit, budget_tokens}`; `search` `{query, projects, include_shared, all_projects:false, limit, budget_tokens}`; `run_create` and `run_checkpoint` `{request_json}`; `proposal_prepare`, `proposal_evaluate`, and `proposal_submit` `{proposal_json}`; `ingest_review_create` `{review_json}`. The request/proposal/review values are serialized JSON strings that must follow their pinned record schemas. Never omit `project_id` from a selected-file upload or source read, or put `scope` inside search/list-source arguments. `get_source` reads registered sources only. A newly captured/uploaded source is staged; do not call `get_source` for it. Register its exact returned `source_candidate` in the same proposal that cites it, and read its evidence through the returned staged `extraction_id`.
+Antigravity may expose MCP through a generic `call_mcp_tool` wrapper. Use the discovered server/tool names and their advertised schemas; do not infer nested `scope` objects when an operation accepts flat scope fields. The wrapper's outer arguments are `ServerName`, `ToolName` and `Arguments`; `Arguments` contains only the target MCP tool's input object. For example, `get_source` is called as `{ServerName:"gewu-dome-pilot", ToolName:"get_source", Arguments:{project_id:"dome-performance", revision_id:"<exact revision id>"}}`. Do not nest the wrapper object inside `Arguments`. The local connector is a separate MCP server: `list_selected_files` takes `{}` and `upload_selected_file` takes `{file_id, project_id}`. Use the exact file ID returned by the connector; do not pass a path, file bytes or base64 through the wrapper. For common service calls, the required arguments are: `get_project_context` `{project_id}`; `get_source` `{project_id, revision_id}`; `source_extraction_block` `{project_id, extraction_id, block_id, offset, length}`; `list_sources` `{projects, include_shared, all_projects:false, limit, budget_tokens}`; `search` `{query, projects, include_shared, all_projects:false, limit, budget_tokens}`; `run_create` and `run_checkpoint` `{request_json}`; `proposal_prepare`, `proposal_evaluate`, and `proposal_submit` `{proposal_json}`; `ingest_review_create` `{review_json}`. The request/proposal/review values are serialized JSON strings that must follow their pinned record schemas. Never omit `project_id` from a selected-file upload or source read, or put `scope` inside search/list-source arguments. `get_source` reads registered sources only. A newly captured/uploaded source is staged; do not call `get_source` for it. Register its exact returned `source_candidate` in the same proposal that cites it, and read its evidence through the returned staged `extraction_id`.
 
 For Antigravity, call `diagnostics`, `get_project_context` and `run_create` once each in that order. After a successful call, keep its returned IDs/context and move to the next stage. If a generic-wrapper call gets an argument validation error, inspect only the pinned entry for that tool, correct the outer wrapper once, and stop if the corrected call fails.