@cosmicdrift/kumiko-samples 0.391.1 → 0.392.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.391.1",
+  "version": "0.392.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.391.1",
+  "version": "0.392.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/src/admin-shell/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "includeTenantOverview turns the tenant overview off",
+    "detail": "createAdminShellFeature({ includeTenantOverview: false }) registers neither the tenant overview screen nor its nav and leaves it out of the tenant workspace. The default stays true."
+  },
   {
     "version": "0.363.0",
     "type": "improvement",

package/packages/bundled-features/src/admin-shell/feature.ts

@@ -39,6 +39,9 @@ export type CreateAdminShellOptions = {
   /** Tenant nav → document-designer:nav:templates, platform nav → document-designer:nav:platform-templates.
    *  Requires document-designer mounted (a separate package, so no import here). Default false. */
   readonly includeDocumentDesigner?: boolean;
+  /** Tenant overview dashboard: screen, nav and the entry in the tenant workspace. Default true.
+   *  Set false when the app ships its own landing screen for tenant admins. */
+  readonly includeTenantOverview?: boolean;
   /** When false, only overview screens + nav are registered — app owns r.workspace(). Default true. */
   readonly registerWorkspaces?: boolean;
   /** Metric list the overview panels are built from — pass the SAME list to
@@ -47,18 +50,48 @@ export type CreateAdminShellOptions = {
   readonly metrics?: readonly MetricDefinition[];
 };
 
+type NavIdOptions = {
+  readonly includeTenantOverview?: boolean;
+  readonly includeTierAdmin?: boolean;
+  readonly includeCapOverview: boolean;
+  readonly includeDocumentDesigner: boolean;
+};
+
+function tenantWorkspaceNavIds(options: NavIdOptions): string[] {
+  return [
+    ...(options.includeTenantOverview === true ? ["admin-shell:nav:tenant-overview"] : []),
+    "tenant:nav:members",
+    "audit:nav:audit-log",
+    ...(options.includeCapOverview ? ["admin-shell:nav:my-caps"] : []),
+    ...(options.includeDocumentDesigner ? ["document-designer:nav:templates"] : []),
+  ];
+}
+
+function platformWorkspaceNavIds(options: NavIdOptions): string[] {
+  return [
+    "admin-shell:nav:platform-overview",
+    "admin-shell:nav:tenants",
+    ...(options.includeCapOverview ? ["admin-shell:nav:tenant-caps"] : []),
+    "audit:nav:audit-log-all-tenants",
+    "jobs:nav:job-runs",
+    ...(options.includeDocumentDesigner ? ["document-designer:nav:platform-templates"] : []),
+    ...(options.includeTierAdmin === true ? ["admin-shell:nav:tier-admin"] : []),
+  ];
+}
+
 export function createAdminShellFeature(options: CreateAdminShellOptions = {}): FeatureDefinition {
   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 includeDocumentDesigner = options.includeDocumentDesigner ?? false;
+  const includeTenantOverview = options.includeTenantOverview ?? true;
   const registerWorkspaces = options.registerWorkspaces ?? true;
   const metrics = options.metrics ?? DEFAULT_METRICS;
 
   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`, `audit:screen:audit-log-all-tenants`, `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`, optional `document-designer` template navs) and the two overview dashboards, built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; 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`, `audit:screen:audit-log-all-tenants`, `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`, optional `document-designer` template navs) and the two overview dashboards (the tenant one can be dropped with `includeTenantOverview: false`), built from the metrics list (`metrics` option, default DEFAULT_METRICS). Mount after user, tenant, audit, jobs, metrics and metrics-system; 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",
@@ -77,39 +110,35 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
 
     r.translations({ keys: ADMIN_SHELL_I18N });
 
-    const tenantNav: string[] = [
-      "admin-shell:nav:tenant-overview",
-      "tenant:nav:members",
-      "audit:nav:audit-log",
-      ...(includeCapOverview ? (["admin-shell:nav:my-caps"] as const) : []),
-      ...(includeDocumentDesigner ? (["document-designer:nav:templates"] as const) : []),
-    ];
-    const platformNav: string[] = [
-      "admin-shell:nav:platform-overview",
-      "admin-shell:nav:tenants",
-      ...(includeCapOverview ? (["admin-shell:nav:tenant-caps"] as const) : []),
-      "audit:nav:audit-log-all-tenants",
-      "jobs:nav:job-runs",
-      ...(includeDocumentDesigner ? (["document-designer:nav:platform-templates"] as const) : []),
-      ...(includeTierAdmin ? (["admin-shell:nav:tier-admin"] as const) : []),
-    ];
-
-    r.screen({
-      id: TENANT_OVERVIEW_SCREEN_ID,
-      type: "dashboard",
-      access: { roles: access.admin },
-      description: "admin-shell.screen.tenant-overview.subtitle",
-      timeRange: OVERVIEW_TIME_RANGE,
-      panels: [...tenantOverviewPanels(metrics, { includeCapOverview })],
+    const tenantNav = tenantWorkspaceNavIds({
+      includeTenantOverview,
+      includeCapOverview,
+      includeDocumentDesigner,
     });
-    r.nav({
-      id: "tenant-overview",
-      label: "admin-shell:nav.tenantOverview",
-      icon: "home",
-      screen: "admin-shell:screen:tenant-overview",
-      order: 1,
+    const platformNav = platformWorkspaceNavIds({
+      includeTierAdmin,
+      includeCapOverview,
+      includeDocumentDesigner,
     });
 
+    if (includeTenantOverview) {
+      r.screen({
+        id: TENANT_OVERVIEW_SCREEN_ID,
+        type: "dashboard",
+        access: { roles: access.admin },
+        description: "admin-shell.screen.tenant-overview.subtitle",
+        timeRange: OVERVIEW_TIME_RANGE,
+        panels: [...tenantOverviewPanels(metrics, { includeCapOverview })],
+      });
+      r.nav({
+        id: "tenant-overview",
+        label: "admin-shell:nav.tenantOverview",
+        icon: "home",
+        screen: "admin-shell:screen:tenant-overview",
+        order: 1,
+      });
+    }
+
     r.screen({
       id: PLATFORM_OVERVIEW_SCREEN_ID,
       type: "dashboard",

package/packages/bundled-features/src/auth-email-password/handlers/invite-accept-with-login.write.ts

@@ -37,7 +37,7 @@ import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/error
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { decryptStoredPii, sessionLocaleField, sessionTimezoneField } from "../../shared/index.ts";
-// kumiko-lint-ignore cross-feature-import invite-flow
+// kumiko-lint-ignore cross-feature-import the handler loads the pending invitation and marks it accepted
 import {
   INVITATION_STATUS,
   tenantInvitationEntity,
@@ -50,7 +50,7 @@ import {
   grantInvitedGlobalRoles,
   parseInvitedGlobalRoles,
 } from "../../user/invited-global-roles.ts";
-// kumiko-lint-ignore cross-feature-import login-style password-check
+// kumiko-lint-ignore cross-feature-import the handler verifies the invited email password against the user row, like login
 import { userTable } from "../../user/schema/user.ts";
 import { invalidCredentials, invalidInviteToken, inviteEmailMismatch } from "../errors.ts";
 import {

package/packages/bundled-features/src/auth-email-password/handlers/invite-signup-complete.write.ts

@@ -33,7 +33,7 @@ import {
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { decryptStoredPii, registrationLocaleFromRequest } from "../../shared/index.ts";
-// kumiko-lint-ignore cross-feature-import invite-flow
+// kumiko-lint-ignore cross-feature-import the handler loads the pending invitation and marks it accepted
 import {
   INVITATION_STATUS,
   tenantInvitationEntity,
@@ -48,7 +48,7 @@ import {
 import { seedTenantMembership } from "../../tenant/seeding.ts";
 // kumiko-lint-ignore cross-feature-import global roles granted on invite accept live on the user row
 import { parseInvitedGlobalRoles } from "../../user/invited-global-roles.ts";
-// kumiko-lint-ignore cross-feature-import existence-check
+// kumiko-lint-ignore cross-feature-import the handler rejects an invitation whose email already has a user row
 import { userTable } from "../../user/schema/user.ts";
 import { invalidInviteToken } from "../errors.ts";
 import {

package/packages/bundled-features/src/cap-overview/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "Cap amounts follow their unit and a limit of 0 reads \"Not included\"",
+    "detail": "Values with unit \"mb\" show as MB, GB or TB (base 1024), count and tokens use the locale's digit grouping. A limit of 0 or less shows \"Not included\" instead of a 0 bar, also when nothing is measured. caps:usage rows and the tenant-caps list cells now carry the unit of the cap. New key cap-overview.notIncluded in all locale packages."
+  },
+  {
+    "version": "0.392.0",
+    "type": "improvement",
+    "title": "CapCardsPanel can be limited to specific cap keys via params.capKeys",
+    "detail": "A custom dashboard panel with params capKeys as a list of cap ids shows only those cards, in the order of the capsUsage query. Anything other than a list of strings means no limit, and capKeys is not sent to the server. Each limited cap card also shows how much is left (or that nothing is), next to the percent chip, and a limited panel adds a link to the full usage screen."
+  },
   {
     "version": "0.383.0",
     "type": "improvement",

package/packages/bundled-features/src/cap-overview/handlers/caps-usage.query.ts

@@ -86,6 +86,7 @@ export function createCapsUsageQuery(
             id: cap.id,
             label: cap.label,
             limit,
+            ...(cap.unit !== undefined && { unit: cap.unit }),
             ...(cap.icon !== undefined && { icon: cap.icon }),
             ...(cap.accentColor !== undefined && { accentColor: cap.accentColor }),
           };

package/packages/bundled-features/src/cap-overview/handlers/tenant-caps-list.query.ts

@@ -262,10 +262,11 @@ export function createTenantCapsListQuery(caps: readonly CapSpec[], listCaps: re
           const rawUsed = usageByCap.get(cap.id)?.get(row.tenantId);
           const used = rawUsed === undefined ? 0 : rawUsed;
           const limit = limitByTenantAndCap.get(tenantCapKey(row.tenantId, cap.id)) ?? null;
+          const unit = cap.unit !== undefined ? { unit: cap.unit } : {};
           capFields[capFieldName(cap.id)] =
             used === null
-              ? { used: null, limit, fraction: 0 }
-              : { used, limit, fraction: computeFraction(used, limit) };
+              ? { used: null, limit, fraction: 0, ...unit }
+              : { used, limit, fraction: computeFraction(used, limit), ...unit };
         }
         return {
           tenantId: row.tenantId,

package/packages/bundled-features/src/cap-overview/i18n.ts

@@ -12,7 +12,11 @@ export const CAP_OVERVIEW_I18N: Readonly<Record<string, LocalizedString>> = {
   "cap-overview.platform.filter.tenant": { en: "Tenant" },
   "cap-overview.cards.empty": { en: "No caps configured for this tenant." },
   "cap-overview.cards.loading": { en: "Loading usage…" },
+  "cap-overview.cards.remaining": { en: "{amount} left" },
+  "cap-overview.cards.noneLeft": { en: "None left" },
+  "cap-overview.cards.viewAll": { en: "View all usage" },
   "cap-overview.notMeasured": { en: "Not measured yet" },
+  "cap-overview.notIncluded": { en: "Not included" },
   "cap-overview.unlimited": { en: "{used} · unlimited" },
   "cap-overview.errors.progressPrimitiveMissing": {
     en: "Usage bar unavailable — Progress primitive is not registered.",

package/packages/bundled-features/src/cap-overview/types.ts

@@ -2,6 +2,8 @@ import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { CapLimitContext } from "../cap-counter/index.ts";
 
+export type CapUnit = "count" | "mb" | "tokens";
+
 // Closed vocabulary for the dashboard cards' icon chip — cap-cards-panel.tsx
 // holds the matching lucide-react lookup. Small on purpose (YAGNI): extend
 // both together when a cap needs a shape not covered here.
@@ -35,7 +37,7 @@ export type CapSpec = {
     db: TenantDb,
     tenantIds: readonly TenantId[],
   ) => Promise<Map<TenantId, number | null>>;
-  readonly unit?: "count" | "mb" | "tokens";
+  readonly unit?: CapUnit;
   /** Icon chip on the dashboard cards. Optional — omitted renders the card
    *  without an icon, same as before this field existed. */
   readonly icon?: CapIconKey;
@@ -54,6 +56,7 @@ export type CapUsage = {
   // `limit: null` means unlimited — a pure usage meter with no cap to hit.
   readonly limit: number | null;
   readonly fraction: number;
+  readonly unit?: CapUnit;
 };
 
 export type CapUsageWithMeta = CapUsage & {

package/packages/bundled-features/src/cap-overview/web/cap-amount-format.ts

@@ -0,0 +1,37 @@
+import type { CapUnit } from "../types.ts";
+
+const MB_PER_GB = 1024;
+const MB_PER_TB = 1024 * 1024;
+
+function megabyteUnit(valueInMb: number): { readonly unit: string; readonly divisor: number } {
+  const magnitude = Math.abs(valueInMb);
+  if (magnitude < MB_PER_GB) return { unit: "megabyte", divisor: 1 };
+  if (magnitude < MB_PER_TB) return { unit: "gigabyte", divisor: MB_PER_GB };
+  return { unit: "terabyte", divisor: MB_PER_TB };
+}
+
+export function formatCapAmount(value: number, unit: CapUnit | undefined, locale: string): string {
+  try {
+    if (unit === "mb") {
+      const scaled = megabyteUnit(value);
+      return new Intl.NumberFormat(locale, {
+        style: "unit",
+        unit: scaled.unit,
+        unitDisplay: "short",
+        maximumFractionDigits: 1,
+      }).format(value / scaled.divisor);
+    }
+    return new Intl.NumberFormat(locale).format(value);
+  } catch {
+    return String(value);
+  }
+}
+
+export function formatCapUsedOfLimit(
+  used: number,
+  limit: number,
+  unit: CapUnit | undefined,
+  locale: string,
+): string {
+  return `${formatCapAmount(used, unit, locale)} / ${formatCapAmount(limit, unit, locale)}`;
+}

package/packages/bundled-features/src/cap-overview/web/cap-cards-panel.tsx

@@ -1,6 +1,12 @@
 import type { ExtensionSectionProps } from "@cosmicdrift/kumiko-renderer";
-import { usePrimitives, useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
-import { EMPTY_VALUE_PLACEHOLDER } from "@cosmicdrift/kumiko-renderer/headless";
+import {
+  useLocale,
+  useNav,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+import { EMPTY_VALUE_PLACEHOLDER, type Translate } from "@cosmicdrift/kumiko-renderer/headless";
 import {
   EmptyState,
   StatCard,
@@ -9,9 +15,11 @@ import {
 } from "@cosmicdrift/kumiko-renderer/web";
 import { Database, FileText, Gauge, Hash, Mail, Users } from "lucide-react";
 import type { ComponentType, ReactNode } from "react";
-import type { CapIconKey, CapUsageTone, CapUsageWithMeta } from "../types.ts";
+import type { CapIconKey, CapUnit, CapUsageTone, CapUsageWithMeta } from "../types.ts";
+import { formatCapAmount, formatCapUsedOfLimit } from "./cap-amount-format.ts";
 import { CapUsageBar } from "./cap-usage-bar.tsx";
-import { CapOverviewQueries } from "./constants.ts";
+import { CapOverviewQueries, MY_CAPS_SCREEN_ID } from "./constants.ts";
+import { isCapNotIncluded } from "./usage-math.ts";
 
 type CapsUsageResponse = { readonly rows: readonly CapUsageWithMeta[] };
 
@@ -41,6 +49,106 @@ function isMeasured(cap: CapUsageWithMeta): cap is CapUsageWithMeta & { used: nu
   return cap.used !== null;
 }
 
+// Boundary check: only an array of strings restricts; anything else means no restriction.
+function readCapKeys(value: unknown): ReadonlySet<string> | undefined {
+  if (!Array.isArray(value)) return undefined;
+  return new Set(value.filter((entry): entry is string => typeof entry === "string"));
+}
+
+function ViewAllLink(): ReactNode {
+  const t = useTranslation();
+  const { Link } = usePrimitives();
+  const nav = useNav();
+  const target = { screenId: MY_CAPS_SCREEN_ID };
+  return (
+    <Link
+      href={nav.hrefFor(target)}
+      onPress={() => nav.navigate(target)}
+      variant="muted"
+      testId="cap-cards-view-all"
+    >
+      {t("cap-overview.cards.viewAll")}
+    </Link>
+  );
+}
+
+function CapUsageSummaryRow({ cap }: { readonly cap: CapUsageWithMeta }): ReactNode {
+  const t = useTranslation();
+  const locale = useLocale().locale();
+  const remainingText =
+    isMeasured(cap) && cap.limit !== null && cap.limit > 0
+      ? remainingLabel(t, Math.max(cap.limit - cap.used, 0), cap.unit, locale)
+      : undefined;
+  if (cap.percent === null && remainingText === undefined) return null;
+  return (
+    <div className="flex items-center gap-2">
+      {cap.percent !== null && (
+        <StatusBadge tone={TONE_TO_STATUS[cap.tone]}>{`${cap.percent}%`}</StatusBadge>
+      )}
+      {remainingText !== undefined && (
+        <span className="text-sm text-muted-foreground" data-testid="cap-card-remaining">
+          {remainingText}
+        </span>
+      )}
+    </div>
+  );
+}
+
+function remainingLabel(
+  t: Translate,
+  rest: number,
+  unit: CapUnit | undefined,
+  locale: string,
+): string {
+  return rest > 0
+    ? t("cap-overview.cards.remaining", { amount: formatCapAmount(rest, unit, locale) })
+    : t("cap-overview.cards.noneLeft");
+}
+
+function CapUsageStat({
+  cap,
+  footer,
+}: {
+  readonly cap: CapUsageWithMeta;
+  readonly footer?: ReactNode;
+}): ReactNode {
+  const t = useTranslation();
+  const locale = useLocale().locale();
+  const Icon = cap.icon !== undefined ? CAP_ICONS[cap.icon] : undefined;
+  // An unlimited, measured cap has neither a badge nor a bar; StatCard still
+  // wraps any defined child in a spacing div, so pass undefined then.
+  const notIncluded = isCapNotIncluded(cap.limit);
+  const body =
+    !notIncluded && (!isMeasured(cap) || cap.limit !== null) ? (
+      <div className="flex flex-col gap-2">
+        <CapUsageSummaryRow cap={cap} />
+        <CapUsageBar usage={cap} showLabel={false} />
+        {footer}
+      </div>
+    ) : (
+      footer
+    );
+  return (
+    <StatCard
+      icon={Icon !== undefined ? <Icon className="size-4" /> : undefined}
+      label={t(cap.label)}
+      value={
+        notIncluded
+          ? t("cap-overview.notIncluded")
+          : !isMeasured(cap)
+            ? EMPTY_VALUE_PLACEHOLDER
+            : cap.limit === null
+              ? formatCapAmount(cap.used, cap.unit, locale)
+              : formatCapUsedOfLimit(cap.used, cap.limit, cap.unit, locale)
+      }
+      {...(cap.accentColor !== undefined && { accentColor: cap.accentColor })}
+      testId="cap-card"
+    >
+      {body}
+    </StatCard>
+  );
+}
+
 export function CapCardsPanel({ filterParams }: ExtensionSectionProps): ReactNode {
   const t = useTranslation();
   const { Banner } = usePrimitives();
@@ -58,62 +166,38 @@ export function CapCardsPanel({ filterParams }: ExtensionSectionProps): ReactNod
     );
   }
 
-  const rows = query.data?.rows ?? [];
+  const capKeys = readCapKeys(filterParams?.["capKeys"]);
+  const allRows = query.data?.rows ?? [];
+  const rows = capKeys === undefined ? allRows : allRows.filter((row) => capKeys.has(row.id));
 
   if (!query.loading && rows.length === 0) {
     return <EmptyState title={t("cap-overview.cards.empty")} testId="cap-cards-panel-empty" />;
   }
 
+  // A single limited card carries the link itself; several share one under the grid.
+  const linkInCard = capKeys !== undefined && rows.length === 1;
   return (
-    <div
-      // Arbitrary bracket values (grid-cols-[repeat(...)]) never compiled:
-      // styles.css's Tailwind v4 @source scan only covers renderer/web/src,
-      // renderer/src and samples/**/src (see its comment) — bundled-features
-      // isn't scanned, so a class unique to this file has no generated rule
-      // and silently no-ops (the grid fell back to one implicit column,
-      // stacking every card full-width). Reusing the exact classes
-      // dashboard-body.tsx's own panel grid already uses guarantees the
-      // rule exists, since that file IS in the scanned surface.
-      className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4"
-      data-testid="cap-cards-panel"
-    >
-      {query.loading && rows.length === 0 && (
-        <div className="text-sm text-muted-foreground">{t("cap-overview.cards.loading")}</div>
-      )}
-      {rows.map((cap) => {
-        const Icon = cap.icon !== undefined ? CAP_ICONS[cap.icon] : undefined;
-        // An unlimited, measured cap has neither a badge nor a bar; StatCard still
-        // wraps any defined child in a spacing div, so pass undefined then.
-        const body =
-          !isMeasured(cap) || cap.limit !== null ? (
-            <div className="flex flex-col gap-2">
-              {cap.percent !== null && (
-                <div className="flex items-center justify-between gap-2">
-                  <StatusBadge tone={TONE_TO_STATUS[cap.tone]}>{`${cap.percent}%`}</StatusBadge>
-                </div>
-              )}
-              <CapUsageBar usage={cap} showLabel={false} />
-            </div>
-          ) : undefined;
-        return (
-          <StatCard
-            key={cap.id}
-            icon={Icon !== undefined ? <Icon className="size-4" /> : undefined}
-            label={t(cap.label)}
-            value={
-              !isMeasured(cap)
-                ? EMPTY_VALUE_PLACEHOLDER
-                : cap.limit === null
-                  ? String(cap.used)
-                  : `${cap.used} / ${cap.limit}`
-            }
-            {...(cap.accentColor !== undefined && { accentColor: cap.accentColor })}
-            testId="cap-card"
-          >
-            {body}
-          </StatCard>
-        );
-      })}
+    <div className="flex flex-col gap-2">
+      <div
+        // Arbitrary bracket values (grid-cols-[repeat(...)]) never compiled:
+        // styles.css's Tailwind v4 @source scan only covers renderer/web/src,
+        // renderer/src and samples/**/src (see its comment) — bundled-features
+        // isn't scanned, so a class unique to this file has no generated rule
+        // and silently no-ops (the grid fell back to one implicit column,
+        // stacking every card full-width). Reusing the exact classes
+        // dashboard-body.tsx's own panel grid already uses guarantees the
+        // rule exists, since that file IS in the scanned surface.
+        className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4"
+        data-testid="cap-cards-panel"
+      >
+        {query.loading && rows.length === 0 && (
+          <div className="text-sm text-muted-foreground">{t("cap-overview.cards.loading")}</div>
+        )}
+        {rows.map((cap) => (
+          <CapUsageStat key={cap.id} cap={cap} footer={linkInCard ? <ViewAllLink /> : undefined} />
+        ))}
+      </div>
+      {capKeys !== undefined && !linkInCard && <ViewAllLink />}
     </div>
   );
 }

package/packages/bundled-features/src/cap-overview/web/cap-usage-bar.tsx

@@ -1,7 +1,8 @@
-import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useLocale, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import type { ReactNode } from "react";
 import type { CapUsage } from "../types.ts";
-import { computeTone } from "./usage-math.ts";
+import { formatCapAmount, formatCapUsedOfLimit } from "./cap-amount-format.ts";
+import { computeTone, isCapNotIncluded } from "./usage-math.ts";
 
 export function CapUsageBar({
   usage,
@@ -14,6 +15,15 @@ export function CapUsageBar({
 }): ReactNode {
   const { Progress, Text, Banner } = usePrimitives();
   const t = useTranslation();
+  const locale = useLocale().locale();
+
+  if (isCapNotIncluded(usage.limit)) {
+    return (
+      <Text variant="small" testId="cap-usage-not-included">
+        {t("cap-overview.notIncluded")}
+      </Text>
+    );
+  }
 
   if (usage.used === null) {
     return (
@@ -27,7 +37,7 @@ export function CapUsageBar({
     // A progress bar with no denominator says nothing — show the raw count instead.
     return showLabel ? (
       <Text variant="small" testId="cap-usage-unlimited">
-        {t("cap-overview.unlimited", { used: usage.used })}
+        {t("cap-overview.unlimited", { used: formatCapAmount(usage.used, usage.unit, locale) })}
       </Text>
     ) : null;
   }
@@ -49,7 +59,11 @@ export function CapUsageBar({
           {t("cap-overview.errors.progressPrimitiveMissing")}
         </Banner>
       )}
-      {showLabel && <Text variant="small">{`${usage.used} / ${usage.limit}`}</Text>}
+      {showLabel && (
+        <Text variant="small">
+          {formatCapUsedOfLimit(usage.used, usage.limit, usage.unit, locale)}
+        </Text>
+      )}
     </div>
   );
 }

package/packages/bundled-features/src/cap-overview/web/cap-usage-cell.tsx

@@ -1,9 +1,11 @@
 import type { ColumnRendererProps } from "@cosmicdrift/kumiko-renderer";
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { isOneOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import type { ReactNode } from "react";
-import type { CapUsage } from "../types.ts";
+import type { CapUnit, CapUsage } from "../types.ts";
 import { CapUsageBar } from "./cap-usage-bar.tsx";
 
+const CAP_UNITS: readonly CapUnit[] = ["count", "mb", "tokens"];
+
 function isCapUsage(value: unknown): value is CapUsage {
   if (!isPlainObject(value)) return false;
   const used = value["used"];
@@ -11,7 +13,8 @@ function isCapUsage(value: unknown): value is CapUsage {
   return (
     (typeof used === "number" || used === null) &&
     (typeof limit === "number" || limit === null) &&
-    typeof value["fraction"] === "number"
+    typeof value["fraction"] === "number" &&
+    (value["unit"] === undefined || isOneOf(CAP_UNITS, value["unit"]))
   );
 }
 

package/packages/bundled-features/src/cap-overview/web/usage-math.ts

@@ -8,9 +8,13 @@ const DANGER_THRESHOLD = 1;
 
 // limit === null means unlimited (no cap to measure against); limit <= 0
 // means "not part of this tier" — both render as 0, never NaN/Infinity.
+export function isCapNotIncluded(limit: number | null): boolean {
+  return limit !== null && limit <= 0;
+}
+
 function rawFraction(used: number, limit: number | null): number {
   if (limit === null) return 0;
-  if (limit <= 0) return 0;
+  if (isCapNotIncluded(limit)) return 0;
   const fraction = used / limit;
   return Number.isFinite(fraction) ? fraction : 0;
 }