feat: add Dashboard navigation as presentation configuration

Phase 6D pass 1. The shell's navigation was a flat list of module ids, which
is not a usable experience — and the obvious fix carries an obvious trap.
Letting a module declare its folder, or modelling "Media" as something
Livestream and Video belong to, turns a rendering preference into
architecture: a folder becomes an owner, membership starts to look like a
dependency, and the flat module graph acquires a hierarchy nobody decided on.

So the rule comes first: a Dashboard group is a label on a rendering bucket.
No manifest, no version, no artifact, no API, no lifecycle; nothing depends on
it. Livestream depends on Video because it calls Video's functionality, and
that orders startup. Livestream is shown under Media, and that orders nothing.
No parent module, child module, owning module, or group-derived dependency
appears anywhere in the contracts.

No manifest change and no version 5. `manifest.name` has been required since
version 1 and already is the module's product identity, so the shell renders
"Livestream" instead of `livestream` with nothing added. `suggestedGroup` is
deliberately deferred rather than shipped: it would force a hard
manifest-version cutover for a hint, and its only correct semantics needs
initialization logic that risks a suggestion overwriting an administrator's
decision. Defaulting and ownership are different things.

Two Core tables (migration 0003) hold groups and placements — server-side,
because a church configures its Dashboard rather than one browser;
platform-global, because no organization model exists to scope them to.
`group_id` is `on delete set null`, so deleting a group ungroups its modules
and a dangling reference is impossible. `module_id` carries no foreign key,
because modules are packages rather than rows, so a placement for an
uninstalled module is retained and restores its position on reinstall.

`resolveDashboardNavigation` is a pure function of configuration plus the
mountable set: an unplaced module is ungrouped and visible with no
initialization write, an absent module renders nothing, empty groups are kept,
and ordering is total with the module id as final tie-break.

`GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of
the host-neutral module UI inventory rather than merged into it — each generic
descriptor is embedded untouched, so a standalone host never inherits Dashboard
semantics. Reading needs the permission the inventory already needs; organizing
needs the new platform permission `core.dashboard.navigation.manage` through a
narrow, idempotent, closed-validation mutation contract. No editor UI.

The flatness rule is executable: a test discovers real fixtures with a genuine
dependency, arranges them four ways including both in one folder and the
dependency inverted in presentation, and asserts discovery order, dependency
declarations, and the module set stay byte-identical. The end-to-end test
organizes a real installation through the real API, mounts a module from inside
a group, moves it, and asserts the navigation entry is byte-identical across the
move and still mounts the same artifact.

The shell's client for the generic inventory became dead code and was removed
rather than kept speculatively; the endpoint itself is unchanged.

Co-Authored-By: Claude Opus 5 <[email protected]>

apps/api/tests/api-http.integration.ts

@@ -194,6 +194,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0000_identity_core_tables",
       "core:0001_authorization_core_tables",
       "core:0002_authorization_integrity",
+      "core:0003_dashboard_navigation_tables",
     ]);
     expect(aggregate.migrations[0]?.checksum).toBe(
       "f8f2086ef06f7a6943e8ffc4350bb010b37aed04c0a72030d2b153c986b1325f",
@@ -2158,9 +2159,9 @@ describe.sequential("live API — installed module permission end-to-end", () =>
     expect(moduleCheck).toMatchObject({ status: "pass" });
     expect(moduleCheck?.details).toEqual(["calendar 0.1.0"]);
     expect(permissionsCheck).toMatchObject({
-      // Core's own two (`core.authorization.grants.manage`, `core.modules.ui.read`) plus the
-      // fixture module's one.
-      details: ["3 permissions registered"],
+      // Core's own three (`core.authorization.grants.manage`, `core.modules.ui.read`,
+      // `core.dashboard.navigation.manage`) plus the fixture module's one.
+      details: ["4 permissions registered"],
       status: "pass",
     });
     // Doctor and permission composition read only the manifest — the fixture's register/start

apps/api/tests/app.test.ts

@@ -17,6 +17,7 @@ import {
 } from "@ekklesia/core/modules";
 import { IdentityRuntimeError } from "@ekklesia/core/identity";
 import { describe, expect, it, vi } from "vitest";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { createApiApp, type CreateApiAppAuthorizationOptions } from "../src/app.js";
 import { AUTH_REQUEST_MAX_BODY_BYTES } from "../src/body-limits.js";
 
@@ -87,6 +88,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime,
@@ -105,6 +107,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime,
@@ -124,6 +127,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime,
@@ -145,6 +149,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime,
@@ -168,6 +173,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime,
@@ -191,6 +197,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime,
@@ -211,6 +218,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime,
@@ -233,6 +241,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime,
@@ -252,6 +261,7 @@ describe("Ekklesia API Hono application", () => {
       const app = createApiApp({
         moduleRoutes: Object.freeze([]),
         moduleUi: emptyModuleUiPublication(),
+        dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
         runtime,
@@ -273,6 +283,7 @@ describe("Ekklesia API Hono application", () => {
       const app = createApiApp({
         moduleRoutes: Object.freeze([]),
         moduleUi: emptyModuleUiPublication(),
+        dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
         runtime,
@@ -301,6 +312,7 @@ describe("Ekklesia API Hono application", () => {
       const app = createApiApp({
         moduleRoutes: Object.freeze([]),
         moduleUi: emptyModuleUiPublication(),
+        dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
         runtime,
@@ -330,6 +342,7 @@ describe("Ekklesia API Hono application", () => {
       const app = createApiApp({
         moduleRoutes: Object.freeze([]),
         moduleUi: emptyModuleUiPublication(),
+        dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
         runtime,
@@ -364,6 +377,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime: fakeRuntime(),
@@ -380,6 +394,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime: fakeRuntime(),
@@ -398,6 +413,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime: fakeRuntime(),
@@ -415,6 +431,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime: fakeRuntime(),
@@ -430,6 +447,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime: fakeRuntime(),
@@ -452,6 +470,7 @@ describe("Ekklesia API Hono application", () => {
     const app = createApiApp({
       moduleRoutes: Object.freeze([]),
       moduleUi: emptyModuleUiPublication(),
+      dashboard: createInMemoryDashboardStore(),
       moduleServices: fakeModuleServices(),
       authorization: fakeAuthorization({}),
       runtime: fakeRuntime(),
@@ -477,6 +496,7 @@ describe("Ekklesia API Hono application", () => {
       const app = createApiApp({
         moduleRoutes: Object.freeze([]),
         moduleUi: emptyModuleUiPublication(),
+        dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({ evaluator: { authorize: evaluatorAuthorize } }),
         runtime: fakeRuntime(),
@@ -505,6 +525,7 @@ describe("Ekklesia API Hono application", () => {
       const app = createApiApp({
         moduleRoutes: Object.freeze([]),
         moduleUi: emptyModuleUiPublication(),
+        dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({
           evaluator: { authorize: evaluatorAuthorize },
@@ -524,6 +545,7 @@ describe("Ekklesia API Hono application", () => {
       const app = createApiApp({
         moduleRoutes: Object.freeze([]),
         moduleUi: emptyModuleUiPublication(),
+        dashboard: createInMemoryDashboardStore(),
         moduleServices: fakeModuleServices(),
         authorization: fakeAuthorization({}),
         runtime: fakeRuntime(),

apps/api/tests/dashboard-routes.test.ts

@@ -0,0 +1,621 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import {
+  ANONYMOUS_PRINCIPAL,
+  createAuthenticatedPrincipal,
+  type EkklesiaPrincipal,
+  type ModuleDatabase,
+  type ModuleRuntimeServices,
+  parseEkklesiaUserId,
+} from "@ekklesia/contracts";
+import {
+  type AuthorizationStore,
+  createAuthorizationEvaluator,
+} from "@ekklesia/core/authorization";
+import type { DashboardConfiguration } from "@ekklesia/core/dashboard";
+import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
+import {
+  composePlatformPermissionRegistry,
+  createModuleUiPublicationRegistry,
+  discoverModules,
+} from "@ekklesia/core/modules";
+import type { Hono } from "hono";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApiApp } from "../src/app.js";
+import { DASHBOARD_NAVIGATION_PATH } from "../src/dashboard-routes.js";
+import { MODULE_UI_INVENTORY_PATH } from "../src/module-ui-inventory.js";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
+
+const trustedOrigin = "https://dashboard.example.test";
+const untrustedOrigin = "https://evil.example.test";
+const viewerId = parseEkklesiaUserId("33333333-3333-4333-8333-333333333333");
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    temporaryDirectories
+      .splice(0)
+      .map((directory) => rm(directory, { force: true, recursive: true })),
+  );
+});
+
+interface ModuleFixture {
+  readonly id: string;
+  readonly name: string;
+  readonly withUi?: boolean;
+}
+
+async function createModule(modulesDirectory: string, fixture: ModuleFixture): Promise<void> {
+  const moduleDirectory = path.join(modulesDirectory, fixture.id);
+  await mkdir(path.join(moduleDirectory, "dist/server"), { recursive: true });
+  await writeFile(
+    path.join(moduleDirectory, "package.json"),
+    JSON.stringify({
+      ekklesia: { layer: "module" },
+      name: `@test/module-${fixture.id}`,
+      type: "module",
+      version: "1.0.0",
+    }),
+  );
+  await writeFile(
+    path.join(moduleDirectory, "ekklesia.module.json"),
+    JSON.stringify({
+      compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
+      entrypoints: {
+        server: "./dist/server/index.js",
+        ...(fixture.withUi === false ? {} : { ui: "./dist/ui/index.js" }),
+      },
+      id: fixture.id,
+      manifestVersion: 4,
+      name: fixture.name,
+      version: "1.0.0",
+    }),
+  );
+  await writeFile(
+    path.join(moduleDirectory, "dist/server/index.js"),
+    `export default { id: ${JSON.stringify(fixture.id)}, version: "1.0.0" };`,
+  );
+  if (fixture.withUi !== false) {
+    await mkdir(path.join(moduleDirectory, "dist/ui"), { recursive: true });
+    await writeFile(
+      path.join(moduleDirectory, "dist/ui/index.js"),
+      `export default { id: ${JSON.stringify(fixture.id)}, version: "1.0.0", mount() {} };\n`,
+    );
+  }
+}
+
+interface InstallOptions {
+  readonly fixtures?: readonly ModuleFixture[];
+  readonly principal?: EkklesiaPrincipal;
+  readonly platformOwner?: boolean;
+  readonly configuration?: Partial<DashboardConfiguration>;
+}
+
+const defaultFixtures: readonly ModuleFixture[] = [
+  { id: "video", name: "Video" },
+  { id: "livestream", name: "Livestream" },
+  { id: "calendar", name: "Calendar" },
+];
+
+async function install(options: InstallOptions = {}): Promise<{ app: Hono }> {
+  const modulesDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-dashboard-routes-"));
+  temporaryDirectories.push(modulesDirectory);
+  for (const fixture of options.fixtures ?? defaultFixtures) {
+    await createModule(modulesDirectory, fixture);
+  }
+  const modules = await discoverModules({
+    moduleSdkVersion: "0.1.0",
+    modulesDirectory,
+    platformVersion: "0.1.0",
+  });
+
+  const evaluator = createAuthorizationEvaluator({
+    grants: { hasActiveGrant: async () => false },
+    platformOwners: { isPlatformOwner: async () => options.platformOwner === true },
+  });
+  const runtime: EkklesiaIdentityRuntime = {
+    handleAuthRequest: vi.fn().mockResolvedValue(new Response(null, { status: 200 })),
+    resolvePrincipal: vi.fn().mockResolvedValue(options.principal ?? ANONYMOUS_PRINCIPAL),
+  };
+  const store = {
+    createGrant: vi.fn(),
+    grantPlatformOwner: vi.fn(),
+    hasActiveGrant: vi.fn().mockResolvedValue(false),
+    isPlatformOwner: vi.fn().mockResolvedValue(false),
+    listGrantsForUser: vi.fn().mockResolvedValue({ grants: [] }),
+    revokeGrant: vi.fn(),
+    revokePlatformOwner: vi.fn(),
+  } as unknown as AuthorizationStore;
+
+  const app = createApiApp({
+    authorization: { evaluator, registry: composePlatformPermissionRegistry(modules), store },
+    dashboard: createInMemoryDashboardStore(options.configuration ?? {}),
+    moduleRoutes: Object.freeze([]),
+    moduleServices: Object.freeze({
+      database: Object.freeze({}) as unknown as ModuleDatabase,
+    }) as ModuleRuntimeServices,
+    moduleUi: createModuleUiPublicationRegistry(modules),
+    runtime,
+    trustedOrigins: [trustedOrigin],
+  });
+
+  return { app };
+}
+
+function signedIn(): EkklesiaPrincipal {
+  return createAuthenticatedPrincipal(viewerId);
+}
+
+interface NavigationEntry {
+  readonly name: string;
+  readonly module: {
+    readonly id: string;
+    readonly version: string;
+    readonly ui: { readonly url: string };
+    readonly api: { readonly baseUrl: string };
+    readonly permissions: readonly string[];
+  };
+}
+
+interface NavigationBody {
+  readonly groups: ReadonlyArray<{
+    readonly id: string;
+    readonly label: string;
+    readonly order: number;
+    readonly modules: readonly NavigationEntry[];
+  }>;
+  readonly ungrouped: readonly NavigationEntry[];
+}
+
+async function navigationOf(app: Hono): Promise<NavigationBody> {
+  const response = await app.request(DASHBOARD_NAVIGATION_PATH);
+  expect(response.status).toBe(200);
+  return (await response.json()) as NavigationBody;
+}
+
+/** An administrator: a platform owner, who passes the evaluator's owner bypass for the restricted
+ * manage permission exactly as in production. */
+async function administrator(configuration: Partial<DashboardConfiguration> = {}) {
+  return install({ configuration, platformOwner: true, principal: signedIn() });
+}
+
+function mutate(app: Hono, method: "PUT" | "DELETE", url: string, body?: unknown) {
+  return app.request(url, {
+    ...(body === undefined
+      ? {}
+      : { body: JSON.stringify(body), headers: { "content-type": "application/json" } }),
+    headers: {
+      origin: trustedOrigin,
+      ...(body === undefined ? {} : { "content-type": "application/json" }),
+    },
+    method,
+  });
+}
+
+describe("Dashboard navigation — reading", () => {
+  it("shows every mountable module as ungrouped when nothing is configured", async () => {
+    const { app } = await install({ principal: signedIn() });
+
+    const navigation = await navigationOf(app);
+
+    expect(navigation.groups).toEqual([]);
+    // A fresh installation is immediately usable: no initialization write, no manual database edit.
+    expect(navigation.ungrouped.map((entry) => entry.name)).toEqual([
+      "Calendar",
+      "Livestream",
+      "Video",
+    ]);
+  });
+
+  it("renders the module's own manifest name, never its id", async () => {
+    const { app } = await install({ principal: signedIn() });
+
+    const navigation = await navigationOf(app);
+
+    expect(navigation.ungrouped.map((entry) => entry.name)).not.toContain("livestream");
+    expect(navigation.ungrouped.find((entry) => entry.module.id === "livestream")?.name).toBe(
+      "Livestream",
+    );
+  });
+
+  it("groups and orders exactly as the stored configuration says", async () => {
+    const { app } = await install({
+      configuration: {
+        groups: [
+          { id: "planning", label: "Planning", sortOrder: 20 },
+          { id: "media", label: "Media", sortOrder: 10 },
+        ],
+        placements: [
+          { groupId: "media", moduleId: "livestream", sortOrder: 20 },
+          { groupId: "media", moduleId: "video", sortOrder: 10 },
+          { groupId: "planning", moduleId: "calendar", sortOrder: 10 },
+        ],
+      },
+      principal: signedIn(),
+    });
+
+    const navigation = await navigationOf(app);
+
+    expect(
+      navigation.groups.map((group) => [group.label, group.modules.map((entry) => entry.name)]),
+    ).toEqual([
+      ["Media", ["Video", "Livestream"]],
+      ["Planning", ["Calendar"]],
+    ]);
+    expect(navigation.ungrouped).toEqual([]);
+  });
+
+  it("embeds the generic mount descriptor unchanged inside each entry", async () => {
+    const { app } = await install({ principal: signedIn() });
+
+    const navigation = await navigationOf(app);
+    const livestream = navigation.ungrouped.find((entry) => entry.module.id === "livestream");
+
+    // Presentation wraps the host-neutral descriptor; it never rewrites it.
+    expect(livestream?.module).toEqual({
+      api: { baseUrl: "/api/v1/modules/livestream" },
+      id: "livestream",
+      permissions: [],
+      ui: { url: "/api/v1/module-ui/livestream/1.0.0" },
+      version: "1.0.0",
+    });
+    expect(Object.keys(livestream ?? {}).sort()).toEqual(["module", "name"]);
+  });
+
+  it("agrees exactly with the generic inventory about what is mountable", async () => {
+    const { app } = await install({
+      configuration: {
+        groups: [{ id: "media", label: "Media", sortOrder: 10 }],
+        placements: [{ groupId: "media", moduleId: "video", sortOrder: 10 }],
+      },
+      principal: signedIn(),
+    });
+
+    const navigation = await navigationOf(app);
+    const inventory = (await (await app.request(MODULE_UI_INVENTORY_PATH)).json()) as {
+      modules: ReadonlyArray<{ id: string }>;
+    };
+
+    const navigationModules = [
+      ...navigation.groups.flatMap((group) => group.modules),
+      ...navigation.ungrouped,
+    ].map((entry) => entry.module);
+    // Both derive from one publication registry through one shared description, so they cannot
+    // disagree about what exists or about any URL.
+    expect(navigationModules.map((module) => module.id).sort()).toEqual(
+      inventory.modules.map((module) => module.id).sort(),
+    );
+  });
+
+  it("keeps the generic inventory free of presentation metadata", async () => {
+    const { app } = await install({ principal: signedIn() });
+
+    const body = await (await app.request(MODULE_UI_INVENTORY_PATH)).text();
+
+    // The host-neutral contract a standalone host consumes must not learn Ekklesia has folders or
+    // display names. That layering is the whole reason navigation is a separate route.
+    for (const field of ["name", "label", "group", "order", "ungrouped"]) {
+      expect(body, field).not.toContain(`"${field}"`);
+    }
+  });
+
+  it("omits a module that is no longer installed, without breaking navigation", async () => {
+    const { app } = await install({
+      configuration: {
+        groups: [{ id: "media", label: "Media", sortOrder: 10 }],
+        placements: [
+          { groupId: "media", moduleId: "video", sortOrder: 10 },
+          { groupId: "media", moduleId: "removed-module", sortOrder: 20 },
+        ],
+      },
+      fixtures: [{ id: "video", name: "Video" }],
+      principal: signedIn(),
+    });
+
+    const navigation = await navigationOf(app);
+
+    expect(navigation.groups[0]?.modules.map((entry) => entry.module.id)).toEqual(["video"]);
+    expect(JSON.stringify(navigation)).not.toContain("removed-module");
+  });
+
+  it("keeps a newly installed module visible alongside an existing arrangement", async () => {
+    const { app } = await install({
+      configuration: {
+        groups: [{ id: "media", label: "Media", sortOrder: 10 }],
+        placements: [{ groupId: "media", moduleId: "video", sortOrder: 10 }],
+      },
+      principal: signedIn(),
+    });
+
+    const navigation = await navigationOf(app);
+
+    expect(navigation.groups[0]?.modules.map((entry) => entry.name)).toEqual(["Video"]);
+    // Calendar and Livestream were never configured and are still reachable.
+    expect(navigation.ungrouped.map((entry) => entry.name)).toEqual(["Calendar", "Livestream"]);
+  });
+
+  it("excludes a module that ships no UI, exactly like the inventory does", async () => {
+    const { app } = await install({
+      fixtures: [
+        { id: "video", name: "Video" },
+        { id: "roster", name: "Roster", withUi: false },
+      ],
+      principal: signedIn(),
+    });
+
+    const navigation = await navigationOf(app);
+
+    expect(JSON.stringify(navigation)).not.toContain("Roster");
+  });
+
+  it("leaks no filesystem path, package root, or manifest internal", async () => {
+    const { app } = await install({ principal: signedIn() });
+
+    const body = await (await app.request(DASHBOARD_NAVIGATION_PATH)).text();
+
+    expect(body).not.toContain(tmpdir());
+    expect(body).not.toContain("dist");
+    expect(body).not.toContain("@test/module-");
+    expect(body).not.toContain("ekklesia.module.json");
+    expect(body).not.toContain("entrypoints");
+    expect(body).not.toContain("manifestVersion");
+  });
+
+  it("is per-principal, uncached, and refused to anonymous callers", async () => {
+    const { app: anonymous } = await install();
+    const { app } = await install({ principal: signedIn() });
+
+    const denied = await anonymous.request(DASHBOARD_NAVIGATION_PATH);
+    const allowed = await app.request(DASHBOARD_NAVIGATION_PATH, {
+      headers: { origin: trustedOrigin },
+    });
+
+    expect(denied.status).toBe(403);
+    expect(await denied.text()).not.toContain("Livestream");
+    expect(allowed.headers.get("cache-control")).toBe("no-store");
+    const vary = allowed.headers.get("vary")?.toLowerCase() ?? "";
+    expect(vary).toContain("origin");
+    expect(vary).toContain("cookie");
+  });
+});
+
+describe("Dashboard navigation — organizing", () => {
+  it("creates a group and places a module, and both persist into the resolved view", async () => {
+    const { app } = await administrator();
+
+    expect(
+      (
+        await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/groups/media`, {
+          label: "Media",
+          order: 10,
+        })
+      ).status,
+    ).toBe(200);
+    expect(
+      (
+        await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/placements/livestream`, {
+          groupId: "media",
+          order: 10,
+        })
+      ).status,
+    ).toBe(200);
+
+    const navigation = await navigationOf(app);
+
+    expect(navigation.groups.map((group) => group.label)).toEqual(["Media"]);
+    expect(navigation.groups[0]?.modules.map((entry) => entry.name)).toEqual(["Livestream"]);
+    expect(navigation.ungrouped.map((entry) => entry.name)).toEqual(["Calendar", "Video"]);
+  });
+
+  it("renames a group without moving anything", async () => {
+    const { app } = await administrator({
+      groups: [{ id: "media", label: "Media", sortOrder: 10 }],
+      placements: [{ groupId: "media", moduleId: "livestream", sortOrder: 10 }],
+    });
+
+    await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/groups/media`, {
+      label: "Sunday Production",
+      order: 10,
+    });
+    const navigation = await navigationOf(app);
+
+    expect(navigation.groups[0]).toMatchObject({ id: "media", label: "Sunday Production" });
+    expect(navigation.groups[0]?.modules.map((entry) => entry.name)).toEqual(["Livestream"]);
+  });
+
+  it("moves a module between groups and changes only its placement", async () => {
+    const { app } = await administrator({
+      groups: [
+        { id: "media", label: "Media", sortOrder: 10 },
+        { id: "sunday-production", label: "Sunday Production", sortOrder: 5 },
+      ],
+      placements: [
+        { groupId: "media", moduleId: "livestream", sortOrder: 10 },
+        { groupId: "media", moduleId: "video", sortOrder: 20 },
+      ],
+    });
+    const before = await navigationOf(app);
+    const livestreamBefore = before.groups
+      .flatMap((group) => group.modules)
+      .find((entry) => entry.module.id === "livestream");
+
+    await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/placements/livestream`, {
+      groupId: "sunday-production",
+      order: 10,
+    });
+    const after = await navigationOf(app);
+    const livestreamAfter = after.groups
+      .flatMap((group) => group.modules)
+      .find((entry) => entry.module.id === "livestream");
+
+    // The one property this whole pass exists to guarantee: the module — its artifact URL, its API
+    // root, its permissions, its version, its name — is byte-identical across the move.
+    expect(livestreamAfter).toEqual(livestreamBefore);
+    expect(
+      after.groups.find((group) => group.id === "sunday-production")?.modules.map((e) => e.name),
+    ).toEqual(["Livestream"]);
+    expect(after.groups.find((group) => group.id === "media")?.modules.map((e) => e.name)).toEqual([
+      "Video",
+    ]);
+  });
+
+  it("ungroups a module deliberately", async () => {
+    const { app } = await administrator({
+      groups: [{ id: "media", label: "Media", sortOrder: 10 }],
+      placements: [{ groupId: "media", moduleId: "video", sortOrder: 10 }],
+    });
+
+    await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/placements/video`, {
+      groupId: null,
+      order: 5,
+    });
+    const navigation = await navigationOf(app);
+
+    expect(navigation.groups[0]?.modules).toEqual([]);
+    expect(navigation.ungrouped.map((entry) => entry.name)).toEqual([
+      "Video",
+      "Calendar",
+      "Livestream",
+    ]);
+  });
+
+  it("ungroups a deleted group's modules rather than losing them", async () => {
+    const { app } = await administrator({
+      groups: [{ id: "media", label: "Media", sortOrder: 10 }],
+      placements: [{ groupId: "media", moduleId: "video", sortOrder: 10 }],
+    });
+
+    const deleted = await mutate(app, "DELETE", `${DASHBOARD_NAVIGATION_PATH}/groups/media`);
+    const navigation = await navigationOf(app);
+
+    expect(deleted.status).toBe(204);
+    expect(navigation.groups).toEqual([]);
+    expect(navigation.ungrouped.map((entry) => entry.name)).toEqual([
+      "Video",
+      "Calendar",
+      "Livestream",
+    ]);
+  });
+
+  it("refuses a placement naming a group that does not exist", async () => {
+    const { app } = await administrator();
+
+    const response = await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/placements/video`, {
+      groupId: "not-a-group",
+      order: 10,
+    });
+
+    expect(response.status).toBe(404);
+    expect(await response.json()).toEqual({ code: "DASHBOARD_GROUP_NOT_FOUND" });
+  });
+
+  it("refuses a body carrying anything beyond the declared fields", async () => {
+    const { app } = await administrator();
+
+    const bodies: readonly unknown[] = [
+      { label: "Media", order: 10, parentGroupId: "root" },
+      { label: "Media", order: 10, ownerModuleId: "video" },
+      { label: "Media" },
+      { label: "", order: 10 },
+      { label: "Media", order: -1 },
+      { label: "Media", order: 1.5 },
+      { label: 42, order: 10 },
+      [],
+      null,
+    ];
+    for (const body of bodies) {
+      const response = await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/groups/media`, body);
+      expect(response.status, JSON.stringify(body)).toBe(400);
+      expect(await response.json(), JSON.stringify(body)).toEqual({ code: "INVALID_REQUEST" });
+    }
+  });
+
+  it("refuses a malformed group identifier in the path", async () => {
+    const { app } = await administrator();
+
+    const response = await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/groups/Not%20Valid`, {
+      label: "Media",
+      order: 10,
+    });
+
+    expect(response.status).toBe(400);
+  });
+});
+
+describe("Dashboard navigation — authority", () => {
+  it("refuses organizing to a signed-in user without the manage permission", async () => {
+    // Reading works for any signed-in user; organizing does not.
+    const { app } = await install({ principal: signedIn() });
+
+    expect((await app.request(DASHBOARD_NAVIGATION_PATH)).status).toBe(200);
+    const response = await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/groups/media`, {
+      label: "Media",
+      order: 10,
+    });
+
+    expect(response.status).toBe(403);
+    expect(await response.json()).toEqual({ code: "AUTHORIZATION_DENIED" });
+  });
+
+  it("refuses organizing from an untrusted origin, before authorization even runs", async () => {
+    const { app } = await administrator();
+
+    const response = await app.request(`${DASHBOARD_NAVIGATION_PATH}/groups/media`, {
+      body: JSON.stringify({ label: "Media", order: 10 }),
+      headers: { "content-type": "application/json", origin: untrustedOrigin },
+      method: "PUT",
+    });
+
+    expect(response.status).toBe(403);
+    expect(await response.json()).toEqual({ code: "UNTRUSTED_ORIGIN" });
+  });
+
+  it("refuses organizing to an anonymous caller", async () => {
+    const { app } = await install();
+
+    for (const [method, url, body] of [
+      ["PUT", `${DASHBOARD_NAVIGATION_PATH}/groups/media`, { label: "Media", order: 10 }],
+      ["DELETE", `${DASHBOARD_NAVIGATION_PATH}/groups/media`, undefined],
+      ["PUT", `${DASHBOARD_NAVIGATION_PATH}/placements/video`, { groupId: null, order: 0 }],
+    ] as const) {
+      const response = await mutate(app, method, url, body);
+      expect(response.status, `${method} ${url}`).toBe(403);
+    }
+  });
+
+  it("grants no module authority to an administrator who reorganizes the Dashboard", async () => {
+    // The platform owner holds `core.dashboard.navigation.manage` through the owner bypass. That
+    // says nothing about any module: the hints in the navigation view are still evaluated per
+    // module permission, and every module route stays enforced on its own.
+    const { app } = await administrator();
+
+    await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/groups/media`, {
+      label: "Media",
+      order: 10,
+    });
+    await mutate(app, "PUT", `${DASHBOARD_NAVIGATION_PATH}/placements/livestream`, {
+      groupId: "media",
+      order: 10,
+    });
+    const navigation = await navigationOf(app);
+
+    const livestream = navigation.groups[0]?.modules[0];
+    // The fixture modules declare no permissions at all, so an owner still holds none for them:
+    // moving a module into a folder cannot manufacture a permission hint, let alone a grant.
+    expect(livestream?.module.permissions).toEqual([]);
+  });
+
+  it("routes no method the navigation contract does not define", async () => {
+    const { app } = await administrator();
+
+    for (const method of ["POST", "PATCH"] as const) {
+      const response = await app.request(DASHBOARD_NAVIGATION_PATH, {
+        headers: { origin: trustedOrigin },
+        method,
+      });
+      expect(response.status, method).toBe(404);
+    }
+  });
+});

apps/api/tests/module-database.integration.ts

@@ -220,6 +220,7 @@ async function applyCoreMigrations(url: string): Promise<void> {
       "core:0000_identity_core_tables",
       "core:0001_authorization_core_tables",
       "core:0002_authorization_integrity",
+      "core:0003_dashboard_navigation_tables",
     ]);
     await applyModuleMigrations({ aggregate, database: createPostgresMigrationDatabase(url) });
   } finally {
@@ -245,6 +246,7 @@ async function applyMigrationsWithModule(url: string): Promise<void> {
     "core:0000_identity_core_tables",
     "core:0001_authorization_core_tables",
     "core:0002_authorization_integrity",
+    "core:0003_dashboard_navigation_tables",
     "db-facade:0000_initial",
   ]);
   expect(aggregate.migrations[0]?.checksum).toBe(
@@ -439,6 +441,9 @@ describe.sequential("live API — module database explicit migration ownership",
       expect(await migrationHistoryCount(database.url, "core:0002_authorization_integrity")).toBe(
         1,
       );
+      expect(
+        await migrationHistoryCount(database.url, "core:0003_dashboard_navigation_tables"),
+      ).toBe(1);
     } finally {
       await dropDatabase(database.name);
     }

apps/api/tests/module-http-routes.test.ts

@@ -19,6 +19,7 @@ import {
 import type { EkklesiaIdentityRuntime } from "@ekklesia/core/identity";
 import { createModuleUiPublicationRegistry } from "@ekklesia/core/modules";
 import { describe, expect, it, vi } from "vitest";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { createApiApp } from "../src/app.js";
 import {
   canonicalizeVaryHeader,
@@ -108,6 +109,7 @@ function buildModuleApp(options: {
     moduleRoutes: options.routes,
     moduleServices: services,
     moduleUi: createModuleUiPublicationRegistry([]),
+    dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: options.trustedOrigins ?? [trustedOrigin],
   });

apps/api/tests/module-ui-host-e2e.test.ts

@@ -28,6 +28,7 @@ import {
   moduleUiSourceUrl,
 } from "@ekklesia/shell";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { createApiApp } from "../src/app.js";
 
 /**
@@ -73,8 +74,12 @@ afterEach(async () => {
  * already proven end to end by `templates/module`'s own tests, and what this test needs is a byte
  * sequence whose journey through publication, inventory, and the loader can be asserted exactly.
  */
-async function createFixtureModule(modulesDirectory: string): Promise<void> {
-  const moduleDirectory = path.join(modulesDirectory, "example");
+async function createFixtureModule(
+  modulesDirectory: string,
+  id = "example",
+  name = "Example module",
+): Promise<void> {
+  const moduleDirectory = path.join(modulesDirectory, id);
   await mkdir(path.join(moduleDirectory, "dist/server"), { recursive: true });
   await mkdir(path.join(moduleDirectory, "dist/ui"), { recursive: true });
 
@@ -82,7 +87,7 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
     path.join(moduleDirectory, "package.json"),
     JSON.stringify({
       ekklesia: { layer: "module" },
-      name: "@test/module-example",
+      name: `@test/module-${id}`,
       type: "module",
       version: "0.1.0",
     }),
@@ -92,14 +97,14 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
     JSON.stringify({
       compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
       entrypoints: { server: "./dist/server/index.js", ui: "./dist/ui/index.js" },
-      id: "example",
+      id,
       manifestVersion: 4,
-      name: "Example module",
+      name,
       permissions: [
         {
           baseline: "restricted",
           description: "Read example records.",
-          id: "example.records.read",
+          id: `${id}.records.read`,
         },
       ],
       version: "0.1.0",
@@ -108,13 +113,13 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
   await writeFile(
     path.join(moduleDirectory, "dist/server/index.js"),
     `export default {
-      id: "example",
+      id: ${JSON.stringify(id)},
       version: "0.1.0",
       register({ http }) {
         http.route({
           method: "GET",
           path: "/records",
-          permission: "example.records.read",
+          permission: ${JSON.stringify(`${id}.records.read`)},
           maxBodyBytes: 0,
           async handler() {
             return Response.json([{ id: "a" }, { id: "b" }]);
@@ -128,10 +133,10 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
   await writeFile(
     path.join(moduleDirectory, "dist/ui/index.js"),
     `export default {
-  id: "example",
+  id: ${JSON.stringify(id)},
   version: "0.1.0",
   async mount(container, context) {
-    if (!context.permissions.has("example.records.read")) {
+    if (!context.permissions.has(${JSON.stringify(`${id}.records.read`)})) {
       container.textContent = context.moduleId + ":denied";
       return () => { container.textContent = ""; };
     }
@@ -148,6 +153,10 @@ async function createFixtureModule(modulesDirectory: string): Promise<void> {
 interface HarnessOptions {
   readonly principal?: EkklesiaPrincipal;
   readonly grants?: readonly string[];
+  /** Extra fixture modules, so grouping can be exercised with more than one — a folder containing a
+   * single module proves very little. */
+  readonly extraModules?: ReadonlyArray<{ readonly id: string; readonly name: string }>;
+  readonly platformOwner?: boolean;
 }
 
 interface Harness {
@@ -164,6 +173,9 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
   const modulesDirectory = await mkdtemp(path.join(tmpdir(), "ekklesia-host-e2e-"));
   temporaryDirectories.push(modulesDirectory);
   await createFixtureModule(modulesDirectory);
+  for (const extra of options.extraModules ?? []) {
+    await createFixtureModule(modulesDirectory, extra.id, extra.name);
+  }
 
   const modules = await discoverModules({
     moduleSdkVersion: "0.1.0",
@@ -180,7 +192,7 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
   const granted = new Set(options.grants ?? []);
   const evaluator = createAuthorizationEvaluator({
     grants: { hasActiveGrant: async (query) => granted.has(query.permission) },
-    platformOwners: { isPlatformOwner: async () => false },
+    platformOwners: { isPlatformOwner: async () => options.platformOwner === true },
   });
   const runtime: EkklesiaIdentityRuntime = {
     handleAuthRequest: vi.fn().mockResolvedValue(new Response(null, { status: 200 })),
@@ -201,6 +213,7 @@ async function startHarness(options: HarnessOptions = {}): Promise<Harness> {
     moduleRoutes: moduleRuntime.routes,
     moduleServices: services,
     moduleUi: createModuleUiPublicationRegistry(modules),
+    dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: ["https://dashboard.example.test"],
   });
@@ -250,9 +263,12 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
       // 1. The shell's own bootstrap: principal, then inventory.
       const bootstrap = await bootstrapHost(harness.config);
       expect(bootstrap.principal).toEqual({ kind: "authenticated", userId: viewerId });
-      expect(bootstrap.modules).toHaveLength(1);
+      // A module nobody has arranged yet is ungrouped and visible — no initialization write.
+      expect(bootstrap.navigation.groups).toEqual([]);
+      expect(bootstrap.navigation.ungrouped).toHaveLength(1);
+      expect(bootstrap.navigation.ungrouped[0]?.name).toBe("Example module");
 
-      const descriptor = bootstrap.modules[0];
+      const descriptor = bootstrap.navigation.ungrouped[0]?.descriptor;
       if (!descriptor) {
         throw new Error("the inventory returned no module");
       }
@@ -304,7 +320,7 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
     });
     try {
       const bootstrap = await bootstrapHost(harness.config);
-      const descriptor = bootstrap.modules[0];
+      const descriptor = bootstrap.navigation.ungrouped[0]?.descriptor;
       if (!descriptor) {
         throw new Error("the inventory returned no module");
       }
@@ -336,7 +352,7 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
     });
     try {
       const bootstrap = await bootstrapHost(harness.config);
-      const descriptor = bootstrap.modules[0];
+      const descriptor = bootstrap.navigation.ungrouped[0]?.descriptor;
       if (!descriptor) {
         throw new Error("the inventory returned no module");
       }
@@ -364,13 +380,187 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
     }
   });
 
+  it("renders a configured arrangement, and a move changes presentation only", async () => {
+    const harness = await startHarness({
+      extraModules: [
+        { id: "video", name: "Video" },
+        { id: "calendar", name: "Calendar" },
+      ],
+      grants: ["example.records.read"],
+      platformOwner: true,
+      principal: createAuthenticatedPrincipal(viewerId),
+    });
+    const organize = (url: string, body: unknown) =>
+      (harness.config.fetch as typeof fetch)(`https://ekklesia.example.test${url}`, {
+        body: JSON.stringify(body),
+        headers: { "content-type": "application/json", origin: "https://dashboard.example.test" },
+        method: "PUT",
+      });
+
+    try {
+      // An administrator organizes the Dashboard, through the real mutation API.
+      await organize("/api/v1/dashboard/navigation/groups/media", { label: "Media", order: 10 });
+      await organize("/api/v1/dashboard/navigation/groups/planning", {
+        label: "Planning",
+        order: 20,
+      });
+      await organize("/api/v1/dashboard/navigation/placements/video", {
+        groupId: "media",
+        order: 10,
+      });
+      await organize("/api/v1/dashboard/navigation/placements/example", {
+        groupId: "media",
+        order: 20,
+      });
+      await organize("/api/v1/dashboard/navigation/placements/calendar", {
+        groupId: "planning",
+        order: 10,
+      });
+
+      // The shell's own bootstrap sees exactly that arrangement.
+      const before = await bootstrapHost(harness.config);
+      expect(
+        before.navigation.groups.map((group) => [
+          group.label,
+          group.modules.map((entry) => entry.name),
+        ]),
+      ).toEqual([
+        ["Media", ["Video", "Example module"]],
+        ["Planning", ["Calendar"]],
+      ]);
+      expect(before.navigation.ungrouped).toEqual([]);
+
+      // Mounting from inside a group uses the descriptor the group carried, untouched.
+      const groupedEntry = before.navigation.groups[0]?.modules[1];
+      if (!groupedEntry) {
+        throw new Error("the arrangement did not contain the expected module");
+      }
+      const container = containerSink();
+      const mounted = await loadModuleUi({
+        container: container as unknown as LoaderContainer,
+        context: createModuleUiContext({
+          config: harness.config,
+          descriptor: groupedEntry.descriptor,
+          principal: before.principal,
+        }),
+        source: {
+          moduleId: groupedEntry.descriptor.id,
+          url: await publishedArtifactUrl(
+            harness,
+            moduleUiSourceUrl(harness.config, groupedEntry.descriptor),
+          ),
+          version: groupedEntry.descriptor.version,
+        },
+      });
+      expect(container.textContent).toBe("example:200:2");
+      await mounted.unmount();
+
+      // Now move it somewhere else entirely.
+      await organize("/api/v1/dashboard/navigation/groups/sunday-production", {
+        label: "Sunday Production",
+        order: 5,
+      });
+      await organize("/api/v1/dashboard/navigation/placements/example", {
+        groupId: "sunday-production",
+        order: 10,
+      });
+
+      const after = await bootstrapHost(harness.config);
+      expect(
+        after.navigation.groups.map((group) => [
+          group.label,
+          group.modules.map((entry) => entry.name),
+        ]),
+      ).toEqual([
+        ["Sunday Production", ["Example module"]],
+        ["Media", ["Video"]],
+        ["Planning", ["Calendar"]],
+      ]);
+
+      const movedEntry = after.navigation.groups[0]?.modules[0];
+      if (!movedEntry) {
+        throw new Error("the moved module was not found in its new group");
+      }
+      // The whole point of the pass: the module is byte-identical across the move — same artifact
+      // URL, same API root, same permissions, same version, same name.
+      expect(movedEntry).toEqual(groupedEntry);
+
+      // And it still mounts the same artifact and reaches the same API.
+      const callsBeforeRemount = harness.moduleApiCalls.length;
+      const movedContainer = containerSink();
+      const remounted = await loadModuleUi({
+        container: movedContainer as unknown as LoaderContainer,
+        context: createModuleUiContext({
+          config: harness.config,
+          descriptor: movedEntry.descriptor,
+          principal: after.principal,
+        }),
+        source: {
+          moduleId: movedEntry.descriptor.id,
+          url: await publishedArtifactUrl(
+            harness,
+            moduleUiSourceUrl(harness.config, movedEntry.descriptor),
+          ),
+          version: movedEntry.descriptor.version,
+        },
+      });
+      expect(movedContainer.textContent).toBe("example:200:2");
+      expect(harness.moduleApiCalls.slice(callsBeforeRemount)).toEqual([
+        "GET /api/v1/modules/example/records",
+      ]);
+      await remounted.unmount();
+    } finally {
+      await harness.stop();
+    }
+  });
+
+  it("keeps a newly installed module visible beside an existing arrangement", async () => {
+    const harness = await startHarness({
+      extraModules: [{ id: "video", name: "Video" }],
+      platformOwner: true,
+      principal: createAuthenticatedPrincipal(viewerId),
+    });
+    try {
+      await (harness.config.fetch as typeof fetch)(
+        "https://ekklesia.example.test/api/v1/dashboard/navigation/groups/media",
+        {
+          body: JSON.stringify({ label: "Media", order: 10 }),
+          headers: {
+            "content-type": "application/json",
+            origin: "https://dashboard.example.test",
+          },
+          method: "PUT",
+        },
+      );
+      await (harness.config.fetch as typeof fetch)(
+        "https://ekklesia.example.test/api/v1/dashboard/navigation/placements/video",
+        {
+          body: JSON.stringify({ groupId: "media", order: 10 }),
+          headers: {
+            "content-type": "application/json",
+            origin: "https://dashboard.example.test",
+          },
+          method: "PUT",
+        },
+      );
+
+      const bootstrap = await bootstrapHost(harness.config);
+
+      expect(bootstrap.navigation.groups[0]?.modules.map((entry) => entry.name)).toEqual(["Video"]);
+      // `example` was never placed, and is still reachable rather than invisible.
+      expect(bootstrap.navigation.ungrouped.map((entry) => entry.name)).toEqual(["Example module"]);
+    } finally {
+      await harness.stop();
+    }
+  });
+
   it("gives an anonymous visitor no inventory and therefore nothing to mount", async () => {
     const harness = await startHarness();
     try {
       const bootstrap = await bootstrapHost(harness.config);
 
       expect(bootstrap.principal).toEqual({ kind: "anonymous" });
-      expect(bootstrap.modules).toEqual([]);
+      expect(bootstrap.navigation).toEqual({ groups: [], ungrouped: [] });
     } finally {
       await harness.stop();
     }
@@ -383,7 +573,7 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
     });
     try {
       const bootstrap = await bootstrapHost(harness.config);
-      const descriptor = bootstrap.modules[0];
+      const descriptor = bootstrap.navigation.ungrouped[0]?.descriptor;
       if (!descriptor) {
         throw new Error("the inventory returned no module");
       }

apps/api/tests/module-ui-inventory.test.ts

@@ -23,6 +23,7 @@ import {
 } from "@ekklesia/core/modules";
 import type { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { createApiApp } from "../src/app.js";
 import { moduleApiBaseUrl } from "../src/module-http-routes.js";
 import { MODULE_UI_INVENTORY_PATH } from "../src/module-ui-inventory.js";
@@ -168,6 +169,7 @@ async function install(options: InstallOptions): Promise<Installation> {
     moduleRoutes: Object.freeze([]),
     moduleServices: services,
     moduleUi: createModuleUiPublicationRegistry(modules),
+    dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: [trustedOrigin],
   });

apps/api/tests/module-ui-routes.test.ts

@@ -20,6 +20,7 @@ import {
 import { loadModuleUi } from "@ekklesia/module-ui-host";
 import type { Hono } from "hono";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { createApiApp } from "../src/app.js";
 import {
   MODULE_UI_ASSET_PREFIX,
@@ -168,6 +169,7 @@ async function install(fixtures: readonly ModuleFixture[]): Promise<Installation
     moduleRoutes: Object.freeze([]),
     moduleServices: services,
     moduleUi: createModuleUiPublicationRegistry(modules),
+    dashboard: createInMemoryDashboardStore(),
     runtime,
     trustedOrigins: [trustedOrigin],
   });

apps/api/tests/support/in-memory-dashboard-store.ts

@@ -0,0 +1,86 @@
+import type {
+  DashboardConfiguration,
+  DashboardGroupRecord,
+  DashboardPlacementRecord,
+  DashboardStore,
+  SetDashboardPlacementInput,
+  UpsertDashboardGroupInput,
+} from "@ekklesia/core/dashboard";
+import { DashboardStoreError } from "@ekklesia/core/dashboard";
+
+/**
+ * An in-memory `DashboardStore` for tests that exercise **routing and resolution**, not persistence.
+ *
+ * It reproduces only the two behaviours those tests depend on — a placement may not name a group
+ * that does not exist, and deleting a group ungroups its modules (the schema's
+ * `on delete set null`) — and deliberately reproduces nothing else. Everything the real store owns
+ * that this double would only be guessing at (identifier grammar, label trimming and bounds,
+ * ordering bounds, transactional behaviour, and the actual `on delete set null` constraint) is
+ * proven against real PostgreSQL in `core/tests/dashboard-store.integration.ts` instead, so this
+ * double can never quietly stand in for a persistence guarantee nobody checked.
+ */
+export function createInMemoryDashboardStore(
+  seed: Partial<DashboardConfiguration> = {},
+): DashboardStore {
+  const groups = new Map<string, DashboardGroupRecord>(
+    (seed.groups ?? []).map((group) => [group.id, { ...group }] as const),
+  );
+  const placements = new Map<string, DashboardPlacementRecord>(
+    (seed.placements ?? []).map((placement) => [placement.moduleId, { ...placement }] as const),
+  );
+
+  const sorted = <Record extends { readonly sortOrder: number }>(
+    records: readonly Record[],
+    key: (record: Record) => string,
+  ): readonly Record[] =>
+    Object.freeze(
+      [...records].sort(
+        (left, right) =>
+          left.sortOrder - right.sortOrder ||
+          (key(left) < key(right) ? -1 : key(left) > key(right) ? 1 : 0),
+      ),
+    );
+
+  return Object.freeze({
+    async deleteGroup(groupId: string): Promise<void> {
+      if (!groups.delete(groupId)) {
+        throw new DashboardStoreError("DASHBOARD_GROUP_NOT_FOUND");
+      }
+      for (const [moduleId, placement] of placements) {
+        if (placement.groupId === groupId) {
+          placements.set(moduleId, { ...placement, groupId: null });
+        }
+      }
+    },
+
+    async readConfiguration(): Promise<DashboardConfiguration> {
+      return Object.freeze({
+        groups: sorted([...groups.values()], (group) => group.id),
+        placements: sorted([...placements.values()], (placement) => placement.moduleId),
+      });
+    },
+
+    async setPlacement(input: SetDashboardPlacementInput): Promise<DashboardPlacementRecord> {
+      if (input.groupId !== null && !groups.has(input.groupId)) {
+        throw new DashboardStoreError("DASHBOARD_GROUP_NOT_FOUND");
+      }
+      const record: DashboardPlacementRecord = Object.freeze({
+        groupId: input.groupId,
+        moduleId: input.moduleId,
+        sortOrder: input.sortOrder,
+      });
+      placements.set(input.moduleId, record);
+      return record;
+    },
+
+    async upsertGroup(input: UpsertDashboardGroupInput): Promise<DashboardGroupRecord> {
+      const record: DashboardGroupRecord = Object.freeze({
+        id: input.id,
+        label: input.label.trim(),
+        sortOrder: input.sortOrder,
+      });
+      groups.set(input.id, record);
+      return record;
+    },
+  });
+}