docs: clarify local file connector setup

README.md

@@ -1,6 +1,6 @@
 # GEWU local research-agent pack
 
-Version 0.20.20. Adds claim-bound online verification observations with URL provenance and explicit limits; web pages are not uploaded or treated as archived evidence. Adds exact answer-basis references for citation-free governing-rule answers while retaining source-citation checks. Requires an explicit operator identity handoff before source transfer and bounds resumed work by learning unit. Fixes Windows updater path handling. Adds safe pack update scripts for Windows and POSIX workspaces. Clarifies Antigravity's MCP argument envelope and required project/budget fields, enforces the one-pass diagnostics/context/run sequence, and distinguishes staged sources from registered sources. It keeps prepared proposal JSON byte-for-byte intact, records safe recovery from one missing outer brace in a copied proposal, distinguishes malformed proposals from valid policy holds, makes clear that run state is created through GEWU MCP rather than local run files, avoids headless shell/cache lookups and run-ID reuse across pack changes, groups proposals by semantic learning, guards against placeholder probes, uses server-side canonical digest preparation, stores compact run pins, makes shared scope opt-in, checks duplicates, bounds citation reads and checkpoints per-source budgets. It clarifies that the service's 50,000 `budget_tokens` cap measures serialized response codepoints rather than model context tokens and recommends separate runs for independently resumable sources.
+Version 0.20.21. Clarifies that local-file ingestion requires the GEWU service MCP and a separate local `gewu-connector` stdio server. Documents connector setup and requires the agent to stop with a setup blocker when the connector or selected file is unavailable, without streaming file bytes as base64 or inventing an upload script. Adds claim-bound online verification observations with URL provenance and explicit limits; web pages are not uploaded or treated as archived evidence. Adds exact answer-basis references for citation-free governing-rule answers while retaining source-citation checks. Requires an explicit operator identity handoff before source transfer and bounds resumed work by learning unit. Fixes Windows updater path handling. Adds safe pack update scripts for Windows and POSIX workspaces. Clarifies Antigravity's MCP argument envelope and required project/budget fields, enforces the one-pass diagnostics/context/run sequence, and distinguishes staged sources from registered sources. It keeps prepared proposal JSON byte-for-byte intact, records safe recovery from one missing outer brace in a copied proposal, distinguishes malformed proposals from valid policy holds, makes clear that run state is created through GEWU MCP rather than local run files, avoids headless shell/cache lookups and run-ID reuse across pack changes, groups proposals by semantic learning, guards against placeholder probes, uses server-side canonical digest preparation, stores compact run pins, makes shared scope opt-in, checks duplicates, bounds citation reads and checkpoints per-source budgets. It clarifies that the service's 50,000 `budget_tokens` cap measures serialized response codepoints rather than model context tokens and recommends separate runs for independently resumable sources.
 
 This pack contains the [agent profile](AGENTS.md), Claude harness pointer ([CLAUDE.md](CLAUDE.md)), shared protocols, four skills and separate pipeline procedures. An existing local host supplies the model and tools. There is no standalone agent engine here.
 
@@ -67,8 +67,20 @@ GEWU can be deployed in two configurations: a **dedicated research workspace** o
    ```
    Use `--mode dedicated` for a workspace reserved for research. The installer refuses an occupied GEWU destination and will not replace a pre-existing root instruction file.
 
-3. **Configure host MCP connections:**
-   Configure the selected host's project MCP entry for the service's authenticated Streamable HTTP endpoint, normally `<service-url>/mcp`, using a bearer credential supplied through that host's secure environment or credential mechanism. Do not put a live token in a checked-in project config. The local `gewu-connector` command is a separate, explicit-file upload bridge; it is not the general GEWU service MCP client. It returns a typed source candidate and never returns the selected path or bytes. Omit `source_revision_id` to derive a content-bound local revision with an exact retry checkpoint, or pass the original ID when resuming an existing workflow. `source_capture_text` archives and extracts explicitly supplied UTF-8 text or Markdown up to 1 MB and returns a candidate marked as pasted text; it does not register the source. To enable URL capture, the service operator may set `GEWU_FETCH_ALLOWED_HOSTS` to comma-separated exact public hostnames. The capture tool archives UTF-8 text, Markdown, HTML and PDF. HTML extraction produces visible text, not markup-byte offsets. PDF extraction currently requires Linux bubblewrap, Poppler and prlimit, runs without network access; mixed text/blank pages are partial and image-only PDFs report `PDF_NO_TEXT` as unavailable.
+3. **Configure the service and local-file MCP servers:**
+   Local-file ingestion needs two separate MCP server entries. The authenticated Streamable HTTP server at `<service-url>/mcp` provides GEWU workflow tools but cannot read files from the agent's machine. Configure it with the operator-provisioned bearer credential through the host's secure credential mechanism. The `gewu-connector` stdio server must run on the machine that can access the source file and receive the same appropriately scoped `GEWU_TOKEN` through its protected environment.
+
+   Configure the connector with its service URL and explicit file allowlist. Its launch arguments have this shape (the host's MCP config syntax varies):
+
+   ```text
+   gewu-connector --url <service-url>/mcp --file <stable-id>=<absolute-local-path>
+   ```
+
+   This command is the long-running stdio MCP server process; the host starts it and owns its lifetime. If the package is not installed in the host's Python environment, configure the host to launch the checkout through `uv run --project <path-to-GEWU> gewu-connector ...` instead. The connector must run where the selected file path exists, and its process must receive `GEWU_TOKEN` through the host's protected environment.
+
+   Add one `--file ID=PATH` for each selected source, and supply `GEWU_TOKEN` through the host's protected environment or secret store. Never put the token in the command arguments, prompt, or checked-in config. The connector provides `list_selected_files` and `upload_selected_file`; the agent must use a listed file ID and the authorized project ID. It streams and resumes bytes internally and returns metadata plus a staged source candidate, not the path or bytes. Do not send whole-file base64 through conversational MCP calls or suggest a one-shot upload script. If the host cannot start the connector, stop and report that setup blocker without claiming upload success. See the [local-file contribution protocol](protocols/CONTRIBUTIONS.md#capture-local-files-through-the-connector) for limits and failure behavior.
+
+   `source_capture_text` is only for UTF-8 plain text or Markdown explicitly supplied by the user (up to 1 MB); it archives and extracts that text but does not register the candidate. `source_capture_url` is available only for public hosts the service operator has allowlisted. It supports UTF-8 text, Markdown, HTML and PDF; HTML citations point into visible-text extraction. PDF extraction requires Linux bubblewrap, Poppler and prlimit, and scanned PDFs report `PDF_NO_TEXT`.
 
    Supply the non-secret authenticated principal ID alongside the project, selected files and turn budget. For example: `principal_id=agent-pilot; project_id=dome-performance; sources=2017bouillot.pdf; budget=one evidence-backed learning unit this turn`. Keep bearer credentials in the connector/host secret mechanism. If the principal ID is missing, the agent must stop before capture instead of searching credential/configuration files.