@cosmicdrift/kumiko-bundled-features 0.240.0 → 0.242.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.240.0",
+  "version": "0.242.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>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.240.0",
-    "@cosmicdrift/kumiko-framework": "0.240.0",
-    "@cosmicdrift/kumiko-headless": "0.240.0",
-    "@cosmicdrift/kumiko-renderer": "0.240.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.240.0",
-    "@cosmicdrift/kumiko-types": "0.240.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.242.0",
+    "@cosmicdrift/kumiko-framework": "0.242.0",
+    "@cosmicdrift/kumiko-headless": "0.242.0",
+    "@cosmicdrift/kumiko-renderer": "0.242.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.242.0",
+    "@cosmicdrift/kumiko-types": "0.242.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.240.0",
-    "@cosmicdrift/kumiko-locale-es": "0.240.0"
+    "@cosmicdrift/kumiko-locale-de": "0.242.0",
+    "@cosmicdrift/kumiko-locale-es": "0.242.0"
   }
 }

package/src/admin-shell/__tests__/admin-shell-security.integration.test.ts

@@ -39,12 +39,10 @@ import {
   ADMIN_SHELL_FEATURE,
   DEFAULT_PLATFORM_WORKSPACE_ID,
   DEFAULT_TENANT_WORKSPACE_ID,
+  TENANT_OVERVIEW_SCREEN_ID,
 } from "../constants";
 import { createAdminShellFeature } from "../feature";
-import {
-  TENANT_OVERVIEW_ALLOWED_QUERIES,
-  TENANT_OVERVIEW_FORBIDDEN_QUERIES,
-} from "../overview-allowlist";
+import { isOverviewQueryAllowed, TENANT_OVERVIEW_FORBIDDEN_QUERIES } from "../overview-allowlist";
 
 let stack: TestStack;
 let TENANT_ID: TenantId;
@@ -175,9 +173,20 @@ describe("SystemAdmin platform queries", () => {
 });
 
 describe("tenant overview query allowlist", () => {
-  test("static allowlist excludes every forbidden platform query", () => {
-    for (const qn of TENANT_OVERVIEW_FORBIDDEN_QUERIES) {
-      expect(TENANT_OVERVIEW_ALLOWED_QUERIES).not.toContain(qn);
+  // The tenant-overview screen dispatches only the queries baked into its
+  // own dashboard panels (no client-side allowlist gate anymore, fw#2312) —
+  // this checks the actual screen definition against the allowlist instead
+  // of the allowlist against itself.
+  test("tenant-overview screen panels stay inside the allowlist and off the forbidden list", () => {
+    const screen = createAdminShellFeature().screens[TENANT_OVERVIEW_SCREEN_ID];
+    if (screen?.type !== "dashboard")
+      throw new Error("expected tenant-overview to be a dashboard screen");
+    for (const panel of screen.panels) {
+      if (panel.kind !== "stat") throw new Error(`expected stat panel, got ${panel.kind}`);
+      expect(isOverviewQueryAllowed("tenant", panel.query)).toBe(true);
+      expect((TENANT_OVERVIEW_FORBIDDEN_QUERIES as readonly string[]).includes(panel.query)).toBe(
+        false,
+      );
     }
   });
 

package/src/admin-shell/__tests__/overview-allowlist.test.ts

@@ -2,6 +2,8 @@ import { describe, expect, test } from "bun:test";
 import { JobQueries } from "../../jobs/constants";
 import { TenantQueries } from "../../tenant/constants";
 import { UserQueries } from "../../user/constants";
+import { PLATFORM_OVERVIEW_SCREEN_ID, TENANT_OVERVIEW_SCREEN_ID } from "../constants";
+import { createAdminShellFeature } from "../feature";
 import {
   isOverviewQueryAllowed,
   PLATFORM_OVERVIEW_ALLOWED_QUERIES,
@@ -9,6 +11,19 @@ import {
   TENANT_OVERVIEW_FORBIDDEN_QUERIES,
 } from "../overview-allowlist";
 
+// Every screen dispatches only the queries baked into its own panel
+// definitions (no client-side allowlist gate anymore, fw#2312) — the
+// allowlist's regression value now lives in this static cross-check instead
+// of a runtime guard.
+function statPanelQueries(screenId: string): readonly string[] {
+  const screen = createAdminShellFeature().screens[screenId];
+  if (screen?.type !== "dashboard") throw new Error(`expected dashboard screen: ${screenId}`);
+  return screen.panels.map((panel) => {
+    if (panel.kind !== "stat") throw new Error(`expected stat panel on ${screenId}: ${panel.kind}`);
+    return panel.query;
+  });
+}
+
 describe("overview query allowlist", () => {
   test("tenant allowlist excludes platform-only queries", () => {
     for (const forbidden of TENANT_OVERVIEW_FORBIDDEN_QUERIES) {
@@ -41,3 +56,18 @@ describe("overview query allowlist", () => {
     expect(isOverviewQueryAllowed("tenant", UserQueries.list)).toBe(false);
   });
 });
+
+describe("overview screen panels vs allowlist (fw#2312 regression)", () => {
+  test("tenant-overview panels use only allowlisted, never forbidden, queries", () => {
+    for (const query of statPanelQueries(TENANT_OVERVIEW_SCREEN_ID)) {
+      expect(isOverviewQueryAllowed("tenant", query)).toBe(true);
+      expect((TENANT_OVERVIEW_FORBIDDEN_QUERIES as readonly string[]).includes(query)).toBe(false);
+    }
+  });
+
+  test("platform-overview panels use only allowlisted queries", () => {
+    for (const query of statPanelQueries(PLATFORM_OVERVIEW_SCREEN_ID)) {
+      expect(isOverviewQueryAllowed("platform", query)).toBe(true);
+    }
+  });
+});

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

@@ -1,35 +1,43 @@
 import { describe, expect, test } from "bun:test";
-import { access, createRegistry } from "@cosmicdrift/kumiko-framework/engine";
-import { createAuditFeature } from "../../audit/feature";
-import { createConfigFeature } from "../../config/feature";
-import { createJobsFeature } from "../../jobs/feature";
-import { createTenantFeature } from "../../tenant/feature";
-import { tierEngineFeature } from "../../tier-engine/feature";
-import { createUserFeature } from "../../user/feature";
+import { access } from "@cosmicdrift/kumiko-framework/engine";
+import { ConfigQueries } from "../../config/constants";
+import { JobQueries } from "../../jobs/constants";
+import { TenantQueries } from "../../tenant/constants";
+import { UserQueries } from "../../user/constants";
 import { PLATFORM_OVERVIEW_SCREEN_ID, TENANT_OVERVIEW_SCREEN_ID } from "../constants";
 import { createAdminShellFeature } from "../feature";
 
-const features = [
-  createConfigFeature(),
-  createUserFeature(),
-  createTenantFeature(),
-  createAuditFeature(),
-  createJobsFeature(),
-  tierEngineFeature,
-  createAdminShellFeature(),
-];
+const adminShell = createAdminShellFeature();
+
+function statPanelQueries(screenId: string): readonly string[] {
+  const screen = adminShell.screens[screenId];
+  if (screen?.type !== "dashboard") throw new Error(`expected dashboard screen: ${screenId}`);
+  return screen.panels.map((panel) => {
+    if (panel.kind !== "stat") throw new Error(`expected stat panel on ${screenId}: ${panel.kind}`);
+    return panel.query;
+  });
+}
 
 describe("overview screens boot", () => {
-  test("tenant-overview screen is access.admin", () => {
-    const registry = createRegistry(features);
-    const screen = registry.getScreen(`admin-shell:screen:${TENANT_OVERVIEW_SCREEN_ID}`);
+  test("tenant-overview screen is access.admin, dashboard with 3 stat panels", () => {
+    const screen = adminShell.screens[TENANT_OVERVIEW_SCREEN_ID];
     expect(screen?.access).toEqual({ roles: access.admin });
-    expect(screen?.type).toBe("custom");
+    expect(screen?.type).toBe("dashboard");
+    expect(statPanelQueries(TENANT_OVERVIEW_SCREEN_ID)).toEqual([
+      TenantQueries.invitations,
+      TenantQueries.members,
+      ConfigQueries.readiness,
+    ]);
   });
 
-  test("platform-overview screen is SystemAdmin-only", () => {
-    const registry = createRegistry(features);
-    const screen = registry.getScreen(`admin-shell:screen:${PLATFORM_OVERVIEW_SCREEN_ID}`);
+  test("platform-overview screen is SystemAdmin-only, dashboard with 3 stat panels", () => {
+    const screen = adminShell.screens[PLATFORM_OVERVIEW_SCREEN_ID];
     expect(screen?.access).toEqual({ roles: access.systemAdmin });
+    expect(screen?.type).toBe("dashboard");
+    expect(statPanelQueries(PLATFORM_OVERVIEW_SCREEN_ID)).toEqual([
+      TenantQueries.list,
+      UserQueries.list,
+      JobQueries.list,
+    ]);
   });
 });

package/src/admin-shell/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "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",

package/src/admin-shell/feature.ts

@@ -7,6 +7,10 @@ import {
   defineFeature,
   type FeatureDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { ConfigQueries } from "../config";
+import { JobQueries } from "../jobs";
+import { TenantQueries } from "../tenant";
+import { UserQueries } from "../user";
 import {
   ADMIN_SHELL_FEATURE,
   DEFAULT_PLATFORM_WORKSPACE_ID,
@@ -71,14 +75,40 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
       ...(includeTierAdmin ? (["admin-shell:nav:tier-admin"] as const) : []),
     ];
 
-    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
     r.screen({
       id: TENANT_OVERVIEW_SCREEN_ID,
-      type: "custom",
-      renderer: { react: { __component: "TenantOverviewScreen" } },
+      type: "dashboard",
       access: { roles: access.admin },
       description:
         "Landing page of the tenant-admin workspace, showing pending invitation, member and missing-config counts for the caller's own tenant so an operator sees what needs attention there.",
+      panels: [
+        {
+          kind: "stat",
+          id: "pending-invitations",
+          label: "admin-shell:overview.pendingInvitations",
+          query: TenantQueries.invitations,
+          // tenant:query:invitations returns a bare array, not a paged
+          // envelope — "length" reads record["length"], i.e. the array's
+          // own .length. Not a typo.
+          valueField: "length",
+        },
+        {
+          kind: "stat",
+          id: "members",
+          label: "admin-shell:overview.members",
+          query: TenantQueries.members,
+          // Same array-shaped response as invitations above.
+          valueField: "length",
+        },
+        {
+          kind: "stat",
+          id: "missing-config",
+          label: "admin-shell:overview.missingConfig",
+          query: ConfigQueries.readiness,
+          valueField: "missingCount",
+          toneField: "missingTone",
+        },
+      ],
     });
     r.nav({
       id: "tenant-overview",
@@ -88,14 +118,38 @@ export function createAdminShellFeature(options: CreateAdminShellOptions = {}):
       order: 1,
     });
 
-    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
     r.screen({
       id: PLATFORM_OVERVIEW_SCREEN_ID,
-      type: "custom",
-      renderer: { react: { __component: "PlatformOverviewScreen" } },
+      type: "dashboard",
       access: { roles: access.systemAdmin },
       description:
         "Landing page of the platform-admin workspace, showing installation-wide tenant, user and failed-job counts so a system admin sees the health of the whole deployment at a glance.",
+      panels: [
+        {
+          kind: "stat",
+          id: "tenants",
+          label: "admin-shell:overview.tenants",
+          query: TenantQueries.list,
+          params: { totalCount: true },
+          valueField: "total",
+        },
+        {
+          kind: "stat",
+          id: "users",
+          label: "admin-shell:overview.users",
+          query: UserQueries.list,
+          params: { totalCount: true },
+          valueField: "total",
+        },
+        {
+          kind: "stat",
+          id: "failed-jobs",
+          label: "admin-shell:overview.failedJobs",
+          query: JobQueries.list,
+          params: { status: "failed", totalCount: true },
+          valueField: "total",
+        },
+      ],
     });
     r.nav({
       id: "platform-overview",

package/src/admin-shell/i18n.ts

@@ -15,9 +15,6 @@ export const ADMIN_SHELL_I18N: Readonly<Record<string, LocalizedString>> = {
   "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…" },
   "admin-shell:overview.pendingInvitations": {
     en: "Pending invitations",
   },
@@ -25,11 +22,7 @@ export const ADMIN_SHELL_I18N: Readonly<Record<string, LocalizedString>> = {
   "admin-shell:overview.missingConfig": {
     en: "Missing configuration",
   },
-  "admin-shell:overview.missingConfigHint": {
-    en: "Check required settings",
-  },
   "admin-shell:overview.tenants": { en: "Tenants" },
   "admin-shell:overview.users": { en: "Users" },
   "admin-shell:overview.failedJobs": { en: "Failed jobs" },
-  "admin-shell:overview.failedJobsHint": { en: "Review job runs" },
 };

package/src/admin-shell/web/client-plugin.tsx

@@ -1,14 +1,8 @@
 // @runtime client
 import { mergeTranslations, type TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
-import {
-  ADMIN_SHELL_FEATURE,
-  PLATFORM_OVERVIEW_SCREEN_ID,
-  TENANT_OVERVIEW_SCREEN_ID,
-} from "../constants";
+import { ADMIN_SHELL_FEATURE } from "../constants";
 import { defaultTranslations } from "./i18n";
-import { PlatformOverviewScreen } from "./platform-overview-screen";
-import { TenantOverviewScreen } from "./tenant-overview-screen";
 
 export type AdminShellClientOptions = {
   readonly translations?: TranslationsByLocale;
@@ -18,9 +12,5 @@ export function adminShellClient(options?: AdminShellClientOptions): ClientFeatu
   return {
     name: ADMIN_SHELL_FEATURE,
     translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
-    components: {
-      [TENANT_OVERVIEW_SCREEN_ID]: TenantOverviewScreen,
-      [PLATFORM_OVERVIEW_SCREEN_ID]: PlatformOverviewScreen,
-    },
   };
 }

package/src/agent-tools/__tests__/agent-doc-lint.test.ts

@@ -128,6 +128,46 @@ describe("findAgentDocGaps", () => {
     expect(findAgentDocGaps([feature])).toHaveLength(0);
   });
 
+  test("R2: custom screen with agent.expose:false opt-out -> no gap", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.screen({
+        id: "sysadmin-secrets",
+        type: "custom",
+        renderer: { react: "stub" },
+        agent: { expose: false },
+      });
+    });
+
+    expect(findAgentDocGaps([feature])).toHaveLength(0);
+  });
+
+  test("R2: custom screen with agent.expose:true but no description -> still a gap", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.screen({
+        id: "widget-editor",
+        type: "custom",
+        renderer: { react: "stub" },
+        agent: { expose: true },
+      });
+    });
+
+    const gaps = findAgentDocGaps([feature]);
+    expect(gaps).toHaveLength(1);
+    expect(gaps[0]?.qn).toBe("doc-gap-demo:screen:widget-editor");
+    expect(gaps[0]?.kind).toBe(AgentDocGapKinds.customScreenWithoutDescription);
+  });
+
+  test("R2: the custom-screen gap message names both ways out", () => {
+    const feature = defineFeature("doc-gap-demo", (r) => {
+      r.screen({ id: "widget-editor", type: "custom", renderer: { react: "stub" } });
+    });
+
+    const gaps = findAgentDocGaps([feature]);
+    expect(gaps).toHaveLength(1);
+    expect(formatAgentDocGap(gaps[0]!)).toContain("agent: { expose: false }");
+    expect(formatAgentDocGap(gaps[0]!)).toContain("`description`");
+  });
+
   test("R2: non-custom screen without description -> no gap (only custom screens are linted)", () => {
     const feature = defineFeature("doc-gap-demo", (r) => {
       r.entity("widget", { fields: {}, description: "A widget." });

package/src/agent-tools/__tests__/agent-manifest.test.ts

@@ -183,4 +183,40 @@ describe("buildAgentManifest", () => {
     const entityNames = manifestA.entities.map((e) => e.name);
     expect(entityNames).toEqual([...entityNames].sort());
   });
+
+  test("a nav pointing at an opted-out screen is dropped too, so the screen id never leaks via navs", () => {
+    const feature = defineFeature("nav-leak-test", (r) => {
+      r.screen({
+        id: "sysadmin-secrets",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Webhook secrets.",
+        agent: { expose: false },
+      });
+      r.screen({
+        id: "public-board",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Public board.",
+      });
+      r.nav({
+        id: "sysadmin-secrets",
+        label: "nav-leak-test:nav:sysadmin-secrets",
+        screen: "nav-leak-test:screen:sysadmin-secrets",
+      });
+      r.nav({
+        id: "public-board",
+        label: "nav-leak-test:nav:public-board",
+        screen: "nav-leak-test:screen:public-board",
+      });
+    });
+
+    const manifest = buildAgentManifest(createRegistry([feature]), {
+      locale: "en",
+      roles: ["admin"],
+    });
+
+    expect(manifest.navs.map((n) => n.screen)).toEqual(["nav-leak-test:screen:public-board"]);
+    expect(manifest.screens.map((s) => s.id)).toEqual(["nav-leak-test:screen:public-board"]);
+  });
 });

package/src/agent-tools/__tests__/tool-catalog.test.ts

@@ -303,6 +303,57 @@ describe("buildToolCatalog — client tools", () => {
     expect(descriptor.screenIds.has("catalog-test:screen:widget-approve-form")).toBe(true);
   });
 
+  test("a screen with agent.expose:false is absent from the navigate enum and from the manifest", () => {
+    const feature = defineFeature("exposure-test", (r) => {
+      r.screen({
+        id: "sysadmin-secrets",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Webhook secrets.",
+        agent: { expose: false },
+      });
+      r.screen({
+        id: "public-board",
+        type: "custom",
+        renderer: { react: "stub" },
+        description: "Public board.",
+      });
+    });
+    const registry = createRegistry([feature]);
+    const manifest = buildAgentManifest(registry, { locale: "en", roles: ["Admin"] });
+    const catalog = buildToolCatalog(registry, manifest, { mode: "edit" });
+
+    expect(manifest.screens.map((s) => s.id)).toContain("exposure-test:screen:public-board");
+    expect(manifest.screens.map((s) => s.id)).not.toContain(
+      "exposure-test:screen:sysadmin-secrets",
+    );
+
+    const descriptor = catalog.dispatchTable.get("navigate");
+    if (descriptor?.kind !== "client" || descriptor.op !== "navigate")
+      throw new Error("wrong kind");
+    expect(descriptor.screenIds.has("exposure-test:screen:sysadmin-secrets")).toBe(false);
+    expect(descriptor.screenIds.has("exposure-test:screen:public-board")).toBe(true);
+
+    const navTool = catalog.tools.find((t) => t.name === "navigate");
+    const schema = navTool?.inputSchema ?? {};
+    const properties = isRecord(schema["properties"]) ? schema["properties"] : {};
+    const screenIdSchema = isRecord(properties["screenId"]) ? properties["screenId"] : {};
+    const enumValues = Array.isArray(screenIdSchema["enum"]) ? screenIdSchema["enum"] : [];
+    expect(enumValues).toContain("exposure-test:screen:public-board");
+    expect(enumValues).not.toContain("exposure-test:screen:sysadmin-secrets");
+  });
+
+  test("a screen without an agent slot stays in the navigate enum", () => {
+    const catalog = buildCatalog(ADMIN);
+    const descriptor = catalog.dispatchTable.get("navigate");
+    if (descriptor?.kind !== "client" || descriptor.op !== "navigate")
+      throw new Error("wrong kind");
+    // None of catalog-test's screens carry a description either — this is the
+    // regression guard against a screen without an `agent` slot silently
+    // fail-closing (the way a handler without a description would).
+    expect(descriptor.screenIds.has("catalog-test:screen:widget-detail")).toBe(true);
+  });
+
   test("open_form maps the actionForm handler and the entityEdit create/update handlers", () => {
     const catalog = buildCatalog(ADMIN);
     const descriptor = catalog.dispatchTable.get("open_form");

package/src/agent-tools/agent-doc-lint.ts

@@ -3,7 +3,13 @@ import type {
   QueryHandlerDef,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { QnTypes, qn, resolveAgentExposure, toKebab } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  isAgentVisibleScreen,
+  QnTypes,
+  qn,
+  resolveAgentExposure,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export const AgentDocGapKinds = {
   handlerWithoutDescription: "handler-without-description",
@@ -56,13 +62,18 @@ function handlerDocGaps(
 function screenDocGaps(feature: FeatureDefinition): readonly AgentDocGap[] {
   const gaps: AgentDocGap[] = [];
   for (const [shortId, screen] of Object.entries(feature.screens ?? {})) {
-    if (screen.type !== CUSTOM_SCREEN_TYPE || screen.description !== undefined) continue;
+    if (
+      screen.type !== CUSTOM_SCREEN_TYPE ||
+      screen.description !== undefined ||
+      !isAgentVisibleScreen(screen)
+    )
+      continue;
     gaps.push({
       qn: qn(toKebab(feature.name), QnTypes.screen, toKebab(shortId)),
       feature: feature.name,
       kind: AgentDocGapKinds.customScreenWithoutDescription,
       message:
-        "This custom screen has no description, so the AI agent can't tell what it's for — set `description` to explain it.",
+        "This custom screen has no description, so the AI agent can't tell what it's for — set `description` to explain it, or `agent: { expose: false }` to hide it from the agent deliberately.",
     });
   }
   return gaps;

package/src/agent-tools/agent-manifest.ts

@@ -10,7 +10,11 @@ import type {
   WorkspaceDefinition,
   WriteHandlerDef,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { hasAccess, resolveAgentExposure } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  hasAccess,
+  isAgentVisibleScreen,
+  resolveAgentExposure,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import type {
   AgentManifest,
@@ -204,10 +208,15 @@ function buildNavs(
   workspaces: ReadonlyMap<string, WorkspaceDefinition>,
   translations: TranslationKeys,
   roles: readonly string[],
+  screens: ReadonlyMap<string, ScreenDefinition>,
 ): readonly AgentManifestNav[] {
   const result: AgentManifestNav[] = [];
   for (const [, nav] of navs) {
     if (!uiVisible(nav.access, roles)) continue;
+    // A nav pointing at an opted-out screen would leak its id and label back
+    // into the manifest the screen was just removed from.
+    const target = nav.screen !== undefined ? screens.get(nav.screen) : undefined;
+    if (target !== undefined && !isAgentVisibleScreen(target)) continue;
     const visibleWorkspaces = visibleWorkspaceIds(nav.workspaces, workspaces, roles);
     const hasWorkspaces = nav.workspaces !== undefined && nav.workspaces.length > 0;
     if (hasWorkspaces && visibleWorkspaces.length === 0) continue;
@@ -239,6 +248,9 @@ function buildScreens(
   const result: AgentManifestScreen[] = [];
 
   for (const [, screen] of screens) {
+    // An opted-out screen must not reach the manifest at all — the tool catalog
+    // builds `navigate`'s screen-id enum straight from `manifest.screens`.
+    if (!isAgentVisibleScreen(screen)) continue;
     const matchingNavs = allNavs.filter((nav) => nav.screen === screen.id);
     const accessibleNavs = matchingNavs.filter((nav) => uiVisible(nav.access, roles));
 
@@ -312,8 +324,9 @@ export function buildAgentManifest(
     roles,
     (qn) => registry.getHandlerEntity(qn),
   );
-  const navs = buildNavs(navMap, workspaceMap, translations, roles);
-  const screens = buildScreens(registry.getAllScreens(), navMap, workspaceMap, translations, roles);
+  const screenMap = registry.getAllScreens();
+  const navs = buildNavs(navMap, workspaceMap, translations, roles, screenMap);
+  const screens = buildScreens(screenMap, navMap, workspaceMap, translations, roles);
   const workspaces = buildWorkspaces(workspaceMap, translations, roles);
 
   return {

package/src/agent-tools/feature.ts

@@ -6,7 +6,7 @@ export const AGENT_TOOLS_FEATURE_NAME = "agent-tools";
 export function createAgentToolsFeature(): FeatureDefinition {
   return defineFeature(AGENT_TOOLS_FEATURE_NAME, (r) => {
     r.describe(
-      "Builds a tool catalog and an agent manifest from the mounted registry so an LLM agent can call handlers and understand the app's shape. A handler, custom screen, or entity without a `description` stays invisible to the agent by construction (see `resolveAgentExposure`) — this feature surfaces those gaps at boot and via `kumiko agent lint` so an app author notices before an agent silently can't see a feature.",
+      "Builds a tool catalog and an agent manifest from the mounted registry so an LLM agent can call handlers and understand the app's shape. A handler or entity without a `description` stays invisible to the agent by construction (see `resolveAgentExposure`), while a screen stays visible unless it opts out with `agent: { expose: false }` (see `isAgentVisibleScreen`) — this feature surfaces the resulting gaps at boot and via `kumiko agent lint` so an app author notices before an agent silently can't see a feature.",
     );
     r.uiHints({
       displayLabel: "AI Agent Tools",