docs: clarify local file upload connector flow

docs/GETTING_STARTED.md

@@ -66,7 +66,7 @@ The API exposes its authenticated Streamable HTTP MCP endpoint at `http://127.0.
 make provision-credential ARGS="--credential-id local-agent-dome --principal-id local-agent --role agent --role editor --project dome-performance"
 ```
 
-Supply the printed token to your MCP host through its protected environment or credential store as `GEWU_TOKEN`. The service URL is `http://127.0.0.1:8000/mcp`. Do not reuse the browser viewer credential. The repository's `gewu-connector` is a selected-file upload bridge, not a general MCP client; see [the local agent specification](architecture/LOCAL_AGENT.md) and [agent pack guide](../agents/gewu/README.md) for its constraints and setup. Native discovery and workflows in Claude, Codex, Antigravity, and OpenCode remain unqualified, so treat any host connection as local experimentation.
+Supply the printed token to your MCP host through its protected environment or credential store as `GEWU_TOKEN`. The service URL is `http://127.0.0.1:8000/mcp`. Do not reuse the browser viewer credential. The service MCP and the repository's `gewu-connector` are separate MCP servers: the former provides GEWU workflow tools, while the latter reads explicitly selected local files and streams them to the service. Configure the connector as a second, local stdio server when file ingestion is needed; see the [agent pack guide](../agents/gewu/README.md#configure-the-service-and-local-file-mcp-servers) for its arguments and stop conditions. Native discovery and workflows in Claude, Codex, Antigravity, and OpenCode remain unqualified, so treat any host connection as local experimentation.
 
 Give the agent the non-secret principal ID used when provisioning its credential (`local-agent` in the example), its project, selected connector file IDs and a turn budget. Diagnostics intentionally omits the principal ID. Generate a bounded handoff without reading credentials:
 

docs/architecture/LOCAL_AGENT.md

@@ -58,7 +58,7 @@ The [modularity protocol](../development/MODULARITY_PROTOCOL.md) applies to all
 | `kb-curate` | Scoped audit -> inspect candidates -> propose corrections/relations -> receipts | Traceable changes or a report, preserving disagreements and old revisions. |
 | `kb-synthesize` | Accepted inputs -> dependency inventory -> compare/compose -> evidence audit -> optional proposal | Labeled local synthesis draft, or accepted synthesis after a real receipt. |
 
-The four skills are instruction artifacts, and the service has authenticated Streamable HTTP reads and contribution tools. The `gewu-connector` stdio program bridges explicitly selected local files to that service without exposing file bytes or credentials in model-visible tool responses. It is launched with one or more stable file IDs and paths, plus a service URL; the operator supplies `GEWU_TOKEN` through the host's protected environment rather than a command-line argument. The connector requires HTTPS for non-loopback services and stores resumable upload checkpoints in a private state file. The pack manifest is bound to generated wire schemas and now has a reversible workspace installer, but host MCP configuration, native client workflows and remote deployment remain unqualified. The authenticated `source_capture_url` MCP operation is enabled only when the operator configures the exact public-host allowlist in `GEWU_FETCH_ALLOWED_HOSTS`; URL and selected-file intake support UTF-8 text, Markdown, HTML visible-text extraction and PDF. Linux PDF extraction runs inside bubblewrap; scanned PDFs return an explicit no-text result, and Windows/macOS parsing remain unqualified.
+The four skills are instruction artifacts, and the service has authenticated Streamable HTTP reads and contribution tools. Local-file ingestion uses two MCP server entries: the Streamable HTTP service endpoint provides workflow tools, while the `gewu-connector` stdio process runs on the machine with the selected files, reads only its explicit allowlist, and streams the bytes without exposing file bytes or credentials in model-visible tool responses. The service endpoint cannot read a path on the agent machine. It is launched with one or more stable file IDs and paths, plus a service URL; the operator supplies `GEWU_TOKEN` through the host's protected environment rather than a command-line argument. The connector requires HTTPS for non-loopback services and stores resumable upload checkpoints in a private state file. The pack manifest is bound to generated wire schemas and now has a reversible workspace installer, but host MCP configuration, native client workflows and remote deployment remain unqualified. The authenticated `source_capture_url` MCP operation is enabled only when the operator configures the exact public-host allowlist in `GEWU_FETCH_ALLOWED_HOSTS`; URL and selected-file intake support UTF-8 text, Markdown, HTML visible-text extraction and PDF. Linux PDF extraction runs inside bubblewrap; scanned PDFs return an explicit no-text result, and Windows/macOS parsing remain unqualified.
 
 ## Run and resume contract
 

src/gewu/transports/mcp_server.py

@@ -1102,7 +1102,11 @@ def create_mcp_server(
             expected_sha256: str,
             ctx: Context,
         ) -> str:
-            """Begin a bounded source upload scoped to an authorized project."""
+            """Begin a low-level upload for a byte-capable client such as gewu-connector.
+
+            For files on the agent's machine, configure and use the local stdio
+            connector instead of sending source bytes through conversational calls.
+            """
 
             principal = _principal(ctx, identity_provider)
             _require_project_submission(principal, project_id)
@@ -1148,7 +1152,12 @@ def create_mcp_server(
             chunk_sha256: str,
             ctx: Context,
         ) -> str:
-            """Transfer one integrity-checked upload chunk."""
+            """Transfer one integrity-checked chunk for a byte-capable upload client.
+
+            This low-level endpoint is used internally by gewu-connector. Do not
+            send whole-file base64 through conversational MCP; configure the local
+            connector for files on the agent's machine.
+            """
 
             principal = _principal(ctx, identity_provider)
             if len(content_base64) > ((CHUNK_BYTES + 2) // 3) * 4:
@@ -1168,7 +1177,10 @@ def create_mcp_server(
 
         @server.tool(name="source_upload_finalize", structured_output=False)
         def source_upload_finalize(upload_id: str, ctx: Context) -> str:
-            """Finalize and content-address a supported file or UTF-8 transcript artifact."""
+            """Finalize a low-level upload after all verified chunks are present.
+
+            Local-file connector workflows handle upload and finalization internally.
+            """
 
             principal = _principal(ctx, identity_provider)
             try: