doc updates

docs/mcp_stateful_runtime_plan.md

@@ -17,9 +17,10 @@
   `PersistentSessionFactory` exist, and config-built services use the runtime
   pool for generated workflow node execution while discovery/catalog refreshes
   still use short-lived SDK adapter sessions.
-- Unsafe raw public `call_tool` surfaces have been deleted. Remaining work starts
+- Unsafe raw public `call_tool` surfaces have been deleted.
-  at renaming the legacy `transparent_proxy` package to the clearer
+- The proxy/provider layer has been renamed to `wf_mcp.proxy`; public helper
-  proxy/provider-layer package.
+  names now use `create_proxy_client`, `create_proxy_server`, and
+  `validate_proxy_config`.
 
 ---
 
@@ -44,7 +45,7 @@ This is not a `wf_core` graph problem. It is an MCP runtime lifecycle problem.
 
 ## Current Execution Paths
 
-### Transparent Proxy Path
+### Proxy Path
 
 Used by directly exposed proxied MCP tools in MCP clients:
 
@@ -58,7 +59,7 @@ MCP client
 
 Relevant file:
 
-- `src/wf_mcp/transparent_proxy/mounts.py`
+- `src/wf_mcp/proxy/mounts.py`
 
 Current behavior:
 
@@ -101,9 +102,9 @@ Current behavior:
 - Do not implement Playwright-specific hacks.
 - Do not claim notification/subscription forwarding is solved.
 - Do not delete all of `src/wf_mcp/broker` in this pass. That package still owns service/source/catalog/deployment infrastructure.
-- Do not keep `src/wf_mcp/transparent_proxy` as a long-term package name. That
+- Do not reintroduce the old `transparent_proxy` package name. It described a
-  name describes a retired public mode split, not the unified server's mounted
+  retired public mode split, not the unified server's mounted upstream
-  upstream proxy/provider layer.
+  proxy/provider layer.
 - Do not expose a bigger public broker surface while fixing this.
 
 ## Target Design
@@ -202,10 +203,9 @@ Retire or hide:
 - `wf.mcp.call_tool` as planner-visible workflow helper
 - legacy `call_broker_tool` from public broker mode tests
 
-### `wf_mcp.transparent_proxy`
+### `wf_mcp.proxy`
 
-This package is also legacy-named. The code is still useful, but the name is
+This package owns the mounted upstream proxy/provider layer.
-wrong for the current architecture.
 
 Current useful contents:
 
@@ -1137,120 +1137,13 @@ Every remaining mention either:
 - says historical/debugging-only, or
 - points to the persistent runtime migration plan.
 
-## Task 10: Rename `transparent_proxy` To `proxy`
+## Task 10: Proxy Rename Completed
 
-**Files:**
+The old `transparent_proxy` package and `TransparentProxyRuntime` alias are gone.
+Use `wf_mcp.proxy.ProxyRuntime`, `create_proxy_client`,
+`create_proxy_server`, and `validate_proxy_config`.
 
-- Move: `src/wf_mcp/transparent_proxy/admin.py` -> `src/wf_mcp/proxy/admin.py`
+The proxy tests now live in `tests/wf_mcp/test_proxy.py`.
-- Move: `src/wf_mcp/transparent_proxy/mounts.py` -> `src/wf_mcp/proxy/mounts.py`
-- Move: `src/wf_mcp/transparent_proxy/runtime.py` -> `src/wf_mcp/proxy/runtime.py`
-- Move: `src/wf_mcp/transparent_proxy/safe_names.py` -> `src/wf_mcp/proxy/safe_names.py`
-- Move: `src/wf_mcp/transparent_proxy/tools.py` -> `src/wf_mcp/proxy/tools.py`
-- Modify: `src/wf_mcp/server/core.py`
-- Modify: `src/wf_mcp/cli.py`
-- Modify: `docs/wf_mcp_architecture.md`
-- Modify: tests under `tests/wf_mcp/`
-
-- [ ] **Step 1: Move the package contents**
-
-Create `src/wf_mcp/proxy/` and move the active implementation files:
-
-```text
-admin.py
-mounts.py
-runtime.py
-safe_names.py
-tools.py
-```
-
-Create `src/wf_mcp/proxy/__init__.py` exporting the runtime names currently
-used by callers.
-
-- [ ] **Step 2: Leave a temporary compatibility shim**
-
-Replace `src/wf_mcp/transparent_proxy/__init__.py` with:
-
-```python
-from wf_mcp.proxy import *  # noqa: F403
-```
-
-Delete all other files from `src/wf_mcp/transparent_proxy/`.
-
-This makes the old package visibly empty while giving downstream imports one
-migration window.
-
-- [ ] **Step 3: Update internal imports**
-
-Replace internal imports of:
-
-```text
-wf_mcp.transparent_proxy
-```
-
-with:
-
-```text
-wf_mcp.proxy
-```
-
-Check with:
-
-```bash
-rg -n "transparent_proxy" src tests
-```
-
-Expected after this step:
-
-```text
-src/wf_mcp/transparent_proxy/__init__.py
-```
-
-is the only remaining source import location.
-
-- [ ] **Step 4: Rename tests if practical**
-
-Preferred rename:
-
-```text
-tests/wf_mcp/test_transparent_proxy.py -> tests/wf_mcp/test_proxy.py
-```
-
-If the file is too noisy, keep the filename for one pass but update test names
-and imports first. The goal is no new test code using "transparent proxy" as the
-current architecture term.
-
-- [ ] **Step 5: Update docs**
-
-In `docs/wf_mcp_architecture.md`, replace the package row with:
-
-```markdown
-| `wf_mcp.proxy` | Mount configured upstream MCP servers into the unified server. Owns proxy runtime, admin tools, safe tool-name transforms, and proxy inventory helpers. |
-```
-
-Add:
-
-```markdown
-`wf_mcp.transparent_proxy` is a compatibility shim only. Do not add new code
-there.
-```
-
-- [ ] **Step 6: Run verification**
-
-Run:
-
-```bash
-uv run --with pytest pytest tests/wf_mcp -q
-uv run basedpyright --level error
-uvx ruff check src/wf_mcp tests/wf_mcp
-```
-
-Expected:
-
-```text
-passed
-0 errors
-ruff clean
-```
 
 ## Task 11: Live Playwright Verification
 
@@ -1325,21 +1218,13 @@ Append to `random shit/sonnet46-challenge-cont.md`:
 
 ## Migration Rule
 
-Until this plan is implemented:
-
-- Treat `wf.mcp.call_tool` as stateless/debugging-only.
-- Prefer direct transparent proxy tools for manual upstream testing.
-- Do not recommend broker raw calls for Playwright workflows.
-- Do not delete `WfMcpService`; it still owns too much platform infrastructure.
-- Do not add new code to `wf_mcp.transparent_proxy`; it should become a
-  compatibility shim after the rename to `wf_mcp.proxy`.
-
 After this plan is implemented:
 
 - Generated workflow node specs should use persistent MCP runtime.
-- Public raw call helpers should be hidden, removed, or clearly debug-only.
+- Public raw call helpers should stay deleted.
-- `transparent_proxy/` should contain only a shim or be removed after one
+- Prefer direct proxy tools for manual upstream testing.
-  compatibility window.
+- Do not recommend broker raw calls for Playwright workflows.
+- Do not delete `WfMcpService`; it still owns too much platform infrastructure.
 - `broker/` can be renamed/split safely in a later structural cleanup.
 
 ## Verification Commands

docs/wf_mcp_capability_sources.md

@@ -8,7 +8,7 @@ projections of those sources.
 If you need the practical "which thing do I call?" view before the domain model,
 start with [`wf_mcp_operator_manual.md`](wf_mcp_operator_manual.md).
 
-This avoids the current trap where broker admin tools, transparent proxy admin
+This avoids the current trap where broker admin tools, proxy admin
 tools, workflow node specs, and upstream MCP tools all look like unrelated
 systems.
 
@@ -257,7 +257,7 @@ Current code has several useful pieces but the boundaries are blurred.
 | `wf_mcp.broker.service.builtins` | local workflow specs | `wf.std` |
 | `wf_mcp.broker.tools` | compatibility wrapper over shared service-admin registration | `wf.admin.tools` |
 | `wf_mcp.admin_surface.tools` | shared service-backed admin tool registration | `wf.admin.tools` |
-| `wf_mcp.transparent_proxy.admin` | proxy-backed public admin tools | `wf.admin.tools` |
+| `wf_mcp.proxy.admin` | proxy-backed public admin tools | `wf.admin.tools` |
 | discovered MCP tools | upstream tools and workflow wrappers | connection source |
 | broker resources/prompts | catalog/status/planning context | likely `wf.admin` or docs sources |
 

docs/wf_mcp_plan.md

@@ -240,7 +240,7 @@ proxy plane and is the wrong abstraction for stateful MCP servers.
 
 ### Official protocol boundary
 
-The transparent proxy layer should prefer official MCP boundary types over local mirror models.
+The proxy layer should prefer official MCP boundary types over local mirror models.
 
 Use MCP SDK types at the proxy boundary:
 
@@ -313,11 +313,11 @@ Implementation should verify whether the installed MCP/FastMCP dependency expose
 - add the compatible `fastmcp` dependency explicitly
 - or implement the proxy at a lower MCP server/provider layer
 
-Do not encode the transparent proxy as a pile of static decorators. The proxy surface is connection/catalog driven and must be able to change after refresh.
+Do not encode the proxy as a pile of static decorators. The proxy surface is connection/catalog driven and must be able to change after refresh.
 
 ### Sampling and elicitation
 
-Sampling and elicitation make transparent proxying much harder than simple tool forwarding.
+Sampling and elicitation make protocol-transparent proxying much harder than simple tool forwarding.
 
 Simple request flow:
 

docs/wf_mcp_proxy_reality_and_roadmap.md

@@ -161,7 +161,7 @@ Generic notification relay does not pass it yet.
 
 ### Continue Building Now
 
-These areas do not require a perfect transparent proxy:
+These areas do not require a perfect protocol-transparent proxy:
 
 1. capability and source inventory surfaced clearly to users and LLM clients
 2. admin/control UX over configured sources

src/wf_mcp/admin_surface/handlers/runtime.py

@@ -5,7 +5,7 @@ from wf_mcp.models import BrokerConfig
 
 
 class ProxyAdminRuntime(Protocol):
-    """Runtime boundary needed by transparent proxy admin handlers."""
+    """Runtime boundary needed by proxy admin handlers."""
 
     @property
     def manager(self) -> ConfigManager | None: ...

src/wf_mcp/proxy_validation.py

@@ -11,7 +11,7 @@ _SUPPORTED_TRANSPORTS = {"stdio", "http", "streamable-http", "streamable_http",
 
 
 class ProxyConfigError(ValueError):
-    """Raised when a broker config cannot safely run as a transparent proxy."""
+    """Raised when a broker config cannot safely run as a proxy."""
 
 
 def validate_proxy_config(
@@ -33,7 +33,7 @@ def validate_proxy_config(
     )
     if errors:
         joined = "\n".join(f"- {error}" for error in errors)
-        raise ProxyConfigError(f"invalid transparent proxy config:\n{joined}")
+        raise ProxyConfigError(f"invalid proxy config:\n{joined}")
 
 
 def _validate_connection_ids(

tests/wf_mcp/test_protocol_relay.py

@@ -70,7 +70,7 @@ def test_fixture_server_emits_observable_protocol_notifications_directly() -> No
     assert "notifications/message" in methods
 
 
-def test_transparent_proxy_does_not_relay_upstream_protocol_notifications_yet() -> None:
+def test_proxy_does_not_relay_upstream_protocol_notifications_yet() -> None:
     config = BrokerConfig(
         store_root=local_temp_root() / "protocol_relay_store",
         connections=[