starmux 0.10.0 → 0.12.0

package/docs/VALIDATION_OAUTH.md

@@ -1,79 +0,0 @@
-# OAuth validation archive
-
-Historical investigation notes. For current setup, see [OAuth](OAUTH.md).
-
-## Historical acceptance checkpoints
-
-The following entries preserve the investigation chronology. Statements such as “pending” describe that checkpoint only; use the current result and checklist above for present status.
-
-### Remote acceptance deployment checkpoint (2026-10-22)
-
-A separate macOS acceptance deployment now uses Keycloak 26.8.1 with PostgreSQL 17, a public IPv6 HTTPS ingress, and an OAuth-only Core. This is an infrastructure checkpoint, **not a passed ChatGPT end-to-end acceptance**.
-
-Verified on the deployment host:
-
-- The public issuer discovery document returns HTTP 200 with normal TLS certificate verification.
-- The Core returns HTTP 401 without a bearer token; protected-resource metadata remains discoverable.
-- The official tunnel-client 0.0.16 reports OAuth discovery complete and ten OAuth targets automatically registered.
-- A real ChatGPT Tunnel connector now automatically discovers the authorization URL, tunneled token endpoint, resource and `gateway:access` scope. The pre-registered client configuration has been prepared; secret submission and login/consent are pending.
-- The existing API-key Core uses a separate port and access store.
-
-Operational findings:
-
-- Local Fake-IP DNS can break issuer discovery even when direct IPv6 HTTPS works. Correct the deployment host's resolution for the issuer without disabling TLS verification. A host mapping must be updated when the public IPv6 changes.
-- In tunnel-client 0.0.16, trusting an issuer for discovery does not automatically allow registration of its HTTP callout targets. The original loopback MCP URL plus public resource/issuer origin produced `private-host-registration-disabled`. Generic manually configured targets also lacked the OAuth categories/tags used by discovery. The verified fix was to point the tunnel at the same-origin HTTPS MCP endpoint served by the local proxy. The proxy still forwards MCP to the loopback-only Core. Ten typed OAuth targets were then auto-registered, and ChatGPT discovery succeeded. Temporary generic targets and hostname-classification overrides were removed.
-- The HTTPS proxy and valid issuer hostname resolution are now dependencies of the local Tunnel route. This does not require the ChatGPT backend to reach the host over public IPv6: MCP and registered token callouts still traverse the outbound tunnel. Browser login remains a direct HTTPS navigation to the issuer.
-- The final same-origin HTTPS configuration does not enable `--harpoon.allow-plaintext-http`. Keep auto-registered OAuth endpoints behind the narrow proxy allowlist; do not expose authorization-server administration.
-- Run the acceptance Core and authorization server independently of disposable debugging terminals. The test jobs are manually bootstrapped into the current login session, with private logs and no automatic login installation. PostgreSQL data persists; the HTTPS proxy still needs its privileged process to remain running.
-- Keep client secrets, owner credentials, database passwords, access stores, deployment-specific launchers and logs outside the repository.
-
-Still required: client-secret submission, login and consent with the exact current callback, token exchange, authenticated tool discovery and a controlled coding call, followed by revocation rejection. A callback displayed in the configuration dialog is not evidence that the authorization redirect has succeeded.
-
-Reference: [tunnel-client 0.0.16 configuration](https://github.com/openai/tunnel-client/blob/v0.0.16/docs/configuration.md), including OAuth shim rewriting and Harpoon OAuth target metadata.
-
-### Login and token exchange checkpoint
-
-The real ChatGPT authorization request used the configured client, exact registered callback, `gateway:access`, and PKCE S256. Owner login and explicit consent completed, and the browser returned to ChatGPT. Client-secret authentication reached Keycloak successfully. This proves the login/callback path, not a usable MCP authorization.
-
-The first code-to-token exchange returned HTTP 400: Keycloak reported an invalid/unknown requested resource. ChatGPT's Tunnel discovery had replaced the resource with the exact Tunnel MCP URL; the reference realm knew only the canonical Gateway resource. The deployment now registers that exact Tunnel resource as an additional bearer-only resource client. Core issuer/audience validation remains enabled and unchanged. Successful token exchange and the resulting token audience still need verification; registering a resource alone is not proof of acceptance.
-
-Keycloak's default user profile also required an email even though this deployment does not use OIDC email claims. The deployment made email optional instead of inventing a user email. The previous profile configuration was backed up privately.
-
-After the failed exchange, ChatGPT's association button remained disabled. The failed plugin installation was removed while preserving its definition and OAuth settings. Reinstallation through the browser remains pending; do not report the plugin as connected until that succeeds. No credential values or authorization codes are recorded here.
-
-### Tunnel resource aliases and successful association (2026-10-22)
-
-Keycloak 26.8.1's `ResourceIndicatorsPostProcessor` first checks that the requested resource matches an audience granted to the client. Registering a resource client alone is insufficient: add an audience mapper for that resource to the granted scope. It then narrows the token audience to the requested resource URL. The Tunnel shim supplies a different resource URL from the canonical HTTPS endpoint.
-
-Core now supports an optional `oauth.resourceAliases` array in the private access configuration: at most eight exact HTTPS resource URLs identifying this same Gateway. Owners must explicitly configure these identifiers; they are never derived from request headers or automatically trusted from discovery. Issuer, signature, client, subject, scope, lifetime and session revocation checks still apply. Protected-resource metadata continues to advertise the canonical resource. Do not add arbitrary service audiences or wildcard hosts. Removing an alias immediately rejects tokens addressed only to that alias.
-
-The deployment added an exact Tunnel audience mapper and the matching Core resource alias. Reinstallation of the existing ChatGPT plugin then succeeded without changing the callback. The page now offers “Try in chat”, and Core recorded real `verified-oauth` requests. This proves token exchange and authenticated MCP initialization/discovery; coding and revocation acceptance are tracked separately below.
-
-Regression coverage checks default rejection of an unconfigured alias, explicit acceptance, rejection of a neighboring URL, wrong issuer/subject/scope, and rejection after alias removal. Build and the OAuth integration fixture pass.
-
-Source: [Keycloak resource indicator processing](https://github.com/keycloak/keycloak/blob/26.8.1/services/src/main/java/org/keycloak/protocol/oidc/resourceindicators/ResourceIndicatorsPostProcessor.java).
-
-### Acceptance boundary and network dependency
-
-The ChatGPT settings page confirms a connected account using OAuth. The OAuth connector is now independently exposed to the agent, but its first real `health_check` attempt failed before reaching Core: the Tunnel could not complete a token-endpoint call after the host's global IPv6 connectivity was disabled. Keycloak remained healthy on loopback, while the canonical HTTPS issuer was unreachable. This is distinct from the earlier audience mismatch. Do not count this attempt as a successful coding or refresh test.
-
-For this IPv6-hosted deployment, keep the issuer reachable from both the user's login browser and the local Tunnel/Core. An outbound Tunnel does not remove the local dependency on the configured HTTPS issuer. If the host address changes, update the proxy bind address, DNS and any local host mapping together; never disable TLS verification to compensate. An IPv4-only deployment instead needs a reachable HTTPS authorization endpoint or a separately designed local HTTPS route.
-
-The full `npm test` suite passed after the resource-alias change, including all 20 Node test-runner tests plus the preceding compatibility scripts. Real connector file read/write, process execution, token refresh and remote revocation rejection remain pending.
-
-### Real ChatGPT coding and revocation acceptance (2026-10-22 UTC)
-
-After IPv6 was restored, the HTTPS issuer returned 200 and the previously configured address was present again. The earlier idle session's refresh token had expired (`Token is not active`); signing in again with the unchanged callback restored the association.
-
-A fresh ChatGPT web conversation using only the OAuth plugin completed:
-
-- `health_check`, followed by genuine Desktop Commander calls under a new `verified-oauth` connection.
-- `create_directory`, `write_file`, and `read_file` in a dedicated Downloads acceptance directory.
-- `start_process` running the written Python file. Desktop Commander's recorded output contained `GATEWAY_OAUTH_OK_20261022` and process completion. The file was independently checked locally; the local executor did not create or run it as a substitute for the connector.
-- CLI revocation of that exact connection. Subsequent real `tools/call` and `initialize` requests returned HTTP 401. Token-endpoint calls still returned 200, but did not restore access to the revoked session. ChatGPT displayed a reconnect prompt.
-
-Evidence was correlated between Core request IDs/`verified-oauth` audit entries, Desktop Commander's per-tool history and Tunnel status codes. No bearer tokens, secrets or private login data are included here. The coding sequence ran at approximately 18:33 UTC, and revocation rejection at 18:34 UTC.
-
-Observed limitations: the interactive shell printed Homebrew initialization warnings before successfully executing Python; ChatGPT's final answer/app rendering also displayed loading failures even though the tool calls completed. These UI/environment issues must not be confused with failed tool execution or treated as resolved. Long-idle refresh expiry is expected to require a new login; unattended long-duration session behavior has not been accepted as a release guarantee.
-
-Restoration checkpoint (2026-10-23 03:25 UTC): after the interrupted acceptance run, a fresh login using the unchanged callback created a new session. ChatGPT web successfully called `health_check`; Core recorded `verified-oauth` and `DC_BRIDGE_HEALTH_CHECK` with the same request ID. The earlier revoked session remains revoked. The plugin was restored by reauthentication, without undoing the revocation or relaxing access checks. The current Codex thread's dynamically loaded tool handle remained stale after plugin reinstallation, so restoration was verified through the actual ChatGPT web client and Core audit evidence rather than that handle.

package/docs/VALIDATION_TUNNEL.md

@@ -1,39 +0,0 @@
-# Local Mac via official OpenAI Tunnel: coding acceptance
-
-Date: 2026-10-21. Source commit: `be6ed18` (before this report).
-
-## Verified path
-
-Codex Mac MCP Gateway plugin → existing official OpenAI Tunnel → local loopback port 8793 → current checkout compiled TypeScript Core → Desktop Commander.
-
-The existing tunnel targeted port 8793; the saved onboarding profile targeted 18893. Starting the onboarding Core alone did not make the plugin available. The current checkout CLI was then started with `run --profile live`, selecting the existing port configuration while still running the Core from this checkout. No tunnel credentials or network configuration were changed.
-
-Runtime identity:
-
-- Core: `dist/src/dc-workspace-http.js` in this checkout.
-- Version: 0.9.0; startup digest: `83ba2a27930bdb2d`.
-- Access mode: ingress; workspace read-write; write scope home-only.
-- Developer commands: trusted-project; native access enabled.
-- Plugin health: Desktop Commander upstream healthy, 25 upstream tools discovered.
-
-## Actual plugin operations
-
-All project creation, source writes, code editing, reads and test execution below used the Mac MCP Gateway plugin, not local terminal substitutions.
-
-1. Create an isolated directory under the checkout's ignored `tmp/` directory.
-2. Write a TypeScript basket-total function and three Node tests.
-3. Execute tests with a deliberately incorrect quantity calculation: one passes, two fail with the expected assertions.
-4. Edit the calculation through `edit_block` to multiply price by quantity.
-5. Read the source back through `read_file` to confirm the edit.
-6. Execute tests again: **3 pass, 0 fail**.
-
-The test used Node's local TypeScript support. This is a coding workflow test, not a replacement for Gateway's compiled-JavaScript package tests.
-
-## Observations and limits
-
-- Default zsh startup emitted a Homebrew initialization warning including a denied `/dev/null` operation. Tests still executed. Explicit `/bin/sh` and the absolute Node executable produced a clean passing run; shell initialization compatibility remains a separate issue.
-- One `start_process` request returned a Tunnel network error. A subsequent read worked; repeating the side-effect-free tests succeeded. No exactly-once or sustained network reliability claim is made.
-- This verifies the installed plugin over an existing Tunnel in ingress mode. It does **not** verify ChatGPT web OAuth discovery, consent, refresh or revocation through that Tunnel.
-- No public HTTPS listener, IPv6 ingress, DNS or TLS certificate was configured or tested.
-- No OAuth mode switch or user permission expansion was made.
-- Temporary example files remain under ignored `tmp/tunnel-coding-20261021-1420/` for inspection. They are not shipped or committed.

package/docs/VALIDATION_WORKBUDDY.md

@@ -1,59 +0,0 @@
-# WorkBuddy API-key acceptance over HTTPS and IPv6
-
-Date: 2026-10-21. Client: WorkBuddy 5.8.3 on macOS.
-
-## Initial same-host result (2026-10-21)
-
-WorkBuddy loaded a custom Streamable HTTP MCP configuration with an Authorization Bearer header, initialized the Gateway over HTTPS, and discovered 27 tools. Its own daemon log recorded HTTP 200 and `connection-ready` with 27 tools. An authenticated GET returned 405 because this Core does not offer a standalone SSE stream; initialization and discovery still completed successfully.
-
-The test used a domain with only an AAAA record pointing at this Mac, an existing valid Let's Encrypt certificate, and Caddy bound to the Mac's global IPv6 address on port 8443. Port 443 was unavailable to the unprivileged process. Certificate validation was enabled. Only `/mcp` was forwarded to an isolated loopback Core on port 18894; `/dashboard` returned 404.
-
-The existing Tunnel Core on port 8793 and its ingress authentication mode were not changed.
-
-## Client configuration shape
-
-```json
-{
-  "mcpServers": {
-    "mac-mcp-gateway-ipv6": {
-      "type": "streamable-http",
-      "url": "https://YOUR_DOMAIN:8443/mcp",
-      "headers": { "Authorization": "Bearer YOUR_GATEWAY_KEY" }
-    }
-  }
-}
-```
-
-The real credential was written directly to the user-authorized WorkBuddy configuration file with mode 0600, never committed. Server authentication state is stored separately in a private validation directory; Gateway stores credential hashes. Reload/restart the client after externally editing its configuration, and follow any client-side approval prompt.
-
-## Authentication checks
-
-- No key: HTTP 401.
-- Incorrect key: HTTP 401.
-- WorkBuddy key: HTTP 200 and 27 tools.
-- Separate temporary key before revocation: HTTP 200.
-- Same temporary key after revocation: HTTP 401.
-- WorkBuddy key after revoking the temporary key: still HTTP 200.
-- TLS verification: passed; actual peer was the Mac's global IPv6 address.
-
-## Limits of the initial same-host test
-
-The client and server ran on the same Mac. This validates real WorkBuddy protocol/credential compatibility and HTTPS over the host's global IPv6 address, but does not prove external router/firewall reachability from another network. No WorkBuddy AI programming task, reboot persistence, token expiry, OAuth, or unattended certificate renewal was tested in this pass. The test Core and HTTPS proxy are foreground processes, not installed login services. The proxy uses the existing certificate explicitly; this setup is not a permanent certificate-renewal deployment.
-
-## Remote-host follow-up (2026-10-22)
-
-The owner subsequently tested WorkBuddy from a remote host over public IPv6 and HTTPS. For this follow-up, the owner started the CLI with the dedicated API-key access store and `--profile live` on port 8793, then changed Caddy's upstream and upstream Host header to `127.0.0.1:8793`. This differs from the initial isolated port-18894 test above. Other clients targeting port 8793 now also require a valid key.
-
-Evidence and scope:
-
-- Owner-reported remote network test; supplied screenshot shows the Gateway connected, 27/27 tools enabled and two Desktop Commander resources discovered.
-- Owner-supplied remote WorkBuddy transcript reports successful `health_check`, with trace ID `5fb9bd4b-139a-4947-a458-d577ad13069f`.
-- The transcript reports reading a 48-line Markdown document from the server Mac's Downloads directory and summarizing it, using only the Gateway connector.
-- The transcript reports writing a 32-line story to the server Mac's Downloads directory, using only the Gateway connector.
-- Independently inspected the resulting `~/Downloads/story.txt` on the server Mac: 1,844 bytes, 32 lines, modified at 2026-10-22 01:19:58 +08:00. Its title and content match the reported lighthouse story. The inspecting agent did not create or modify that file.
-
-Conclusion: the owner reports successful remote HTTPS/IPv6/API-key connection and actual file reading/writing; the written artifact is independently confirmed on the server. The inspecting agent did not capture the remote client's network traffic or independently replay its remote read call. No credentials, personal document contents, or story contents are included in this report.
-
-Tool-count clarification: the route health result reports 25 upstream tools; the screenshot shows 27 total tools including Gateway tools. The transcript's manually grouped list of 26 omits `list_sessions`; it is not evidence of a routing failure.
-
-Remaining acceptance: a remote WorkBuddy edit-and-execute coding workflow, external-client revocation behavior, restart persistence, OAuth, and sustained service operation. Remote file reading/writing does not by itself establish terminal execution or completion of the OAuth roadmap.

package/docs/assets/mcp-connection-route.svg

@@ -1,104 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="450" viewBox="0 0 1200 450" role="img" aria-labelledby="title description">
-  <title id="title">Starmux: two remote connection routes to one local MCP server</title>
-  <desc id="description">Two explicit routes are shown in parallel. Preferred Direct HTTPS: ChatGPT connects to the owner's DNS name, authenticated HTTPS reverse proxy and single Gateway Core. Alternative Secure MCP Tunnel: ChatGPT uses an OpenAI-hosted Tunnel with an outbound client on the Mac. Both routes reach the same Gateway, which forwards MCP calls to the real local Desktop Commander server. Architecture only; external authorization tests remain pending.</desc>
-  <defs>
-    <linearGradient id="background" x1="0" y1="0" x2="1" y2="1">
-      <stop stop-color="#111728"/><stop offset=".57" stop-color="#17233b"/><stop offset="1" stop-color="#0c2631"/>
-    </linearGradient>
-    <linearGradient id="direct" x1="0" y1="0" x2="1" y2="1">
-      <stop stop-color="#183b43"/><stop offset="1" stop-color="#153045"/>
-    </linearGradient>
-    <linearGradient id="tunnel" x1="0" y1="0" x2="1" y2="1">
-      <stop stop-color="#292849"/><stop offset="1" stop-color="#1c3151"/>
-    </linearGradient>
-    <linearGradient id="gateway" x1="0" y1="0" x2="1" y2="1">
-      <stop stop-color="#253b60"/><stop offset="1" stop-color="#1a2e4b"/>
-    </linearGradient>
-    <marker id="arrowGreen" markerWidth="7" markerHeight="7" refX="5.6" refY="3.5" orient="auto">
-      <path d="M1 1 L5.7 3.5 L1 6" stroke="#5cddc3" stroke-width="1.8" stroke-linejoin="round" fill="none"/>
-    </marker>
-    <marker id="arrowBlue" markerWidth="7" markerHeight="7" refX="5.6" refY="3.5" orient="auto">
-      <path d="M1 1 L5.7 3.5 L1 6" stroke="#82a9ff" stroke-width="1.8" stroke-linejoin="round" fill="none"/>
-    </marker>
-  </defs>
-
-  <rect width="1200" height="450" rx="22" fill="url(#background)"/>
-  <rect x="1" y="1" width="1198" height="448" rx="21" fill="none" stroke="#4c607b" stroke-opacity=".68"/>
-  <g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif">
-    <text x="34" y="45" fill="#f7fbff" font-size="25" font-weight="750">Two ways to reach your Mac. One Gateway you control.</text>
-    <text x="34" y="73" fill="#a5bbd1" font-size="14">Both options use the real local Desktop Commander MCP server — no reimplementation of its tools.</text>
-  </g>
-
-  <!-- One AI client, two explicit paths, one gateway -->
-  <g fill="none" stroke-linecap="round" stroke-linejoin="round">
-    <path d="M234 232 H265 V167 H293" stroke="#5cddc3" stroke-width="2.5" marker-end="url(#arrowGreen)"/>
-    <path d="M265 232 V312 H293" stroke="#82a9ff" stroke-width="2.5" marker-end="url(#arrowBlue)"/>
-    <path d="M773 167 H800 V232 H823" stroke="#5cddc3" stroke-width="2.5" marker-end="url(#arrowGreen)"/>
-    <path d="M773 312 H800 V232" stroke="#82a9ff" stroke-width="2.5"/>
-    <path d="M995 232 H1029" stroke="#55cde6" stroke-width="2.7" marker-end="url(#arrowBlue)"/>
-  </g>
-  <circle cx="265" cy="232" r="4" fill="#b3caff"/>
-  <circle cx="800" cy="232" r="4" fill="#b3caff"/>
-
-  <!-- Source AI client -->
-  <rect x="34" y="168" width="200" height="128" rx="17" fill="#29233e" stroke="#7560b0" stroke-opacity=".8"/>
-  <g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" text-anchor="middle">
-    <circle cx="134" cy="203" r="19" fill="#9f81f7" fill-opacity=".15"/>
-    <path d="M125 194 h17 a5 5 0 0 1 5 5 v9 h-10 l-6 6 v-6 h-6 a5 5 0 0 1 -5 -5 v-4 a5 5 0 0 1 5 -5" stroke="#b496ff" stroke-width="2.2" fill="none"/>
-    <text x="134" y="251" font-size="21" font-weight="730" fill="#f7f4ff">ChatGPT</text>
-    <text x="134" y="274" font-size="12" fill="#c4b7e0">Remote MCP client</text>
-  </g>
-
-  <!-- Primary route: direct HTTPS -->
-  <rect x="295" y="105" width="478" height="125" rx="15" fill="url(#direct)" stroke="#50c9b2" stroke-width="1.8"/>
-  <rect x="316" y="123" width="125" height="23" rx="11.5" fill="#245749" stroke="#49c5a5" stroke-opacity=".55"/>
-  <text x="378" y="139" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" font-weight="750" font-size="12" fill="#b6ffe6">01 · PREFERRED</text>
-  <text x="454" y="140" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" font-weight="730" font-size="18" fill="#f3fefd">Direct HTTPS</text>
-  <text x="317" y="176" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" font-size="16" fill="#d8f6ee">DNS A / AAAA  →  TLS :443  →  Auth</text>
-  <text x="317" y="201" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" font-size="13" fill="#94d9c8">Your reachable IP · your domain · your proxy</text>
-  <g transform="translate(725 125)" fill="none" stroke="#6de0c6" stroke-width="2.2">
-    <path d="M0 10 v-5 a7 7 0 0 1 14 0 v5"/><rect x="-3" y="10" width="20" height="17" rx="3"/>
-    <circle cx="7" cy="17" r="1.6" fill="#6de0c6"/><path d="M7 18 v4"/>
-  </g>
-
-  <!-- Secondary route: OpenAI Tunnel -->
-  <rect x="295" y="250" width="478" height="125" rx="15" fill="url(#tunnel)" stroke="#637fc4" stroke-width="1.7"/>
-  <rect x="316" y="268" width="137" height="23" rx="11.5" fill="#304375" stroke="#7f98e5" stroke-opacity=".65"/>
-  <text x="384.5" y="284" text-anchor="middle" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" font-weight="730" font-size="12" fill="#bed0ff">02 · ALTERNATIVE</text>
-  <text x="467" y="285" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" font-weight="730" font-size="18" fill="#f0f3ff">Secure MCP Tunnel</text>
-  <text x="317" y="320" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" font-size="16" fill="#d7e6ff">OpenAI Tunnel  ↔  outbound tunnel-client</text>
-  <text x="317" y="345" font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" font-size="13" fill="#a5b7e3">No inbound router port · OpenAI relay required</text>
-  <g transform="translate(728 276)" stroke="#97b6ff" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" fill="none">
-    <path d="M-2 6 h20 m-5 -5 l5 5 -5 5 M18 18 h-20 m5 -5 l-5 5 5 5"/>
-  </g>
-
-  <!-- Single local gateway -->
-  <rect x="824" y="168" width="171" height="128" rx="17" fill="url(#gateway)" stroke="#6589dc" stroke-width="1.8"/>
-  <g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" text-anchor="middle">
-    <circle cx="910" cy="203" r="18" fill="#73b4f8" fill-opacity=".15"/>
-    <g stroke="#a5d6ff" fill="none" stroke-width="2">
-      <circle cx="901" cy="198" r="3"/><circle cx="920" cy="198" r="3"/><circle cx="910" cy="213" r="3"/>
-      <path d="M904 201 l4 9 m9 -9 l-4 9 m-9 -12 h13"/>
-    </g>
-    <text x="910" y="251" font-size="17" font-weight="730" fill="#eff7ff">Mac MCP</text>
-    <text x="910" y="272" font-size="17" font-weight="730" fill="#eff7ff">Gateway</text>
-    <text x="910" y="286" font-size="10" fill="#a8cbed">One local Core</text>
-  </g>
-
-  <!-- Real upstream server -->
-  <rect x="1032" y="168" width="145" height="128" rx="17" fill="#13343b" stroke="#54a7b8" stroke-width="1.6"/>
-  <g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif" text-anchor="middle">
-    <rect x="1089" y="189" width="30" height="29" rx="4" fill="#5ac1cf" fill-opacity=".12" stroke="#6fdee3" stroke-width="1.8"/>
-    <path d="M1095 198 h18 M1095 205 h18 M1095 212 h10" stroke="#6fdee3" stroke-width="1.7"/>
-    <text x="1104.5" y="248" font-size="16" font-weight="720" fill="#efffff">Desktop</text>
-    <text x="1104.5" y="269" font-size="16" font-weight="720" fill="#efffff">Commander</text>
-    <text x="1104.5" y="286" font-size="10.5" fill="#aad2d6">Actual MCP tools</text>
-  </g>
-
-  <!-- Explanatory footer -->
-  <path d="M34 405 H1177" stroke="#426078" stroke-opacity=".6"/>
-  <g font-family="-apple-system,BlinkMacSystemFont,Segoe UI,Arial,sans-serif">
-    <circle cx="42" cy="423" r="4.5" fill="#5cddc3"/>
-    <text x="56" y="428" font-size="13" fill="#c2dce8">Both routes reach the same self-hosted Core. External authentication and reachability must be verified separately.</text>
-  </g>
-</svg>

package/docs/assets/mcp-gateway-simple.svg

@@ -1,62 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="405" viewBox="0 0 1200 405" role="img" aria-labelledby="title desc">
-  <title id="title">Starmux: remote AI clients connect to real Mac tools</title>
-  <desc id="desc">One clear flow: compatible remote AI clients, such as ChatGPT, connect over authenticated Direct HTTPS or OpenAI Secure MCP Tunnel to a self-hosted Starmux, which routes approved MCP tool requests to the real Desktop Commander MCP server on that Mac.</desc>
-  <defs>
-    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#111629"/><stop offset="1" stop-color="#0d2432"/></linearGradient>
-    <linearGradient id="cardPurple" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#29223f"/><stop offset="1" stop-color="#201e3c"/></linearGradient>
-    <linearGradient id="cardNavy" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#263456"/><stop offset="1" stop-color="#1b2c4a"/></linearGradient>
-    <linearGradient id="cardTeal" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#173941"/><stop offset="1" stop-color="#17313b"/></linearGradient>
-    <marker id="arrow" markerWidth="7" markerHeight="7" refX="5.5" refY="3.5" orient="auto"><path d="M1 1 L5.8 3.5 L1 6" stroke="#69b5fa" stroke-width="1.8" stroke-linecap="round" fill="none"/></marker>
-  </defs>
-  <rect x="0" y="0" width="1200" height="405" rx="22" fill="url(#bg)"/>
-  <rect x="1" y="1" width="1198" height="403" rx="21" fill="none" stroke="#405675" stroke-opacity=".7"/>
-  <g font-family="-apple-system,BlinkMacSystemFont,'Segoe UI',Arial,sans-serif">
-    <text x="36" y="47" font-weight="740" font-size="27" fill="#f7fbff">Your AI. Your Mac. Your tools.</text>
-    <text x="36" y="76" font-size="15" fill="#a6bed5">Authorized remote MCP calls reach real files, Git and Shell on the Mac you control.</text>
-    <!-- Mac region: Gateway and its real upstream remain on the machine -->
-    <rect x="588" y="117" width="580" height="214" rx="20" fill="#2b4765" fill-opacity=".13" stroke="#648aac" stroke-opacity=".48" stroke-dasharray="5 6"/>
-    <text x="606" y="140" font-weight="750" font-size="11" letter-spacing="1.4" fill="#8fbad8">ON YOUR MAC</text>
-    <!-- Client card -->
-    <rect x="36" y="157" width="224" height="157" rx="16" fill="url(#cardPurple)" stroke="#63558d"/>
-    <g transform="translate(131 175)" fill="none" stroke="#b49aff" stroke-width="2.5" stroke-linejoin="round"><rect width="35" height="25" x="-16" y="0" rx="5"/><path d="M-6 25 v7 l9 -7"/></g>
-    <text x="148" y="230" fill="#f5f2fe" font-size="19" font-weight="730" text-anchor="middle">Remote AI client</text>
-    <text x="148" y="256" fill="#c1b5de" font-size="14" text-anchor="middle">ChatGPT web</text>
-    <text x="148" y="277" fill="#a99fc8" font-size="12.5" text-anchor="middle">or compatible MCP client</text>
-    <!-- Connectivity card -->
-    <rect x="298" y="157" width="252" height="157" rx="16" fill="#1b2941" stroke="#4d7095"/>
-    <text x="424" y="186" fill="#e2efff" font-size="17" font-weight="740" text-anchor="middle">Your connection</text>
-    <rect x="316" y="200" width="216" height="43" rx="10" fill="#1b4a47" stroke="#41bda0" stroke-opacity=".8"/>
-    <circle cx="333" cy="221" r="5.5" fill="#56e1bd"/>
-    <text x="351" y="226" fill="#d9fff5" font-size="15" font-weight="720">Direct HTTPS</text>
-    <text x="521" y="225" fill="#99d9c8" font-size="10" text-anchor="end">PREFERRED</text>
-    <rect x="316" y="252" width="216" height="43" rx="10" fill="#292c53" stroke="#7584d6" stroke-opacity=".85"/>
-    <circle cx="333" cy="273" r="5.5" fill="#9a9dfc"/>
-    <text x="351" y="278" fill="#ecebff" font-size="15" font-weight="720">Secure Tunnel</text>
-    <!-- Gateway card -->
-    <rect x="606" y="157" width="259" height="157" rx="16" fill="url(#cardNavy)" stroke="#7095dd" stroke-width="1.5"/>
-    <g transform="translate(719 178)" stroke="#9acaff" stroke-width="2.5" fill="none"><circle cx="0" cy="0" r="5"/><circle cx="22" cy="0" r="5"/><circle cx="11" cy="23" r="5"/><path d="M5 3 l4 15 M17 3 l-4 15 M6 0 h10"/></g>
-    <text x="735" y="239" fill="#f5f9ff" font-weight="760" font-size="20" text-anchor="middle">Starmux</text>
-    <text x="735" y="265" fill="#bdd5ef" font-size="13.5" text-anchor="middle">Self-hosted entry point</text>
-    <text x="735" y="287" fill="#91b1d8" font-size="12.5" text-anchor="middle">Access + routing</text>
-    <!-- Upstream card -->
-    <rect x="904" y="157" width="245" height="157" rx="16" fill="url(#cardTeal)" stroke="#52a6b2" stroke-width="1.5"/>
-    <rect x="1009" y="178" width="32" height="29" rx="5" fill="none" stroke="#70dfdf" stroke-width="2.5"/>
-    <path d="M1016 187 h18 M1016 193 h18 M1016 199 h10" fill="none" stroke="#70dfdf" stroke-width="2"/>
-    <text x="1026" y="239" fill="#eafaff" font-weight="750" font-size="18" text-anchor="middle">Desktop Commander</text>
-    <text x="1026" y="265" fill="#b9dce0" font-size="13.5" text-anchor="middle">Real MCP server</text>
-    <text x="1026" y="286" fill="#94c3c9" font-size="12.5" text-anchor="middle">Files · Git · Terminal</text>
-    <!-- Flow arrows -->
-    <g stroke="#69b5fa" stroke-width="2.7" stroke-linecap="round" fill="none">
-      <path d="M264 236 H291" marker-end="url(#arrow)"/>
-      <path d="M554 236 H599" marker-end="url(#arrow)"/>
-      <path d="M869 236 H897" marker-end="url(#arrow)"/>
-    </g>
-    <!-- Caveat, small and clear -->
-    <path d="M36 348 H1166" stroke="#4c6482" stroke-opacity=".5"/>
-    <circle cx="43" cy="369" r="5" fill="#5bddbd"/>
-    <text x="56" y="374" fill="#bad5e5" font-size="13">Direct HTTPS: your domain + authentication</text>
-    <circle cx="460" cy="369" r="5" fill="#9b9cf2"/>
-    <text x="473" y="374" fill="#bad5e5" font-size="13">Tunnel: uses OpenAI forwarding</text>
-    <text x="1160" y="374" fill="#799eb9" font-size="12.5" text-anchor="end">One Gateway · One Mac</text>
-  </g>
-</svg>