Platform Capability Catalog and Portal¶

Discovery tool — instantiates Platform Core / Extension Design

The discoverable front door — a browsable inventory of every supported capability and extension path, wrapped in the docs and onboarding that steer builders toward sanctioned surfaces by making them the easiest ones to find.

Platform Capability Catalog and Portal is the front door builders arrive at when they ask what can I build on, and how do I start? It is the discoverable, browsable inventory of every supported capability and extension path — each entry carrying its contract, status, owner, versions, examples, and support channel — wrapped in the docs and onboarding that make a newcomer productive. Its defining job is steering by discoverability: by making the supported path the easiest one to find and the internal hook nearly impossible to find, it pulls builders toward sanctioned surfaces without anyone having to police them.

Example¶

A cloud company's platform team watches forty internal service teams reinvent queues, auth, and feature-flagging, because nobody can find the blessed ones. They stand up a portal. Each supported capability becomes a catalog entry — "Managed Queue v3, supported, owned by Team Messaging, here is the contract, a copy-paste quickstart, and its deprecation status." Experimental capabilities are labeled experimental; retired ones are struck through with a pointer to their replacement.

A new team building a service now discovers the paved road^[1] in minutes rather than grepping the monorepo, and the shadow queue implementations dry up — not because anyone banned them, but because the supported queue is simply easier to find, adopt, and get help with. The catalog did the steering that a policy memo never could.

How it works¶

List every supported capability and extension path as a catalog entry with its contract, owner, version, status, examples, and access route.
Make status and lineage first-class — experimental, supported, deprecated, retired — so a builder sees at a glance what is safe to build on and what is on its way out.
Provide the onboarding layer — quickstarts, worked examples, support routes — that turns "there is an API" into "I shipped against it today."
Curate and rank transparently, so what surfaces first reflects fitness and support rather than politics.

Tuning parameters¶

Curation strictness — how much is listed. A tight catalog of blessed capabilities steers hard but can hide useful niche surfaces; an everything-listed catalog is complete but drowns the paved road in noise.
Status granularity — how many lifecycle states an entry can carry. Finer states set expectations precisely but demand upkeep on every listing.
Ranking basis — what surfaces first: usage, support tier, freshness, or editorial pick. Each nudges builders differently, and each can be gamed.
Onboarding depth — from a bare API reference to a guided quickstart. Deeper onboarding lifts adoption but is expensive to keep current against a moving platform.

When it helps, and when it misleads¶

Its strength is that it cuts shadow duplication and correct-use cost at once, turning a platform's sprawl into something a newcomer can actually navigate. It is the mechanism that makes "reuse what exists" the path of least resistance.

Its failure mode is rot: listings outlive their maintainers, statuses go stale, examples stop compiling — and a stale catalog is worse than none, because it steers builders confidently onto abandoned surfaces. The classic misuse is a portal optimized to look comprehensive — a wall of entries, an ever-rising listing count — rather than to steer well, ranking by raw popularity so the incumbent capability entrenches regardless of fitness. The discipline that guards against this is that every listing has an accountable owner and a real, current status, and that ranking and curation are transparent and periodically pruned.

How it implements the components¶

The Portal realizes the discovery-and-onboarding components — the ones that make a platform's capabilities findable and usable:

platform_capability_and_service_catalog — is the catalog: supported capabilities, contracts, owners, versions, access, status, and examples, all made discoverable in one place.
platform_builder_experience_layer — the docs, quickstarts, worked examples, and support routes that turn a listed capability into something a builder can adopt quickly and correctly.

It surfaces capabilities but does not author the contracts it lists — that is Platform API and SDK — nor hold the authoritative record of extension identity and provenance (Platform Plugin and Extension Registry), nor govern which capabilities are admitted (Platform Ecosystem Change Council).

Instantiates: Platform Core / Extension Design — the Portal is how the platform's capabilities become discoverable and adoptable.
Consumes: Platform Plugin and Extension Registry supplies the identity and status data the Portal displays; Platform API and SDK supplies the contracts it documents.
Sibling mechanisms: Platform API and SDK · Platform Plugin and Extension Registry · Platform Architecture Blueprint · Platform Conformance Test Suite · Platform Ecosystem Change Council · Platform Extension Health and Dependency Dashboard · Platform Extension Manifest · Platform Reference Implementation · Platform Sandbox and Capability Permissions · Platform Semantic Versioning and Release Train

Notes¶

The Portal is a view, not the source of truth: the identity, provenance, and lifecycle state it displays live in the Platform Plugin and Extension Registry. When the two diverge — a status shown "supported" that the registry has already retired — trust the registry and treat the drift as a portal bug, not a governance decision.

References¶

[1] The paved road (or "golden path") — the supported, well-documented way to do a common task, made so much easier than the alternatives that builders choose it freely rather than by mandate. A capability portal is how a platform publishes and maintains its paved roads. ↩