Phase 4: Documentation + runnable decorator example

[tgrunnagle]

Description

Close out the vMCP domain/transport split by making the new API discoverable and
its extension model executable: document New/Serve and the decorator extension
model across the vMCP architecture docs and pkg/vmcp/doc.go, refresh the
pkg/vmcp/server stability table, and add a runnable decorator example embedder
that proves the supported extension mechanism. This story maps to RFC Phase 4
and delivers the documentation + example slice — no production behavior changes,
and server.New stays untouched.

Context

See RFC THV-0076: vMCP Core Interface
for full design details. Part of the vMCP interface refactor (epic #5419).

This is the final story. By the time it lands, #5430 (Phase 1) has
introduced the identity-parameterized VMCP interface and New(cfg) -> VMCP,
#5431 (Phase 2) has added Serve(ctx, VMCP, *ServerConfig) -> *Server, and
#5432 (Phase 3) has reduced server.New to the stable wrapper
Serve(ctx, New(deriveCoreConfig(cfg)), deriveServerConfig(cfg)). This story makes
that now-additive public API legible to downstream embedders (e.g.
stacklok/brood-box) and demonstrates the one supported extension mechanism:
decoration over the VMCP interface.

Per architecture.md ("PR-Sized Decomposition Guidance → Phase 4"), the work is
two PR-sized chores:

• Docs (P4.1 Update vMCP architecture docs + doc.go #5446). Update docs/arch/vmcp-library.md to document New/Serve
  and the decorator extension model and refresh its stability table (the
  embedding-pattern section currently describes only server.New; the table marks
  pkg/vmcp/server Stable as New, Start, Stop). Update
  docs/arch/10-virtual-mcp-architecture.md (overview) and pkg/vmcp/doc.go
  (package docs) to describe the domain/transport split and the decorator seam.
  docs/arch/README.md already indexes vmcp-library.md (Trigger CI on PRs #13) — only the linked
  content changes, not the index.
• Decorator example (P4.2 Runnable decorator example embedder #5447). Add a runnable example embedder implementing a
  subtract-only decorator over VMCP — a "subtract-only" decorator that filters
  its ListTools output and refuses the corresponding CallTool before delegating
  to inner. It demonstrates the two invariants from architecture.md Core
  Principle Bump golangci/golangci-lint-action from 2f856675483cb8b9378ee77ee0beb67955aca9d7 to 4696ba8babb6127d732c3c6dde519db15edab9ea #3: (a) list and call stay consistent (a tool hidden from the list is
  also denied on call), and (b) a decorator can only subtract reachability — it
  holds only inner VMCP and has no path to backends except through inner, so it
  cannot widen access (mirrors the pkg/authz/tool_filter.go filter/deny logic).

This story changes no production behavior and adds no CLI flags, so
task docs (generated docs/cli/thv_vmcp_*.md) is expected to be a no-op.

RFC Phase(s): Phase 4
Dependencies: #5432 (the server.New wrapper + config split must be merged
so the docs and example describe the final New/Serve shape)

Scope

In scope

• Document New/Serve and the decorator extension model in
  docs/arch/vmcp-library.md; refresh its pkg/vmcp/server stability table entry
  to reflect the additive New/Serve API (P4.1 Update vMCP architecture docs + doc.go #5446).
• Update docs/arch/10-virtual-mcp-architecture.md (overview) and pkg/vmcp/doc.go
  (package docs) to describe the domain/transport split and the decorator seam
  (P4.1 Update vMCP architecture docs + doc.go #5446).
• Add a runnable decorator example embedder: a subtract-only decorator over VMCP
  proving list/call consistency and that a decorator cannot widen access (P4.2 Runnable decorator example embedder #5447).

Out of scope

• Any change to VMCP, New, Serve, ServerConfig, or server.New — those
  ship in Phase 1: VMCP interface, core constructor, admission + elicitation seams #5430 / Phase 2: Serve transport helper, re-home transport, replace discovery #5431 / Phase 3: Reduce server.New to wrapper + config split #5432. This story is docs + example only.
• A new transport-layer extension mechanism beyond the existing ServerConfig
  slots and the (*Server).Handler outermost-wrapping pattern (RFC non-goal).
• Regenerating CLI docs for new flags — none are added; task docs is a guard only.
• Changes to docs/arch/README.md's index (already references vmcp-library.md).

Child Tasks

PR-sized tasks under this story (each ≤ 400 LOC, ≤ 10 files changed excluding
tests/docs/generated, one logical change):

• P4.1 Update vMCP architecture docs + doc.go #5446: P4.1 Update vMCP architecture docs + doc.go
• P4.2 Runnable decorator example embedder #5447: P4.2 Runnable decorator example embedder

Acceptance Criteria

• All child tasks complete and merged
• server.New signature and observable behavior unchanged
• New/Serve and the decorator extension model are documented in
  docs/arch/vmcp-library.md, with the stability table refreshed to reflect the
  additive New/Serve API; docs/arch/10-virtual-mcp-architecture.md and
  pkg/vmcp/doc.go describe the domain/transport split and the decorator seam
• A runnable decorator example embedder compiles and demonstrates a
  subtract-only decorator over VMCP, showing list/call consistency and that a
  decorator cannot widen access
• No production behavior change and no CLI flags added; task docs is a no-op
  (generated docs/cli/thv_vmcp_*.md unchanged)
• Existing thv vmcp serve E2E suite passes unchanged

References

• RFC THV-0076 (link above)
• Epic: vMCP interface refactor #5419