@cosmicdrift/kumiko-bundled-features 0.224.2 → 0.226.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.224.2",
+  "version": "0.226.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -36,6 +36,8 @@
     "./tier-engine": "./src/tier-engine/index.ts",
     "./tier-engine/web": "./src/tier-engine/web/index.ts",
     "./cap-counter": "./src/cap-counter/index.ts",
+    "./cap-overview": "./src/cap-overview/index.ts",
+    "./cap-overview/web": "./src/cap-overview/web/index.ts",
     "./custom-fields": "./src/custom-fields/index.ts",
     "./custom-fields/web": "./src/custom-fields/web/index.ts",
     "./tags": "./src/tags/index.ts",
@@ -128,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.224.2",
-    "@cosmicdrift/kumiko-framework": "0.224.2",
-    "@cosmicdrift/kumiko-headless": "0.224.2",
-    "@cosmicdrift/kumiko-renderer": "0.224.2",
-    "@cosmicdrift/kumiko-renderer-web": "0.224.2",
-    "@cosmicdrift/kumiko-types": "0.224.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.226.0",
+    "@cosmicdrift/kumiko-framework": "0.226.0",
+    "@cosmicdrift/kumiko-headless": "0.226.0",
+    "@cosmicdrift/kumiko-renderer": "0.226.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.226.0",
+    "@cosmicdrift/kumiko-types": "0.226.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -162,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.224.2",
-    "@cosmicdrift/kumiko-locale-es": "0.224.2"
+    "@cosmicdrift/kumiko-locale-de": "0.226.0",
+    "@cosmicdrift/kumiko-locale-es": "0.226.0"
   }
 }

package/src/admin-shell/__tests__/admin-shell.boot.test.ts

@@ -1,9 +1,14 @@
 import { describe, expect, test } from "bun:test";
 import { access, createRegistry, validateBoot } from "@cosmicdrift/kumiko-framework/engine";
 import { createAuditFeature } from "../../audit/feature";
+import { billingFoundationFeature } from "../../billing-foundation";
+import { createCapOverviewFeature } from "../../cap-overview/feature";
+import type { CapSpec } from "../../cap-overview/types";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
 import { createConfigFeature } from "../../config/feature";
 import { createJobsFeature } from "../../jobs/feature";
 import { createTenantFeature } from "../../tenant/feature";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
 import { tierEngineFeature } from "../../tier-engine/feature";
 import { createUserFeature } from "../../user/feature";
 import {
@@ -23,6 +28,13 @@ const features = [
   createAdminShellFeature(),
 ];
 
+const testCap: CapSpec = {
+  id: "widgets",
+  label: "test.cap.widgets",
+  limit: () => 5,
+  usage: async () => 0,
+};
+
 describe("admin-shell boot + workspace composition", () => {
   test("validateBoot with user, tenant, audit, jobs, tier-engine", () => {
     expect(() => validateBoot(features)).not.toThrow();
@@ -144,4 +156,58 @@ describe("admin-shell boot + workspace composition", () => {
     expect(shell.translations?.["admin-shell:nav.tenantOverview"]?.["en"]).toBe("Overview");
     expect(shell.translations?.["screen:tenant-overview.title"]?.["en"]).toBe("Overview");
   });
+
+  test("includeCapOverview:true adds cap-overview nav to both workspaces", () => {
+    const withCapOverview = createAdminShellFeature({ includeCapOverview: true });
+    const registry = createRegistry([
+      createConfigFeature(),
+      createUserFeature(),
+      createTenantFeature(),
+      createAuditFeature(),
+      createJobsFeature(),
+      tierEngineFeature,
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      billingFoundationFeature,
+      createCapOverviewFeature({ caps: [testCap] }),
+      withCapOverview,
+    ]);
+    expect(
+      registry.getWorkspaceNavs(`${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_TENANT_WORKSPACE_ID}`),
+    ).toEqual([
+      "admin-shell:nav:tenant-overview",
+      "tenant:nav:members",
+      "audit:nav:audit-log",
+      "admin-shell:nav:my-caps",
+    ]);
+    expect(
+      registry.getWorkspaceNavs(
+        `${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_PLATFORM_WORKSPACE_ID}`,
+      ),
+    ).toEqual([
+      "admin-shell:nav:platform-overview",
+      "admin-shell:nav:tenants",
+      "admin-shell:nav:tenant-caps",
+      "jobs:nav:job-runs",
+      "admin-shell:nav:tier-admin",
+    ]);
+    expect(registry.getNav("admin-shell:nav:my-caps")?.screen).toBe("cap-overview:screen:my-caps");
+    expect(registry.getNav("admin-shell:nav:tenant-caps")?.screen).toBe(
+      "cap-overview:screen:tenant-cap-list",
+    );
+  });
+
+  test("includeCapOverview default (false) adds no cap-overview nav entries", () => {
+    const registry = createRegistry(features);
+    expect(
+      registry.getWorkspaceNavs(`${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_TENANT_WORKSPACE_ID}`),
+    ).not.toContain("admin-shell:nav:my-caps");
+    expect(
+      registry.getWorkspaceNavs(
+        `${ADMIN_SHELL_FEATURE}:workspace:${DEFAULT_PLATFORM_WORKSPACE_ID}`,
+      ),
+    ).not.toContain("admin-shell:nav:tenant-caps");
+    expect(registry.getNav("admin-shell:nav:my-caps")).toBeUndefined();
+    expect(registry.getNav("admin-shell:nav:tenant-caps")).toBeUndefined();
+  });
 });

package/src/admin-shell/feature.ts

@@ -24,6 +24,10 @@ export type CreateAdminShellOptions = {
   };
   /** Platform nav → tier-engine:screen:tier-admin. Requires tier-engine mounted. Default true. */
   readonly includeTierAdmin?: boolean;
+  /** Tenant nav → cap-overview:screen:my-caps, platform nav → cap-overview:screen:tenant-cap-list.
+   *  Requires cap-overview mounted. Default false — apps that don't mount cap-overview
+   *  must not get a nav entry pointing at a screen that doesn't exist. */
+  readonly includeCapOverview?: boolean;
   /** When false, only overview screens + nav are registered — app owns r.workspace(). Default true. */
   readonly registerWorkspaces?: boolean;
 };
@@ -32,11 +36,12 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
   const tenantWsId = options.workspaceIds?.tenant ?? DEFAULT_TENANT_WORKSPACE_ID;
   const platformWsId = options.workspaceIds?.platform ?? DEFAULT_PLATFORM_WORKSPACE_ID;
   const includeTierAdmin = options.includeTierAdmin ?? true;
+  const includeCapOverview = options.includeCapOverview ?? false;
   const registerWorkspaces = options.registerWorkspaces ?? true;
 
   return defineFeature(ADMIN_SHELL_FEATURE, (r) => {
     r.describe(
-      "Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`). Mount after user, tenant, audit, and jobs; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.",
+      "Registers tenant-admin and platform-admin workspaces with provider nav into owner-feature screens (`tenant:screen:members`, `audit:screen:audit-log`, `tenant:screen:tenant-list`, `jobs:screen:job-runs`, optional `tier-engine:screen:tier-admin`, optional `cap-overview:screen:my-caps`/`cap-overview:screen:tenant-cap-list`). Mount after user, tenant, audit, and jobs; pass `workspaceIds` to match app URL conventions (e.g. Studio `d`/`s`, PublicStatus `admin`/`sysadmin`). Client: `adminShellClient()`, `tenantClient()`, `auditClient()`, `jobsClient()`, optional `tierEngineClient()`.",
     );
     r.uiHints({
       displayLabel: "Admin Shell",
@@ -48,17 +53,20 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
     r.requires("audit");
     r.requires("jobs");
     if (includeTierAdmin) r.requires("tier-engine");
+    if (includeCapOverview) r.requires("cap-overview");
 
     r.translations({ keys: ADMIN_SHELL_I18N });
 
-    const tenantNav = [
+    const tenantNav: string[] = [
       "admin-shell:nav:tenant-overview",
       "tenant:nav:members",
       "audit:nav:audit-log",
-    ] as const;
+      ...(includeCapOverview ? (["admin-shell:nav:my-caps"] as const) : []),
+    ];
     const platformNav: string[] = [
       "admin-shell:nav:platform-overview",
       "admin-shell:nav:tenants",
+      ...(includeCapOverview ? (["admin-shell:nav:tenant-caps"] as const) : []),
       "jobs:nav:job-runs",
       ...(includeTierAdmin ? (["admin-shell:nav:tier-admin"] as const) : []),
     ];
@@ -113,6 +121,25 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
       });
     }
 
+    if (includeCapOverview) {
+      r.nav({
+        id: "my-caps",
+        label: "admin-shell:nav.myCaps",
+        icon: "gauge",
+        screen: "cap-overview:screen:my-caps",
+        access: { roles: access.admin },
+        order: 20,
+      });
+      r.nav({
+        id: "tenant-caps",
+        label: "admin-shell:nav.tenantCaps",
+        icon: "gauge",
+        screen: "cap-overview:screen:tenant-cap-list",
+        access: { roles: access.systemAdmin },
+        order: 20,
+      });
+    }
+
     if (registerWorkspaces) {
       r.workspace({
         id: tenantWsId,

package/src/admin-shell/i18n.ts

@@ -13,6 +13,8 @@ export const ADMIN_SHELL_I18N: Readonly<Record<string, LocalizedString>> = {
   "admin-shell:nav.platformOverview": { en: "Overview" },
   "admin-shell:nav.tenants": { en: "Tenants" },
   "admin-shell:nav.tierAdmin": { en: "Assign tier" },
+  "admin-shell:nav.myCaps": { en: "Plans & Caps" },
+  "admin-shell:nav.tenantCaps": { en: "Plans & Caps" },
   "admin-shell:overview.tenantTitle": { en: "Administration" },
   "admin-shell:overview.platformTitle": { en: "Platform" },
   "admin-shell:overview.loading": { en: "Loading…" },

package/src/cap-overview/__tests__/cap-overview-security.integration.test.ts

@@ -0,0 +1,207 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import { billingFoundationFeature } from "../../billing-foundation";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { seedTenant } from "../../tenant/seeding";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import { TierEngineHandlers, tierAssignmentEntity, tierEngineFeature } from "../../tier-engine";
+import { CapOverviewQueries } from "../constants";
+import { createCapOverviewFeature } from "../feature";
+import type { CapSpec } from "../types";
+
+// Two tenants with distinct usage numbers — proves reads are scoped by
+// tenantId, not "whichever row comes back first" or a summed total.
+const TENANT_A = testTenantId(9001);
+const TENANT_B = testTenantId(9002);
+// Distinct tier from A/B — lets sort=tier be told apart from the sort=name default.
+const TENANT_C = testTenantId(9003);
+const USAGE_BY_TENANT: Readonly<Record<string, number>> = {
+  [TENANT_A]: 3,
+  [TENANT_B]: 7,
+};
+
+const testCap: CapSpec = {
+  id: "widgets",
+  label: "test.cap.widgets",
+  limit: () => 10,
+  usage: async (_db, tenantId) => USAGE_BY_TENANT[tenantId] ?? 0,
+};
+
+// Never wired up for any tenant — proves the "not measured" state renders
+// as null, not 0, all the way through the real query handler.
+const unmeasuredCap: CapSpec = {
+  id: "unmeasured",
+  label: "test.cap.unmeasured",
+  limit: () => 10,
+  usage: async () => null,
+};
+
+let stack: TestStack;
+let db: DbConnection;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      billingFoundationFeature,
+      tierEngineFeature,
+      createCapOverviewFeature({ caps: [testCap, unmeasuredCap] }),
+    ],
+  });
+  db = stack.db;
+  await createEventsTable(db);
+  await unsafeCreateEntityTable(db, tenantEntity);
+  await unsafeCreateEntityTable(db, tierAssignmentEntity);
+  await unsafeCreateEntityTable(db, tenantComplianceProfileEntity);
+  configurePiiSubjectKms(new InMemoryKmsAdapter());
+
+  await seedTenant(db, { id: TENANT_A, key: `cap-overview-a-${TENANT_A}`, name: "Tenant A" });
+  await seedTenant(db, { id: TENANT_B, key: `cap-overview-b-${TENANT_B}`, name: "Tenant B" });
+  await seedTenant(db, { id: TENANT_C, key: `cap-overview-c-${TENANT_C}`, name: "Tenant C" });
+
+  const ownerA = createTestUser({
+    id: 90011,
+    tenantId: TENANT_A,
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+  const ownerB = createTestUser({
+    id: 90021,
+    tenantId: TENANT_B,
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+  const ownerC = createTestUser({
+    id: 90031,
+    tenantId: TENANT_C,
+    roles: ["TenantAdmin", "SystemAdmin"],
+  });
+  await stack.http.writeOk(TierEngineHandlers.create, { tier: "pro" }, ownerA);
+  await stack.http.writeOk(TierEngineHandlers.create, { tier: "pro" }, ownerB);
+  await stack.http.writeOk(TierEngineHandlers.create, { tier: "starter" }, ownerC);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("cap-overview tenant isolation", () => {
+  test("TenantAdmin(A) cannot read tenant B's usage via override", async () => {
+    const tenantAdminA = createTestUser({ id: 90012, tenantId: TENANT_A, roles: ["TenantAdmin"] });
+    const res = await stack.http.query(
+      CapOverviewQueries.capsUsage,
+      { tenantId: TENANT_B },
+      tenantAdminA,
+    );
+    expect(res.status).toBe(403);
+  });
+
+  test("TenantAdmin(A) cannot list all tenants", async () => {
+    const tenantAdminA = createTestUser({ id: 90013, tenantId: TENANT_A, roles: ["TenantAdmin"] });
+    const res = await stack.http.query(CapOverviewQueries.tenantCapsList, {}, tenantAdminA);
+    expect(res.status).toBe(403);
+  });
+
+  test("TenantAdmin(A) without override sees exactly A's own numbers, not a sum", async () => {
+    const tenantAdminA = createTestUser({ id: 90014, tenantId: TENANT_A, roles: ["TenantAdmin"] });
+    const result = await stack.http.queryOk<{
+      rows: readonly { id: string; used: number | null; percent: number | null }[];
+    }>(CapOverviewQueries.capsUsage, {}, tenantAdminA);
+    expect(result.rows).toHaveLength(2);
+    const widgetsRow = result.rows.find((row) => row.id === testCap.id);
+    expect(widgetsRow?.used).toBe(USAGE_BY_TENANT[TENANT_A]);
+
+    const unmeasuredRow = result.rows.find((row) => row.id === unmeasuredCap.id);
+    expect(unmeasuredRow?.used).toBeNull();
+    expect(unmeasuredRow?.percent).toBeNull();
+  });
+
+  test("SystemAdmin can read tenant B's usage via override", async () => {
+    const sysAdmin = createTestUser({ id: 90015, tenantId: TENANT_A, roles: ["SystemAdmin"] });
+    const result = await stack.http.queryOk<{
+      rows: readonly { id: string; used: number | null }[];
+    }>(CapOverviewQueries.capsUsage, { tenantId: TENANT_B }, sysAdmin);
+    const widgetsRow = result.rows.find((row) => row.id === testCap.id);
+    expect(widgetsRow?.used).toBe(USAGE_BY_TENANT[TENANT_B]);
+  });
+
+  test("SystemAdmin sees both tenants on the list, each with its own numbers", async () => {
+    const sysAdmin = createTestUser({ id: 90016, tenantId: TENANT_A, roles: ["SystemAdmin"] });
+    const result = await stack.http.queryOk<{
+      rows: readonly Record<string, unknown>[];
+    }>(CapOverviewQueries.tenantCapsList, {}, sysAdmin);
+
+    const byTenant = new Map(result.rows.map((row) => [row["tenantId"] as string, row]));
+    const capField = `cap_${testCap.id}`;
+    expect((byTenant.get(TENANT_A)?.[capField] as { used: number } | undefined)?.used).toBe(
+      USAGE_BY_TENANT[TENANT_A],
+    );
+    expect((byTenant.get(TENANT_B)?.[capField] as { used: number } | undefined)?.used).toBe(
+      USAGE_BY_TENANT[TENANT_B],
+    );
+  });
+});
+
+describe("cap-overview tier filter operators", () => {
+  test("op:ne excludes tenants matching the value, not just those matching it", async () => {
+    const sysAdmin = createTestUser({ id: 90017, tenantId: TENANT_A, roles: ["SystemAdmin"] });
+    const result = await stack.http.queryOk<{ rows: readonly { tenantId: string }[] }>(
+      CapOverviewQueries.tenantCapsList,
+      { filters: [{ field: "tier", op: "ne", value: "pro" }] },
+      sysAdmin,
+    );
+    const tenantIds = result.rows.map((row) => row.tenantId);
+    expect(tenantIds).not.toContain(TENANT_A);
+    expect(tenantIds).not.toContain(TENANT_B);
+    expect(tenantIds).toContain(TENANT_C);
+  });
+
+  test("op:lt on tier is rejected, not silently treated as no filter", async () => {
+    const sysAdmin = createTestUser({ id: 90018, tenantId: TENANT_A, roles: ["SystemAdmin"] });
+    const res = await stack.http.query(
+      CapOverviewQueries.tenantCapsList,
+      { filters: [{ field: "tier", op: "lt", value: "pro" }] },
+      sysAdmin,
+    );
+    expect(res.status).toBe(400);
+  });
+});
+
+describe("cap-overview list sort", () => {
+  test("sort:tier actually reorders the list, not just sortDirection", async () => {
+    const sysAdmin = createTestUser({ id: 90019, tenantId: TENANT_A, roles: ["SystemAdmin"] });
+    const result = await stack.http.queryOk<{
+      rows: readonly { tenantId: string; tier: string }[];
+    }>(CapOverviewQueries.tenantCapsList, { sort: "tier", sortDirection: "asc" }, sysAdmin);
+    const tierOrder = result.rows.map((row) => row.tier);
+    const sortedAscending = [...tierOrder].sort((a, b) => a.localeCompare(b));
+    expect(tierOrder).toEqual(sortedAscending);
+    expect(tierOrder).toContain("starter");
+  });
+
+  test("an unsupported sort field is rejected, not silently ignored", async () => {
+    const sysAdmin = createTestUser({ id: 90020, tenantId: TENANT_A, roles: ["SystemAdmin"] });
+    const res = await stack.http.query(
+      CapOverviewQueries.tenantCapsList,
+      { sort: "usage" },
+      sysAdmin,
+    );
+    expect(res.status).toBe(400);
+  });
+});

package/src/cap-overview/__tests__/cap-overview.boot.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { billingFoundationFeature } from "../../billing-foundation";
+import { createComplianceProfilesFeature } from "../../compliance-profiles";
+import { createConfigFeature } from "../../config/feature";
+import { createTenantFeature } from "../../tenant";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import { tierEngineFeature } from "../../tier-engine";
+import {
+  MY_CAPS_SCREEN_ID,
+  PLATFORM_TENANT_CAPS_SCREEN_ID,
+  TENANT_CAP_LIST_SCREEN_ID,
+} from "../constants";
+import { createCapOverviewFeature } from "../feature";
+import type { CapSpec } from "../types";
+
+const testCap: CapSpec = {
+  id: "widgets",
+  label: "test.cap.widgets",
+  limit: () => 5,
+  usage: async () => 0,
+};
+
+describe("cap-overview boot", () => {
+  test("boots cleanly with a minimal cap set", () => {
+    const features = [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      tierEngineFeature,
+      billingFoundationFeature,
+      createCapOverviewFeature({ caps: [testCap] }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("boots cleanly with the tier facet enabled (facets + filters schema wiring)", () => {
+    const features = [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      tierEngineFeature,
+      billingFoundationFeature,
+      createCapOverviewFeature({ caps: [testCap], tiers: ["free", "pro"] }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("registers all three queries and three screens", () => {
+    const feature = createCapOverviewFeature({ caps: [testCap] });
+    expect(feature.queryHandlers["tenant-caps:list"]).toBeDefined();
+    expect(feature.queryHandlers["caps:usage"]).toBeDefined();
+    expect(feature.queryHandlers["tenant-options"]).toBeDefined();
+    expect(feature.screens[TENANT_CAP_LIST_SCREEN_ID]?.type).toBe("projectionList");
+    expect(feature.screens[MY_CAPS_SCREEN_ID]?.type).toBe("dashboard");
+    expect(feature.screens[PLATFORM_TENANT_CAPS_SCREEN_ID]?.type).toBe("dashboard");
+  });
+
+  test("tenant-cap-list facet field is a declared column and the list handler schema accepts filters", () => {
+    const feature = createCapOverviewFeature({ caps: [testCap], tiers: ["free", "pro"] });
+    const screen = feature.screens[TENANT_CAP_LIST_SCREEN_ID];
+    if (screen?.type !== "projectionList") throw new Error("expected projectionList screen");
+    const facetField = screen.facets?.[0]?.field;
+    const columnFields = screen.columns.map((column) =>
+      typeof column === "string" ? column : column.field,
+    );
+    expect(facetField).toBe("tier");
+    expect(columnFields).toContain("tier");
+    expect(columnFields).toContain(`cap_${testCap.id}`);
+  });
+
+  test("no tier facet when `tiers` is omitted", () => {
+    const feature = createCapOverviewFeature({ caps: [testCap] });
+    const screen = feature.screens[TENANT_CAP_LIST_SCREEN_ID];
+    if (screen?.type !== "projectionList") throw new Error("expected projectionList screen");
+    expect(screen.facets ?? []).toHaveLength(0);
+  });
+
+  // Deep-link: clicking a row on tenant-cap-list must land on THAT tenant's
+  // dashboard, not an empty one — the boot validator now lets a navigate
+  // rowAction's params through onto a dashboard target when its extractor
+  // produces the target's own `filter.id` (framework#1708 follow-up).
+  test("row-click deep-links into platform-tenant-caps with a params extractor matching its filter id", () => {
+    const features = [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      tierEngineFeature,
+      billingFoundationFeature,
+      createCapOverviewFeature({ caps: [testCap] }),
+    ];
+    expect(() => validateBoot(features)).not.toThrow();
+
+    const feature = createCapOverviewFeature({ caps: [testCap] });
+    const listScreen = feature.screens[TENANT_CAP_LIST_SCREEN_ID];
+    if (listScreen?.type !== "projectionList") throw new Error("expected projectionList screen");
+    const rowAction = listScreen.rowActions?.[0];
+    if (rowAction?.kind !== "navigate") throw new Error("expected a navigate rowAction");
+    expect(rowAction.rowClick).toBe(true);
+    expect(rowAction.screen).toBe(PLATFORM_TENANT_CAPS_SCREEN_ID);
+    expect(rowAction.params).toEqual({ map: { tenantId: "tenantId" } });
+
+    const dashboardScreen = feature.screens[PLATFORM_TENANT_CAPS_SCREEN_ID];
+    if (dashboardScreen?.type !== "dashboard") throw new Error("expected dashboard screen");
+    expect(dashboardScreen.filter?.id).toBe("tenantId");
+  });
+
+  test("throws at construction when listCaps references an unknown cap id", () => {
+    expect(() =>
+      createCapOverviewFeature({ caps: [testCap], listCaps: ["does-not-exist"] }),
+    ).toThrow(/unknown cap id "does-not-exist"/);
+  });
+
+  test("throws when caps is empty", () => {
+    expect(() => createCapOverviewFeature({ caps: [] })).toThrow(/must not be empty/);
+  });
+});

package/src/cap-overview/__tests__/usage-math.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { computeFraction, computeTone, computeUnclampedFraction } from "../usage-math";
+
+describe("computeFraction", () => {
+  test("used 3 of limit 5 -> 0.6", () => {
+    expect(computeFraction(3, 5)).toBe(0.6);
+  });
+
+  test("limit 0 -> 0, never NaN/Infinity", () => {
+    expect(computeFraction(5, 0)).toBe(0);
+    expect(computeFraction(0, 0)).toBe(0);
+  });
+
+  test("negative limit -> 0", () => {
+    expect(computeFraction(1, -5)).toBe(0);
+  });
+
+  test("used over limit clamps to 1", () => {
+    expect(computeFraction(9, 5)).toBe(1);
+  });
+
+  test("used 0 of a positive limit -> 0", () => {
+    expect(computeFraction(0, 5)).toBe(0);
+  });
+});
+
+describe("computeUnclampedFraction", () => {
+  test("used over limit -> ratio above 1, unlike computeFraction", () => {
+    expect(computeUnclampedFraction(7, 5)).toBe(1.4);
+    expect(computeFraction(7, 5)).toBe(1);
+  });
+
+  test("limit 0 -> 0, never NaN/Infinity", () => {
+    expect(computeUnclampedFraction(5, 0)).toBe(0);
+  });
+
+  test("used 3 of limit 5 -> 0.6, same as the clamped case", () => {
+    expect(computeUnclampedFraction(3, 5)).toBe(0.6);
+  });
+});
+
+describe("computeTone", () => {
+  test("below 0.8 -> default", () => {
+    expect(computeTone(0)).toBe("default");
+    expect(computeTone(0.79)).toBe("default");
+  });
+
+  test("0.8 up to (not including) 1 -> warn", () => {
+    expect(computeTone(0.8)).toBe("warn");
+    expect(computeTone(0.99)).toBe("warn");
+  });
+
+  test("5/5 (fraction 1) -> danger", () => {
+    expect(computeTone(computeFraction(5, 5))).toBe("danger");
+  });
+
+  test("fraction >= 1 -> danger", () => {
+    expect(computeTone(1)).toBe("danger");
+  });
+});

package/src/cap-overview/changes.json

@@ -0,0 +1,8 @@
+[
+  {
+    "version": "0.224.0",
+    "type": "improvement",
+    "title": "Add cap-overview feature: tier + cap usage visibility per tenant.",
+    "detail": "New read-only bundled feature. SystemAdmin gets a paged, searchable tenant list with tier/billing columns and per-cap usage bars, plus a per-tenant dashboard reachable from the list. TenantAdmin gets a 'My usage' dashboard showing their own tenant's cap usage as cards. Reads tier-engine, billing-foundation and tenant projections plus caller-supplied CapSpec usage callbacks; every handler enforces explicit tenant scoping (no ambient tenant filter, cross-tenant reads require SystemAdmin + acknowledgeCrossTenant)."
+  }
+]

package/src/cap-overview/constants.ts

@@ -0,0 +1,26 @@
+// @runtime client
+// Pure string-literal constants — imported by both server (feature.ts,
+// handlers/) and client (web/) code. See tier-engine/constants.ts for the
+// same convention.
+
+export const CAP_OVERVIEW_FEATURE = "cap-overview" as const;
+
+export const TENANT_CAP_LIST_SCREEN_ID = "tenant-cap-list" as const;
+export const MY_CAPS_SCREEN_ID = "my-caps" as const;
+export const PLATFORM_TENANT_CAPS_SCREEN_ID = "platform-tenant-caps" as const;
+
+export const CapOverviewQueries = {
+  tenantCapsList: "cap-overview:query:tenant-caps:list",
+  capsUsage: "cap-overview:query:caps:usage",
+  tenantOptions: "cap-overview:query:tenant-options",
+} as const;
+
+export const CAP_USAGE_CELL_COMPONENT = "CapUsageCell" as const;
+export const CAP_CARDS_PANEL_COMPONENT = "CapCardsPanel" as const;
+
+// Virtual column field name for a cap's usage cell on tenant-cap-list —
+// prefixed so it can never collide with a real projection column ("name",
+// "tier", "billing").
+export function capFieldName(capId: string): string {
+  return `cap_${capId}`;
+}