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]>

docs/architecture/decisions/0027-dashboard-navigation-and-flat-modules.md

@@ -0,0 +1,268 @@
+# 0027: Dashboard navigation is presentation configuration, and modules stay flat
+
+- Status: Accepted
+- Date: 2026-08-22
+- Extends: [0021](0021-modules-as-hostable-products.md),
+  [0026](0026-minimal-ekklesia-module-ui-host.md)
+
+## Context
+
+ADR 0026 gave Ekklesia a browser shell that mounts discovered module UI. Its navigation was a flat
+list of **module ids** — `livestream`, `announcements` — which is not a usable long-term experience,
+and it had no notion of organizing anything.
+
+The obvious next step carries an equally obvious trap. A church wants to see:
+
+```text
+Media                 Planning              Communication
+├── Livestream        ├── Calendar          └── Announcements
+└── Video             └── Roster
+```
+
+and the tempting way to build that is to let a module say which folder it belongs to, or worse, to
+model "Media" as something Livestream and Video belong *to*. Either turns a rendering preference
+into architecture: a folder becomes an owner, membership starts to look like a dependency, and the
+flat, independently versioned module graph ADR 0021 established quietly acquires a hierarchy nobody
+decided to add.
+
+Two facts from the repository shaped what was actually needed.
+
+**A display name already exists.** `moduleManifestSchema` has required `name` (trimmed, 1–120
+characters) since version 1, and every fixture and the template already set it — `"Example Module"`.
+Nothing needed adding to the manifest to stop rendering raw ids.
+
+**Nothing else exists.** There is no settings or configuration table, no key-value store, no
+organization or tenant model, and no client-side routing anywhere in the repository. Whatever stores
+an arrangement had to be built, and could not be scoped to an organization that does not exist.
+
+## Decision
+
+### Grouping is presentation configuration. It is never module structure.
+
+A Dashboard group is a label on a rendering bucket. It owns no tables, no migrations, no routes, and
+no lifecycle; it has no manifest, no version, and no artifact; nothing depends on it and it depends
+on nothing. **It is not a module**, and "Media" existing does not make Livestream and Video related
+in any way the platform can observe.
+
+The distinction the architecture has to keep sharp:
+
+- *Livestream depends on Video because it calls Video's functionality* — a real technical
+  dependency, declared through the existing module dependency contract, which orders discovery and
+  startup.
+- *Livestream is shown under Media* — a rendering preference an administrator can change at any time,
+  which orders nothing.
+
+Nothing in this pass introduces a parent module, a child module, an owning module, a container
+module, or a group-derived dependency edge. The words do not appear in the contracts, and the
+absence is enforced by tests rather than left to discipline (see **Consequences**).
+
+### No manifest change, and no version 5
+
+`manifest.name` is the display name. It is the module's **product identity** — what the product is
+called — and a module is exactly the right owner of that. Adding a `presentation.name` beside it
+would have created two names for one thing and forced `manifestVersion: 5`, a hard cutover for every
+installed module (ADR 0006's convention: each version rejects all others) in exchange for nothing.
+
+`PublishableModuleUi` gained `name`, carried from the manifest through the existing publication
+registry. That is a Core-internal record, not a manifest change.
+
+### `suggestedGroup` is deferred, deliberately
+
+A module suggesting a default folder is a reasonable idea and was rejected **for this pass** on three
+grounds, in order of weight.
+
+It would force `manifestVersion: 5` — the most disruptive change available — for a *hint*. Its only
+correct semantics ("used when a placement is first materialized, never re-applied over an
+administrator's decision") requires configuration-initialization logic that writes rows on first
+sight of a module; without that machinery the field would be either inert or authoritative, and
+authoritative is the outcome this ADR exists to prevent. And it is not needed: an unplaced module is
+simply ungrouped, which is deterministic, requires no write at all, and is strictly simpler than
+initializing state.
+
+Shipping the field now with semantics we could not yet honour would be adding a misleading contract
+because we know we want the idea eventually. When there is a reason to bump the manifest version,
+this can travel with it.
+
+### Platform-owned, server-side, platform-global persistence
+
+Two Core tables (`core/src/dashboard/schema.ts`), following the `ekklesia_core_*` conventions
+exactly, in migration `0003_dashboard_navigation_tables`:
+
+- `ekklesia_core_dashboard_group` — `id` (opaque stable key), `label`, `sort_order`.
+- `ekklesia_core_dashboard_placement` — `module_id` (primary key: at most one placement per module),
+  nullable `group_id`, `sort_order`.
+
+A church configures its Dashboard, not one browser, so this is server state rather than
+`localStorage`. It is **platform-global**, because Ekklesia has no organization or tenant model;
+inventing a second notion of organization to anticipate one would be worse than adding a scope column
+when a real one exists. That limitation is recorded rather than hidden.
+
+Three schema decisions carry invariants rather than convenience:
+
+`group_id` is `on delete set null`. Deleting a group cannot leave a dangling reference and cannot
+lose a module — its modules become ungrouped, enforced by the database rather than by application
+cleanup that could be skipped.
+
+`module_id` carries **no foreign key**, because modules are packages discovered on disk, not rows. A
+placement for an uninstalled module is therefore normal and is retained, so uninstall-and-reinstall
+preserves an arrangement instead of silently resetting it.
+
+The group `id` is opaque and never re-derived from the label. Renaming "Media" to "Sunday Production"
+changes `label` alone, so every placement survives — a rename can never re-organize the Dashboard.
+
+### The resolution rules, stated exactly
+
+`resolveDashboardNavigation` is a pure function of stored configuration and the currently mountable
+module set. Every rule is directly testable without PostgreSQL:
+
+- **A module with no placement is ungrouped and visible.** Installing a module is sufficient to see
+  it: no initialization write, no manual database edit, no migration. This is the rule that stops a
+  newly installed module from disappearing.
+- **A stored placement for an absent module renders nothing and is retained.** No dead entry; no lost
+  position on reinstall.
+- **A placement naming a missing group is treated as ungrouped**, not dropped. `on delete set null`
+  makes this unreachable in practice; a configuration inconsistency must still never make a module
+  invisible.
+- **Empty groups are kept.** Hiding one would look like it had been deleted.
+- **Ordering is total.** Groups by `(order, id)`; modules by `(configured, order, id)` — placed
+  modules in the administrator's order, then never-configured ones by id, so a newcomer never
+  interrupts an ordering someone chose. Colliding order values can never produce a
+  nondeterministic result; the identifier is always the final tie-break.
+
+Simple integers, not fractional ordering or CRDTs. Reordering rewrites the values it needs to.
+
+### Navigation is layered on the inventory, not merged into it
+
+`GET /api/v1/module-ui` (ADR 0026) still answers *what is mountable*, host-neutrally, and is
+unchanged — no display name, no group, no order. A standalone host consumes it and never learns
+Ekklesia has folders.
+
+`GET /api/v1/dashboard/navigation` answers *how this Dashboard presents those modules*, and
+**embeds** each generic descriptor untouched inside a presentation wrapper:
+
+```json
+{ "groups": [ { "id": "media", "label": "Media", "order": 10,
+                "modules": [ { "name": "Livestream", "module": { "id": "livestream", "…": "…" } } ] } ],
+  "ungrouped": [] }
+```
+
+Embedding rather than flattening is the layering made visible in the payload, and both endpoints
+compose the descriptor through one shared function, so they cannot disagree about what exists or
+about any URL. The server is authoritative for the resolved view: the browser does no grouping, no
+sorting, and no joining, and reads no manifest.
+
+### Reading versus organizing
+
+Reading requires `core.modules.ui.read` — the same permission the inventory requires, because this
+response *contains* that inventory and serves the same audience: any signed-in user needs it to see
+anything at all. A second read permission for the same data would be ceremony.
+
+Organizing requires a new **platform** permission, `core.dashboard.navigation.manage`
+(baseline `restricted`), never a module's — grouping is Ekklesia's configuration, so no module may
+gate, grant, or influence it. Mutations additionally require an exact trusted `Origin` and a bounded
+body before authorization work begins, exactly like every other Core mutation.
+
+Holding it grants no module authority. Moving a module into a folder changes a presentation row; it
+grants nobody access to that module's data, and every module route stays enforced against its own
+declared permission.
+
+### A narrow, structured mutation contract — no configuration blob
+
+Three idempotent operations, each with closed validation that rejects any unexpected key rather than
+dropping it:
+
+```text
+PUT    /api/v1/dashboard/navigation/groups/:groupId       { label, order }
+DELETE /api/v1/dashboard/navigation/groups/:groupId
+PUT    /api/v1/dashboard/navigation/placements/:moduleId  { groupId | null, order }
+```
+
+`PUT` against a client-chosen stable id makes create and rename the same operation, so a rename can
+never orphan a placement. A "save the whole dashboard config" blob was rejected: it has no
+invariants, no per-operation authority, and no way to reject a field nobody meant to send.
+
+No editor UI ships in this pass. The persistence model is proven through the real API instead, which
+is the repository's normal pattern.
+
+### One level of grouping
+
+`Group → Modules`. No nesting, no subgroups. The schema has no parent-group column, so the shape
+itself forecloses it rather than a rule asking developers not to. Nested navigation can be
+reconsidered when a real use case appears.
+
+## Alternatives
+
+- **A `presentation.name` manifest field.** Rejected: `manifest.name` already is the display name,
+  and adding a second would mean two names for one product and a version 5 cutover for nothing.
+- **`suggestedGroup` now.** Deferred; see above. It buys a default at the cost of a manifest version
+  and initialization machinery, and risks becoming authoritative.
+- **A module declaring its own folder authoritatively.** Rejected outright — it is the mistake this
+  ADR exists to prevent. An administrator must be able to move a module without touching it.
+- **Re-applying a module's suggestion on every startup.** Rejected for the same reason: defaulting
+  and ownership are different, and a suggestion that overwrites a decision is ownership.
+- **Modelling a group as a module.** Rejected: it would give a rendering bucket a manifest, a
+  version, a lifecycle, and a place in the dependency graph, and would make "Livestream belongs under
+  Media" indistinguishable from "Livestream depends on Media."
+- **Browser `localStorage`.** Rejected: a church configures its Dashboard, not one browser on one
+  device.
+- **A generalized platform settings framework.** Rejected: two purpose-built tables with real
+  constraints beat a key-value blob whose invariants live only in application code, and nothing else
+  needs settings yet.
+- **Extending the module UI inventory with groups.** Rejected: it would push Dashboard semantics into
+  the host-neutral contract a standalone host is meant to consume.
+- **Making the browser join inventory and configuration.** Rejected: it would put grouping logic —
+  and therefore the ordering rules — in the client, where a second implementation could drift.
+- **Deleting placements for uninstalled modules.** Rejected: retaining them makes reinstall restore
+  an arrangement, at the cost of a few harmless rows.
+- **Hiding empty groups.** Rejected: indistinguishable from deletion, from the administrator's side.
+- **Fractional or CRDT ordering.** Rejected as unjustified for a list a person arranges by hand.
+- **Nested folders, icons, drag and drop, a navigation editor, client routing.** All deferred; each
+  needs a design decision this pass should not make by accident. Icons in particular would
+  immediately require an icon vocabulary, an asset-publication story, and a trust decision about
+  arbitrary SVG.
+
+## Consequences
+
+Ekklesia has a real Dashboard navigation model: persistent, platform-owned, administrator-editable
+through a structured API, rendered by the shell, mounting flat modules through the unchanged generic
+loader. A module now shows as "Livestream" rather than `livestream`.
+
+**The flatness invariant is executable, not aspirational.** `core/tests/dashboard-flat-modules.test.ts`
+discovers real fixtures with a genuine dependency (Livestream depends on Video), then arranges them
+four ways — including both modules under one "Media" folder, and the dependency deliberately inverted
+in presentation — and asserts that discovery order, dependency declarations, capabilities,
+permissions, and the module set come out byte-identical every time, and that no group id is ever a
+module. A future change that let grouping influence any of that fails there.
+
+The end-to-end test goes further: it organizes a real installation through the real mutation API,
+bootstraps the real shell code against it, mounts a module from inside a group, moves that module to
+a different group, and asserts the navigation entry is **byte-identical** across the move — same
+artifact URL, same API root, same permissions, same version, same name — and still mounts and reaches
+the same API.
+
+Four things changed outside the new code. `createApiApp` takes a required `dashboard` store.
+`PublishableModuleUi` carries `name`. Core has a third permission, which moved five existing
+assertions (each updated to name all three permissions rather than to loosen a count). And the shell's
+bootstrap now resolves navigation instead of the raw inventory, which made its client for
+`GET /api/v1/module-ui` dead code; that client was **removed** rather than kept speculatively, and
+its descriptor-validation coverage moved onto the navigation parser. The endpoint itself is unchanged
+and remains fully covered by `apps/api`'s tests.
+
+Two costs worth naming. Navigation configuration is platform-global and will need a scope column when
+an organization model exists. And the navigation endpoint evaluates every listed module's declared
+permissions per request, inheriting ADR 0026's per-request evaluation cost; for a handful of modules
+that is unremarkable, and it is measured work rather than hidden.
+
+## Deferred
+
+Not implemented or promised here: the navigation **editor** — drag and drop, a management UI, and any
+administrator-facing affordance beyond the API; nested folders and subgroups; icons, colors, badges,
+and module descriptions in navigation; `suggestedGroup` and any configuration-initialization or
+defaulting logic; per-module administrator label overrides; Dashboard Home, widgets, summaries, and
+quick actions; permission-aware navigation visibility (whether to hide a module a viewer can do
+nothing in remains an open UX policy); client-side routing and deep links to a selected module;
+organization or tenant scoping; a design system, theme tokens, and CSS asset publication; and every
+real feature module.
+
+The permission-id typing gap carried since ADR 0022 is unchanged: `permissions.has` takes a plain
+string, and the wire arrays are `string[]`, so a typo still silently hides a control.