docs: agent storefront deployment — admission validity backbone + typed MCP front door

[bussyjd]

What

Lets a permissioned obol-stack agent deploy and manage storefront offers — spec,
pricing, metadata, and structured design — with plan/apply semantics, and with
validity enforced at admission for every writer. Two files:
docs/proposals/storefront-mcp-surface.md + a machine-readable
docs/proposals/storefront-mcp-tools.json.

The core idea (two parts)

Agents can already create ServiceOffers — the mother agent via
obol-agent-monetize-rbac.yaml:52, and the sell skill POSTs raw CRs at the
apiserver from inside the pod (monetize.py:472). What's missing on that path is
any validation at all: the CLI's path-conflict/price checks are package main,
unexported, never run for a non-CLI writer, and price: {} is admitted and gates at
$0 (payment.go:141, serviceoffer-crd.yaml:192-221).

1. Validity backbone — a ValidatingWebhookConfiguration. Runs the full battery
   (price-required, cross-offer path first-claimant, grant bounds, reserved paths,
   logo/contact, design tokens) synchronously at write time, for the CLI, the raw
   agent path, and the MCP alike. A webhook — unlike the CEL-only VAP already
   in-tree, which "cannot list other cluster objects" (pathconflict.go:17) — can do
   the cross-object lookups. This is what makes deployment predictable-to-be-valid;
   it needs no MCP to land (Phase 0).
2. Ergonomic front door — storefront-mcp. 9 typed tools
   (whoami/list/get/plan/apply/status/preview_landing/set_profile/retire),
   grant-scoped via a StorefrontGrant CRD + minted bearer token. Its unique value
   over "just kubectl apply --dry-run=server" is what a webhook can't give:
   rendered buyer-byte preview of landing/openapi/402, charter discovery, and
   convergence probes (applied ≠ serving).

Structured design control

A spec.design block: template enum + accent hex + bounded heroTitle/
heroTagline + icon — tokens, never agent-supplied HTML (predictability +
injection surface). Copy is HTML-escaped on render with a reject-not-mangle validator
(the existing sanitizeDisplayToken allowlist is identifier-scoped and would strip
spaces from every real title). Renders via the existing controller ConfigMap/route
machinery (catalog.go, scalar_html.go) and threads accent/icon through
RouteRule → PaymentDisplay — turning the 402 page's hand-mirrored palette
(paymentrequired.go:278) into data.

Reviewed

Drafted, then adversarially reviewed by 3 independent reviewers vs be0a237 (trust
model / code-fact accuracy / agent ergonomics). The review reshaped it: the original
MCP-broker-only framing was replaced by the webhook+MCP split above (a maintainer's
first question is "why not native primitives?" — §2 answers it head-on), RBAC honesty
(the MCP SA is necessarily cluster-scoped; tenant isolation is webhook/app logic, not
RBAC), the resume-ledger orphaning fix moved into Phase 0 (an in-cluster offer record
so MCP-created offers survive stack up), validate folded into plan --dry-run,
the design-copy sanitizer corrected, and every flagged citation fixed
(obol sell approve/gas preflight don't exist yet; auth.go 55/69; crd 192-221).

Phasing

Phase 0 = webhook + in-cluster record + grant CRD (robustness win, no MCP).
Phase 1 = the MCP server + tools. Phase 2 = design render + preview (needs parent
P1 origins). Phase 3 = registration approvals + token rotation.

https://claude.ai/code/session_01VquWN9UMaSHH7MHGcG8bw1