first commit

docs/api-stack/api/api-tenant-provider/src/capability-id/capability-id.md

@@ -0,0 +1,77 @@
+# `"tenant.provider"` — capability id
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`@suaveplan/api-types/capabilities` exports `CapabilityId`, the open
+union derived from the `CapabilityIdRegistry` interface. As of the
+Stage-1 coherence fixes the foundation registry includes
+`"tenant.provider"` directly, so this package no longer maintains a
+widening alias — the runtime constant lives here because the
+`TenantProvider` interface lives here, and host code needs a stable
+sentinel without re-typing the literal everywhere.
+
+The module re-exports the canonical `CapabilityId` from api-types for
+source compatibility with consumers that historically imported it from
+this package.
+
+## Features
+
+- Runtime constant `TENANT_PROVIDER_CAPABILITY_ID = "tenant.provider"`.
+- Type alias `TenantProviderCapabilityId = typeof TENANT_PROVIDER_CAPABILITY_ID`.
+- Re-export of `CapabilityId` from `@suaveplan/api-types/capabilities` — source-compatible with callers that imported the widened alias previously.
+
+## Usage: Basic
+
+```ts
+import { TENANT_PROVIDER_CAPABILITY_ID } from "@suaveplan/api-tenant-provider/capability-id";
+
+if (manifest.requires?.includes(TENANT_PROVIDER_CAPABILITY_ID)) {
+    // The plugin opted into per-tenant fan-out.
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    type CapabilityId,
+    TENANT_PROVIDER_CAPABILITY_ID,
+} from "@suaveplan/api-tenant-provider/capability-id";
+
+// A capability-checker that accepts both foundation and tenant-provider ids.
+function describeCapability(id: CapabilityId): string {
+    switch (id) {
+        case TENANT_PROVIDER_CAPABILITY_ID:
+            return "tenant enumeration (per-tenant cron fan-out)";
+        case "db":
+            return "tenant-scoped database adapter";
+        default:
+            return id;
+    }
+}
+```
+
+## API Reference
+
+- `const TENANT_PROVIDER_CAPABILITY_ID = "tenant.provider" as const`.
+- `type TenantProviderCapabilityId = "tenant.provider"`.
+- `type CapabilityId` — re-export of the canonical union from `@suaveplan/api-types/capabilities`.
+
+## Implementation Notes
+
+Foundation `CapabilityId` is `keyof CapabilityIdRegistry`, and the
+foundation registry already contributes `"tenant.provider"` directly,
+so a separate widening alias here would be redundant. Any third-party
+package adding its own capability id should extend
+`CapabilityIdRegistry` from `@suaveplan/api-types/capabilities` via
+`declare module` rather than re-introducing a widened type union — the
+registry pattern is the documented extension point.
+
+The constant is `as const` so the value type narrows to the exact
+string literal `"tenant.provider"`, which is what makes
+`expectTypeOf<typeof TENANT_PROVIDER_CAPABILITY_ID>().toEqualTypeOf<TenantProviderCapabilityId>()`
+hold at the type level.