@cosmicdrift/kumiko-samples 0.338.0

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

@@ -0,0 +1,27 @@
+[
+  {
+    "version": "0.330.0",
+    "type": "breaking",
+    "title": "admin-shell requires the metrics and metrics-system features and builds its overview dashboards from a metrics list",
+    "detail": "Dashboard panels gain the chart kinds `stacked-bars`, `segment-bars` and `stacked-area`, a subtitle, per-series tones, static query `params`, `ignoreScreenFilter`, an empty label and hint, a `span` (half/full width), a stat `sparklineField` and static `tone`, a `negative` tone, an unlabelled `stat-group` KPI strip and bar/badge list columns. Every panel shows skeleton, empty and error states with retry. A screen can declare a `timeRange` control and a `scope` badge and notice. The admin-shell overview screens use all of this and show the metrics of the new `metrics` and `metrics-system` features. `deliveries-by-channel` now labels the email, in-app and push channels.",
+    "migration": "Mount createMetricsFeature({ metrics: DEFAULT_METRICS }) and createSystemMetricsFeature({ metrics: DEFAULT_METRICS }) from the metrics bundled feature before admin-shell. DEFAULT_METRICS also requires the delivery, sessions, jobs and tenant features.\n\nIf you do not mount all of them, pass the same reduced list to all three: createMetricsFeature({ metrics }), createSystemMetricsFeature({ metrics }) and createAdminShellFeature({ metrics }). Overview panels exist only for metric ids in that list."
+  },
+  {
+    "version": "0.330.0",
+    "type": "improvement",
+    "title": "Bundled screen subtitles (admin-shell, jobs, auth-mfa, tier-engine, user-profile) are i18n keys with de and es translations",
+    "migration": "Additive. Apps that override these screen descriptions keep working; apps that asserted the old English description text in tests now see the translated subtitle."
+  },
+  {
+    "version": "0.241.0",
+    "type": "fix",
+    "title": "tenant-overview/platform-overview dashboards no longer show \"undefined\" tiles; both converted to declarative dashboard screens (fw#2312).",
+    "detail": "Both overview screens sent `totalCount: true` to `tenant:query:list`/`jobs:query:list`, but neither handler's Zod schema declared the field, so it was stripped before the handler saw it and the tile rendered the literal string \"undefined\". Both handlers now accept `totalCount: boolean` and return `total` when set — `jobs:query:list`'s total is a real count (via `countWhere`), not `rows.length`, so it isn't capped by `limit`. `config:query:readiness` gains `missingCount`/`missingTone` alongside the existing `missing` array. `PlatformOverviewScreen`/`TenantOverviewScreen` (never public exports) and their `overview-layout`/`overview-query` support modules are gone — both screens are now `type: \"dashboard\"` (`kind: \"stat\"` panels) rendered by the generic renderer, using the new `DashboardStatPanel.params` (see framework changelog) to pin the failed-jobs tile's `status: \"failed\"` filter server-side. The `overview-allowlist` exports (`isOverviewQueryAllowed`, `overviewAllowedQueries`, the allow/forbidden-list constants) are unchanged and still importable — they're now checked against the screen definitions in tests instead of gating a deleted client-side dispatch call."
+  },
+  {
+    "version": "0.125.0",
+    "type": "improvement",
+    "title": "admin-shell: neues bundled-feature für rollen-gated Tenant- und Platform-Workspaces mit O…",
+    "detail": "admin-shell: neues bundled-feature für rollen-gated Tenant- und Platform-Workspaces mit Overview-Home-Screens, Nav-Icons und Server-i18n. Komponiert Screens aus `tenant`, `audit`, `jobs` und optional `tier-engine` — mount nach diesen Features. Overview-Queries laufen über eine fest kodierte Allowlist pro Workspace, um versehentliche Cross-Workspace-Datenzugriffe zu verhindern."
+  }
+]

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

@@ -0,0 +1,11 @@
+// @runtime client
+export const ADMIN_SHELL_FEATURE = "admin-shell" as const;
+
+export const DEFAULT_TENANT_WORKSPACE_ID = "tenant-admin" as const;
+export const DEFAULT_PLATFORM_WORKSPACE_ID = "platform" as const;
+
+/** Tenant workspace home — attention cards, query-allowlisted. */
+export const TENANT_OVERVIEW_SCREEN_ID = "tenant-overview" as const;
+
+/** Platform workspace home — attention cards, query-allowlisted. */
+export const PLATFORM_OVERVIEW_SCREEN_ID = "platform-overview" as const;

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

@@ -0,0 +1,184 @@
+// admin-shell — role-gated workspaces + provider nav for tenant vs platform operators.
+// Screens live in owner features (tenant, audit, jobs, …); this feature only
+// composes workspaces and cross-feature nav entries.
+
+import {
+  access,
+  defineFeature,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DEFAULT_METRICS, type MetricDefinition } from "../metrics/index.js";
+import {
+  ADMIN_SHELL_FEATURE,
+  DEFAULT_PLATFORM_WORKSPACE_ID,
+  DEFAULT_TENANT_WORKSPACE_ID,
+  PLATFORM_OVERVIEW_SCREEN_ID,
+  TENANT_OVERVIEW_SCREEN_ID,
+} from "./constants.js";
+import { ADMIN_SHELL_I18N } from "./i18n.js";
+import {
+  OVERVIEW_TIME_RANGE,
+  PLATFORM_SCOPE,
+  PLATFORM_TENANT_FILTER,
+  platformOverviewPanels,
+  tenantOverviewPanels,
+} from "./overview-panels.js";
+
+export type CreateAdminShellOptions = {
+  /** Short workspace id for tenant operators (URL segment). Default `tenant-admin`. */
+  readonly workspaceIds?: {
+    readonly tenant?: string;
+    readonly platform?: string;
+  };
+  /** 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;
+  /** Metric list the overview panels are built from — pass the SAME list to
+   *  createMetricsFeature / createSystemMetricsFeature. Panels exist only for
+   *  ids in this list. Default DEFAULT_METRICS. */
+  readonly metrics?: readonly MetricDefinition[];
+};
+
+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 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`, `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`) 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()`.",
+    );
+    r.uiHints({
+      displayLabel: "Admin Shell",
+      category: "operations",
+      recommended: false,
+    });
+    r.requires("user");
+    r.requires("tenant");
+    r.requires("audit");
+    r.requires("jobs");
+    r.requires("metrics");
+    r.requires("metrics-system");
+    if (includeTierAdmin) r.requires("tier-engine");
+    if (includeCapOverview) r.requires("cap-overview");
+
+    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) : []),
+    ];
+    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) : []),
+    ];
+
+    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",
+      access: { roles: access.systemAdmin },
+      description: "admin-shell.screen.platform-overview.subtitle",
+      scope: PLATFORM_SCOPE,
+      timeRange: OVERVIEW_TIME_RANGE,
+      // The picker needs a SystemAdmin {rows:{value,label}} tenant query; only cap-overview ships one.
+      ...(includeCapOverview && { filter: PLATFORM_TENANT_FILTER }),
+      panels: [...platformOverviewPanels(metrics)],
+    });
+    r.nav({
+      id: "platform-overview",
+      label: "admin-shell:nav.platformOverview",
+      icon: "dashboard",
+      screen: "admin-shell:screen:platform-overview",
+      order: 1,
+    });
+
+    r.nav({
+      id: "tenants",
+      label: "admin-shell:nav.tenants",
+      icon: "building",
+      screen: "tenant:screen:tenant-list",
+      access: { roles: access.systemAdmin },
+      order: 10,
+    });
+
+    if (includeTierAdmin) {
+      r.nav({
+        id: "tier-admin",
+        label: "admin-shell:nav.tierAdmin",
+        icon: "shield",
+        screen: "tier-engine:screen:tier-admin",
+        access: { roles: access.systemAdmin },
+        order: 30,
+      });
+    }
+
+    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,
+        label: "admin-shell:workspace.tenant",
+        icon: "users",
+        order: 1,
+        access: { roles: access.admin },
+        nav: [...tenantNav],
+        default: true,
+      });
+
+      r.workspace({
+        id: platformWsId,
+        label: "admin-shell:workspace.platform",
+        icon: "shield",
+        order: 2,
+        access: { roles: access.systemAdmin },
+        nav: platformNav,
+      });
+    }
+  });
+}

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

@@ -0,0 +1,54 @@
+// @runtime client
+// Pure-Data i18n keys for admin-shell (server r.translations + client pivot).
+// Without these keys nav labels and workspace tabs render raw QNs in the shell.
+
+type LocalizedString = { readonly en: string };
+
+export const ADMIN_SHELL_I18N: Readonly<Record<string, LocalizedString>> = {
+  "screen:tenant-overview.title": { en: "Overview" },
+  "screen:platform-overview.title": { en: "Overview" },
+  "admin-shell.screen.tenant-overview.subtitle": {
+    en: "Activity, failed jobs and deliveries, quotas and open admin tasks of this tenant.",
+  },
+  "admin-shell.screen.platform-overview.subtitle": {
+    en: "Tenant, user, job and delivery health across the whole installation.",
+  },
+  "admin-shell:workspace.tenant": { en: "Administration" },
+  "admin-shell:workspace.platform": { en: "Platform" },
+  "admin-shell:nav.tenantOverview": { en: "Overview" },
+  "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.kpi.activeTenants": { en: "Active tenants" },
+  "admin-shell:overview.kpi.activeUsers7d": { en: "Active users, 7 days" },
+  "admin-shell:overview.kpi.activeMembers7d": { en: "Active members, 7 days" },
+  "admin-shell:overview.kpi.failedJobs24h": { en: "Failed jobs, 24 h" },
+  "admin-shell:overview.kpi.failedDeliveries24h": { en: "Failed deliveries, 24 h" },
+  "admin-shell:overview.chart.jobRunsByStatus": { en: "Job runs by status" },
+  "admin-shell:overview.chart.deliveriesByChannel": { en: "Deliveries by channel" },
+  "admin-shell:overview.chart.auditWrites": { en: "Changes per day" },
+  "admin-shell:overview.chart.auditWritesSubtitle": { en: "Audit log, 14 days" },
+  "admin-shell:overview.list.recentFailures": { en: "Recent failures" },
+  "admin-shell:overview.list.recentFailuresEmpty": { en: "No failed jobs" },
+  "admin-shell:overview.list.quotas": { en: "Quotas" },
+  "admin-shell:overview.list.quotasEmpty": { en: "No quotas configured" },
+  "admin-shell:overview.col.job": { en: "Job" },
+  "admin-shell:overview.col.startedAt": { en: "Started" },
+  "admin-shell:overview.col.failedAt": { en: "Failed at" },
+  "admin-shell:overview.col.reason": { en: "Reason" },
+  "admin-shell:overview.col.quota": { en: "Quota" },
+  "admin-shell:overview.col.used": { en: "Used" },
+  "admin-shell:overview.col.limit": { en: "Limit" },
+  "admin-shell:overview.col.usage": { en: "Usage" },
+  "admin-shell:overview.range.24h": { en: "24 hours" },
+  "admin-shell:overview.range.7d": { en: "7 days" },
+  "admin-shell:overview.range.30d": { en: "30 days" },
+  "admin-shell:overview.scope.badge": { en: "All tenants" },
+  "admin-shell:overview.scope.notice": {
+    en: "You are viewing data of all tenants. Cross-tenant queries are recorded in the audit log.",
+  },
+  "admin-shell:overview.filter.tenant": { en: "Tenant" },
+  "admin-shell:overview.filter.allTenants": { en: "All tenants" },
+};

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

@@ -0,0 +1,17 @@
+export {
+  ADMIN_SHELL_FEATURE,
+  DEFAULT_PLATFORM_WORKSPACE_ID,
+  DEFAULT_TENANT_WORKSPACE_ID,
+  PLATFORM_OVERVIEW_SCREEN_ID,
+  TENANT_OVERVIEW_SCREEN_ID,
+} from "./constants.js";
+export { type CreateAdminShellOptions, createAdminShellFeature } from "./feature.js";
+export { ADMIN_SHELL_I18N } from "./i18n.js";
+export {
+  isOverviewQueryAllowed,
+  type OverviewWorkspaceKind,
+  overviewAllowedQueries,
+  PLATFORM_OVERVIEW_ALLOWED_QUERIES,
+  TENANT_OVERVIEW_ALLOWED_QUERIES,
+  TENANT_OVERVIEW_FORBIDDEN_QUERIES,
+} from "./overview-allowlist.js";

package/packages/bundled-features/src/admin-shell/overview-allowlist.ts

@@ -0,0 +1,47 @@
+// Hard-coded query allowlists for overview-home screens — security boundary
+// against privilege escalation via accidental cross-workspace fetches.
+
+import { CapOverviewQueries } from "../cap-overview/index.js";
+import { JobQueries } from "../jobs/index.js";
+import { METRICS_FEATURE, METRICS_SYSTEM_FEATURE } from "../metrics/index.js";
+
+export type OverviewWorkspaceKind = "tenant" | "platform";
+
+/** Tenant workspace overview may only call these queries. */
+export const TENANT_OVERVIEW_ALLOWED_QUERIES = [
+  JobQueries.failures,
+  CapOverviewQueries.capsUsage,
+] as const;
+
+// Metric ids come from the app's metric list, so the boundary is the feature
+// prefix: tenant-scope metrics for the tenant overview, system-scope for the platform one.
+const METRIC_QUERY_PREFIX: Readonly<Record<OverviewWorkspaceKind, string>> = {
+  tenant: `${METRICS_FEATURE}:query:`,
+  platform: `${METRICS_SYSTEM_FEATURE}:query:`,
+};
+
+/** Platform workspace overview may only call these queries. */
+export const PLATFORM_OVERVIEW_ALLOWED_QUERIES = [
+  JobQueries.list,
+  CapOverviewQueries.tenantOptions,
+] as const;
+
+/** Regression guard — TenantAdmin overview must never touch these (HTTP 403). */
+export const TENANT_OVERVIEW_FORBIDDEN_QUERIES = [
+  "tenant:query:list",
+  "jobs:query:list",
+  "feature-toggles:query:list",
+  "feature-toggles:query:registered",
+  "user:query:user:list",
+] as const;
+
+export function overviewAllowedQueries(kind: OverviewWorkspaceKind): readonly string[] {
+  return kind === "tenant" ? TENANT_OVERVIEW_ALLOWED_QUERIES : PLATFORM_OVERVIEW_ALLOWED_QUERIES;
+}
+
+export function isOverviewQueryAllowed(kind: OverviewWorkspaceKind, queryName: string): boolean {
+  return (
+    overviewAllowedQueries(kind).includes(queryName) ||
+    queryName.startsWith(METRIC_QUERY_PREFIX[kind])
+  );
+}

package/packages/bundled-features/src/admin-shell/overview-panels.ts

@@ -0,0 +1,225 @@
+// Declarative panel sets of the two overview dashboards. Panels are derived from
+// the metric list the app mounts, so a reduced list yields a reduced dashboard
+// instead of panels pointing at queries that do not exist.
+
+import type {
+  DashboardChartPanel,
+  DashboardFilterDefinition,
+  DashboardListPanel,
+  DashboardPanelDefinition,
+  DashboardPanelSpan,
+  DashboardStatPanel,
+  DashboardTimeRangeDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { CapOverviewQueries } from "../cap-overview/index.js";
+import { JobQueries } from "../jobs/index.js";
+import { type MetricDefinition, type MetricScope, metricQueryName } from "../metrics/index.js";
+
+const I = "admin-shell:overview";
+
+export const OVERVIEW_TIME_RANGE: DashboardTimeRangeDefinition = {
+  id: "range",
+  options: [
+    { value: "24h", label: `${I}.range.24h` },
+    { value: "7d", label: `${I}.range.7d` },
+    { value: "30d", label: `${I}.range.30d` },
+  ],
+  default: "7d",
+};
+
+export const PLATFORM_TENANT_FILTER: DashboardFilterDefinition = {
+  id: "tenantId",
+  label: `${I}.filter.tenant`,
+  kind: "select",
+  allLabel: `${I}.filter.allTenants`,
+  optionsQuery: CapOverviewQueries.tenantOptions,
+};
+
+export const PLATFORM_SCOPE = {
+  badge: `${I}.scope.badge`,
+  notice: `${I}.scope.notice`,
+} as const;
+
+type MetricPanelContext = {
+  readonly scope: MetricScope;
+  readonly has: (metricId: string) => boolean;
+};
+
+function contextFor(metrics: readonly MetricDefinition[], scope: MetricScope): MetricPanelContext {
+  return {
+    scope,
+    has: (metricId) =>
+      metrics.some((metric) => metric.id === metricId && metric.scopes.includes(scope)),
+  };
+}
+
+function kpi(
+  ctx: MetricPanelContext,
+  metricId: string,
+  label: string,
+  options: { readonly trend?: boolean; readonly negative?: boolean } = {},
+): readonly DashboardStatPanel[] {
+  if (!ctx.has(metricId)) return [];
+  return [
+    {
+      kind: "stat",
+      id: `kpi-${metricId}`,
+      label: `${I}.kpi.${label}`,
+      query: metricQueryName(ctx.scope, metricId),
+      valueField: "value",
+      ...(options.trend === true && {
+        deltaField: "delta",
+        deltaDirectionField: "deltaDirection",
+        sparklineField: "points",
+      }),
+      ...(options.negative === true && { tone: "negative" as const }),
+    },
+  ];
+}
+
+function kpiStrip(stats: readonly DashboardStatPanel[]): readonly DashboardPanelDefinition[] {
+  return stats.length === 0 ? [] : [{ kind: "stat-group", id: "kpis", stats }];
+}
+
+function chart(
+  ctx: MetricPanelContext,
+  metricId: string,
+  panel: Omit<DashboardChartPanel, "kind" | "query">,
+): readonly DashboardPanelDefinition[] {
+  if (!ctx.has(metricId)) return [];
+  return [{ kind: "chart", query: metricQueryName(ctx.scope, metricId), ...panel }];
+}
+
+const DELIVERY_SEGMENT_TONES = {
+  sent: "positive",
+  failed: "negative",
+  skipped: "neutral",
+  queued: "neutral",
+} as const;
+
+const HALF = { span: "half" } as const;
+
+function recentFailuresList(
+  query: string,
+  params: Readonly<Record<string, unknown>>,
+  columns: DashboardListPanel["columns"],
+  span: DashboardPanelSpan,
+): DashboardPanelDefinition {
+  return {
+    kind: "list",
+    id: "recent-failures",
+    label: `${I}.list.recentFailures`,
+    query,
+    params,
+    ignoreScreenFilter: true,
+    columns,
+    span,
+    emptyLabel: `${I}.list.recentFailuresEmpty`,
+  };
+}
+
+export function platformOverviewPanels(
+  metrics: readonly MetricDefinition[],
+): readonly DashboardPanelDefinition[] {
+  const ctx = contextFor(metrics, "system");
+  // Sources without a tenant column cannot be narrowed by the tenant picker.
+  const tenantless = (panel: DashboardStatPanel): DashboardStatPanel => ({
+    ...panel,
+    ignoreScreenFilter: true,
+  });
+  return [
+    ...kpiStrip([
+      ...kpi(ctx, "active-tenants", "activeTenants").map(tenantless),
+      ...kpi(ctx, "active-users", "activeUsers7d", { trend: true }),
+      ...kpi(ctx, "failed-job-runs", "failedJobs24h", { trend: true, negative: true }).map(
+        tenantless,
+      ),
+      ...kpi(ctx, "failed-deliveries", "failedDeliveries24h", { trend: true, negative: true }),
+    ]),
+    ...chart(ctx, "job-runs-by-status", {
+      id: "job-runs-by-status",
+      label: `${I}.chart.jobRunsByStatus`,
+      chart: "stacked-bars",
+      ...HALF,
+      ignoreScreenFilter: true,
+      seriesTones: {
+        completed: "positive",
+        failed: "negative",
+        running: "active",
+        queued: "neutral",
+      },
+    }),
+    ...chart(ctx, "deliveries-by-channel", {
+      id: "deliveries-by-channel",
+      label: `${I}.chart.deliveriesByChannel`,
+      chart: "segment-bars",
+      ...HALF,
+      seriesTones: DELIVERY_SEGMENT_TONES,
+    }),
+    recentFailuresList(
+      JobQueries.list,
+      { status: "failed", sort: "startedAt", sortDirection: "desc", limit: 5 },
+      [
+        { field: "jobName", label: `${I}.col.job` },
+        { field: "startedAt", label: `${I}.col.startedAt`, display: "datetime" as const },
+      ],
+      "full",
+    ),
+  ];
+}
+
+export function tenantOverviewPanels(
+  metrics: readonly MetricDefinition[],
+  options: { readonly includeCapOverview: boolean },
+): readonly DashboardPanelDefinition[] {
+  const ctx = contextFor(metrics, "tenant");
+  return [
+    ...kpiStrip([
+      ...kpi(ctx, "active-users", "activeMembers7d", { trend: true }),
+      ...kpi(ctx, "tenant-job-failures", "failedJobs24h", { trend: true, negative: true }),
+      ...kpi(ctx, "failed-deliveries", "failedDeliveries24h", { trend: true, negative: true }),
+    ]),
+    ...chart(ctx, "deliveries-by-channel", {
+      id: "deliveries-by-channel",
+      label: `${I}.chart.deliveriesByChannel`,
+      chart: "segment-bars",
+      ...HALF,
+      seriesTones: DELIVERY_SEGMENT_TONES,
+    }),
+    ...(options.includeCapOverview
+      ? [
+          {
+            kind: "list" as const,
+            id: "quotas",
+            label: `${I}.list.quotas`,
+            query: CapOverviewQueries.capsUsage,
+            columns: [
+              { field: "label", label: `${I}.col.quota` },
+              { field: "used", label: `${I}.col.used` },
+              { field: "limit", label: `${I}.col.limit` },
+              { field: "fraction", label: `${I}.col.usage`, display: "bar" as const },
+            ],
+            ...HALF,
+            emptyLabel: `${I}.list.quotasEmpty`,
+          },
+        ]
+      : []),
+    ...chart(ctx, "audit-writes", {
+      id: "audit-writes",
+      label: `${I}.chart.auditWrites`,
+      subtitle: `${I}.chart.auditWritesSubtitle`,
+      chart: "stacked-bars",
+      ...HALF,
+    }),
+    recentFailuresList(
+      JobQueries.failures,
+      { limit: 5 },
+      [
+        { field: "jobName", label: `${I}.col.job` },
+        { field: "messageKey", label: `${I}.col.reason` },
+        { field: "failedAt", label: `${I}.col.failedAt`, display: "datetime" as const },
+      ],
+      "half",
+    ),
+  ];
+}

package/packages/bundled-features/src/admin-shell/web/client-plugin.tsx

@@ -0,0 +1,16 @@
+// @runtime client
+import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { ADMIN_SHELL_FEATURE } from "../constants.js";
+import { defaultTranslations } from "./i18n.js";
+
+export type AdminShellClientOptions = {
+  readonly translations?: TranslationsByLocale;
+};
+
+export function adminShellClient(options?: AdminShellClientOptions): ClientFeatureDefinition {
+  return {
+    name: ADMIN_SHELL_FEATURE,
+    translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
+  };
+}

package/packages/bundled-features/src/admin-shell/web/i18n.ts

@@ -0,0 +1,11 @@
+// @runtime client
+// Client pivot of ADMIN_SHELL_I18N — same keys as server r.translations bundle.
+
+import {
+  type TranslationsByLocale,
+  translationsByLocaleFromKeys,
+} from "@cosmicdrift/kumiko-renderer";
+import { ADMIN_SHELL_I18N } from "../i18n.js";
+
+export const defaultTranslations: TranslationsByLocale =
+  translationsByLocaleFromKeys(ADMIN_SHELL_I18N);

package/packages/bundled-features/src/admin-shell/web/index.ts

@@ -0,0 +1,2 @@
+// @runtime client
+export { type AdminShellClientOptions, adminShellClient } from "./client-plugin.js";