Add the module navigation contract: manifest v9, module routes, return-to-origin

Stage 1 PR 7 (ADR 0063). A module becomes a first-class part of the Dashboard.

- Manifest v9 = v8 plus optional `navigation`: a Lucide icon from the curated
  MODULE_NAVIGATION_ICONS set, and up to 12 primary pages (stable id, safe
  label, kebab-case path relative to the module root; no traversal, schemes,
  queries, duplicates, or nesting). Validated before activation.
- Version 8 stays accepted beside version 9, each read strictly as itself
  (discriminated union); no released manifest is rewritten. The template
  moves to v9; the released Signage 0.1.5 manifest is a test fixture.
- Real module routes: /<id> is the landing view, /<id>/<page> a declared
  page, anything beneath a page a module-owned detail route; anything else
  is not-found and mounts nothing. api/assets/display are never pages.
- Sidebar: declared icons, pages nested under an open module, one
  aria-current, collapsed and drawer behaviour; v8 modules unchanged.
- module-ui-sdk: ModuleUiHostContext.navigation (location, subscribe,
  navigate, link, settings), refusing anything outside the module's routes;
  undefined on the display host. Mount ABI unchanged.
- Return-to-origin: one `?return=` carrier on Settings URLs, validated by
  parseReturnTarget and against running modules' declared routes; Settings
  Back returns to exactly the originating module page, across refreshes.

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

docs/development/api.md

@@ -1165,6 +1165,13 @@ How this installation presents its mountable modules
             "api": { "baseUrl": "/api/v1/modules/livestream" },
             "realtime": { "baseUrl": "/api/v1/module-realtime/livestream" },
             "permissions": ["livestream.streams.read"]
+          },
+          "navigation": {
+            "icon": "video",
+            "pages": [
+              { "id": "streams", "label": "Streams", "path": "streams" },
+              { "id": "archive", "label": "Archive", "path": "archive" }
+            ]
           }
         }
       ]
@@ -1174,6 +1181,13 @@ How this installation presents its mountable modules
 }
 ```
 
+`navigation` is what the module itself declares in manifest version 9
+([ADR 0063](../architecture/decisions/0063-module-navigation-contract-manifest-v9.md)): the Lucide
+icon the Dashboard draws it with, and its primary pages in declared order. It is
+`{ "icon": null, "pages": [] }` for a module that declares none, which every manifest version 8
+module is: the generic icon and a single root page. It sits beside the host-neutral descriptor,
+never inside it, and says nothing about where the module is placed.
+
 ### Navigation versus inventory
 
 They are deliberately separate, and this route is layered **on top of** the inventory rather than

docs/development/security.md

@@ -416,6 +416,29 @@ holding the channel permission may receive. If it intentionally includes a signe
 URL remains a bearer capability and is forwarded byte-for-byte; fixed transport errors never reflect
 payloads, URLs, permissions, runtime exceptions, paths, or stacks.
 
+### A module's navigation reaches only its own pages, and return links only real Dashboard pages
+
+Module navigation ([ADR 0063](../architecture/decisions/0063-module-navigation-contract-manifest-v9.md))
+is inert data plus a narrow host capability:
+
+- **The manifest supplies no executable or remote presentation.** A module's `navigation` is a
+  Lucide name from a curated set (never an SVG, a URL, or code) and page paths that are lowercase
+  kebab-case segments beneath its own root. Traversal, schemes, queries, and percent-encoding are
+  refused before the module can start.
+- **The module gets no history object, router, or `window`.** It asks to move to a path relative to
+  its own root. The host refuses anything that is not its root, or at or beneath a page it declares,
+  so no module can navigate the Dashboard into another module or a platform page.
+- **The host's own namespaces are never pages.** `/api/…`, `/assets/…`, and `/display/…` are never
+  read as a module route, a page, or a return target.
+- **`?return=` is untrusted input.** It is only ever read through `parseReturnTarget`, which accepts
+  a canonical same-origin Dashboard address and nothing else. A module address must also name a
+  running module and one of its routes. Anything else is ignored, and Back is a real link to that
+  validated address, never `history.back()`.
+
+None of this is a security boundary between modules: module UI is trusted code in the host's page
+(see above). It keeps honest mistakes and hostile links from turning Dashboard navigation into an
+open redirect or an API link.
+
 ### Client-side permission checks are not a security boundary
 
 A host may tell a module UI what permissions it believes the viewer holds

docs/development/testing.md

@@ -412,6 +412,33 @@ pre-paint appearance cache
 one write of each fixed key, one removal of the appearance key, and no storage API in any file that
 holds the reset token.
 
+Module navigation
+([ADR 0063](../architecture/decisions/0063-module-navigation-contract-manifest-v9.md)) is proven at
+each layer:
+
+- `packages/contracts/tests/module-navigation.test.ts` covers manifest v9: icons, pages, order, every
+  unsafe path, duplicates, nesting, and bounds. It also accepts the byte-exact released Signage 0.1.5
+  manifest (`tests/fixtures/`) as version 8 with no navigation, and refuses `navigation` in a
+  version 8 document.
+- `core/tests/module-discovery.test.ts` discovers that released v8 module and a v9 module side by
+  side, and refuses an escaping page path.
+- `apps/api/tests/dashboard-routes.test.ts` serves a v9 module's icon and pages beside its
+  descriptor, and `{ icon: null, pages: [] }` for v8.
+- `apps/api/tests/dashboard-host-routes.test.ts` holds the shell's icon names equal to the contract's
+  set, and the host namespaces plus platform pages equal to Core's reserved top-level names.
+- `surfaces/shell/tests/module-navigation.test.tsx` mounts real module artifacts through the loader's
+  Shadow DOM boundary. It covers:
+  - roots, declared pages, detail routes, unknown pages, and disabled modules;
+  - Back and Forward and refresh with no remount;
+  - the sidebar's icons and nested pages, collapsed, and in the drawer;
+  - the navigation capability, including refused paths;
+  - module → Settings → Back to the exact page, and every unsafe return target falling back.
+- `templates/module/tests/module-ui.test.ts` renders the v9 template's pages from the host's
+  location.
+- The deploy smoke's real Chromium drives the v9 template through its pages, a deep link, refresh,
+  Back and Forward, the drawer, and module → Settings → Back. With
+  `EKKLESIA_SMOKE_MODULE_RELEASE_DIR` it runs the released v8 Signage package as well.
+
 The account area
 ([ADR 0062](../architecture/decisions/0062-account-area-and-synced-appearance-preferences.md)) is
 proven at each layer: