config/ becomes an empty drop-in mount; examples/ mirrors the mount dirs; plugins & config import the host via #plugin-api/#menu-config subpath imports

examples/README.md

@@ -1,6 +1,10 @@
 # examples/
 
-| Folder | Example of |
-| --- | --- |
-| [`scheduling-plugin/`](scheduling-plugin/) | The reference plugin you copy into `plugins/`: a list page over an upstream REST service, a CSRF-guarded form that forwards a write, and permission-gated nav — built from the core building blocks, holding no state. See its [README](scheduling-plugin/README.md) and the [plugin contract](../README.md#building-plugins). |
-| [`shifts-upstream/`](shifts-upstream/) | A throwaway mock backend the reference plugin reads/writes — stdlib-only, in-memory, no auth. Stands in for your real service so `docker compose up` shows the plugin working out of the box; in production you point `SCHEDULING_UPSTREAM` at the real thing instead. |
+Copy-in reference material. Each subfolder mirrors a **drop-in mount dir** at the repo root — copy it
+across (or bind-mount your own) and restart.
+
+| Path | Copy into | Example of |
+| --- | --- | --- |
+| [`plugins/scheduling/`](plugins/scheduling/) | `plugins/scheduling/` | The reference plugin: a list page over an upstream REST service, a CSRF-guarded form that forwards a write, and permission-gated nav — built from the core building blocks, holding no state. Imports the host surface as `#plugin-api`. See its [README](plugins/scheduling/README.md) and the [plugin contract](../README.md#building-plugins). |
+| [`config/menu.ts`](config/menu.ts) | `config/menu.ts` | The central menu override + branding template (rename/group/order/hide nav, set app name/logo/theme). Imports its typed builder as `#menu-config`; `config/` ships empty, so defaults apply until you copy this in. See [The menu system](../README.md#the-menu-system). |
+| [`shifts-upstream/`](shifts-upstream/) | — (dev service) | A throwaway mock backend the reference plugin reads/writes — stdlib-only, in-memory, no auth. Stands in for your real service so `docker compose up` shows the plugin working out of the box; in production you point `SCHEDULING_UPSTREAM` at the real thing instead. |

examples/config/menu.ts

@@ -0,0 +1,27 @@
+// Reference config/menu.ts — copy into the (empty) config/ mount at the repo root:
+//   cp examples/config/menu.ts config/menu.ts
+// config/ ships empty; mount your own or copy this in. Absent config = built-in defaults.
+//
+// Brand the app and reorder/rename/group/hide nav nodes (by their `id`) across all plugins —
+// the override always wins, applied before the per-user permission filter. Every field is
+// optional; delete one to fall back to the default.
+// See src/ui/menu-config.ts (types), src/ui/nav.ts (NavOverride), README.md (The menu system).
+
+import { defineMenu } from "#menu-config";
+
+export default defineMenu({
+  branding: {
+    name: "Plainpages", // app name shown in the sidebar
+    sub: "Console", // optional subtitle under the name
+    // logo: "/public/logo.svg", // optional logo asset (rendered in the sidebar brand)
+    // theme: "auto",            // default color theme: auto | light | dark
+  },
+
+  // Operator override (rename → group → order → hide), keyed by node id.
+  override: {
+    // rename: { people: "Staff" },                                       // node id → new label
+    // groups: [{ id: "admin", label: "Admin", children: ["users", "roles"] }],
+    // order: ["people", "reports"],                                      // top-level order by id
+    // hide: ["teams"],                                                    // remove nodes (any depth)
+  },
+});

examples/plugins/scheduling/README.md

@@ -1,7 +1,8 @@
 # Scheduling — the reference plugin
 
-A worked example of the [plugin contract](../../README.md#building-plugins). Copy this folder, rename
-it (the folder name becomes the plugin id and mount path), and point it at your own backend.
+A worked example of the [plugin contract](../../../README.md#building-plugins). Copy this folder into
+`plugins/` (it keeps the id and mount path `scheduling`) and point it at your own backend — the folder
+name *is* the plugin id and mount path, so rename it only if you want a different one.
 
 What it demonstrates:
 

examples/plugins/scheduling/plugin.ts

@@ -2,7 +2,7 @@
 // data, a CSRF-guarded form that forwards a write upstream, and permission-gated nav. Copy this
 // folder, rename it, point it at your own backend. Full contract: README.md → Building plugins.
 
-import { definePlugin } from "../../src/plugin-host/plugin-api.ts";
+import { definePlugin } from "#plugin-api";
 import { assertHttpUrl, createShift, createUpstream, listShifts, newShiftForm, overview, READ, SCHEDULING_PATH, SHIFTS_PATH, WRITE } from "./shifts.ts";
 
 // The upstream this plugin reads/writes — a stand-in for your real backend (the plugin is

examples/plugins/scheduling/shifts.test.ts

@@ -2,9 +2,9 @@ import assert from "node:assert/strict";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { Readable } from "node:stream";
 import test from "node:test";
-// Import only from the plugin-api barrel — the same contract boundary shifts.ts uses (the host may
+// Import only from the #plugin-api barrel — the same contract boundary shifts.ts uses (the host may
 // refactor any deeper src/* freely behind it); the test models the dev/test story the contract preaches.
-import { GuardError, Log, type PageChrome, type RequestContext, type RouteResult } from "../../src/plugin-host/plugin-api.ts";
+import { GuardError, Log, type PageChrome, type RequestContext, type RouteResult } from "#plugin-api";
 import {
   assertHttpUrl, buildFormModel, createShift, createUpstream, listShifts, newShiftForm, overview, readInput,
   SHIFTS_PATH, type Shift, type ShiftInput, type ShiftsUpstream, UpstreamError, validate,

examples/plugins/scheduling/shifts.ts

@@ -5,8 +5,8 @@
 // Handlers are factories bound to a ShiftsUpstream, and `fetch` is injectable, so they unit-test as
 // pure functions against a mock upstream with no network (README.md → Local dev & test story).
 
-// One import from the host's plugin-api barrel — the stable author surface (see README.md → Building plugins).
-import { can, CSRF_FIELD, GuardError, type PageChrome, parseListQuery, readFormBody, type RouteHandler, tracedFetch } from "../../src/plugin-host/plugin-api.ts";
+// One import from the host's #plugin-api barrel — the stable author surface (see README.md → Building plugins).
+import { can, CSRF_FIELD, GuardError, type PageChrome, parseListQuery, readFormBody, type RouteHandler, tracedFetch } from "#plugin-api";
 
 export const SCHEDULING_PATH = "/scheduling"; // the plugin's public overview page
 export const SHIFTS_PATH = "/scheduling/shifts";

examples/shifts-upstream/server.ts

@@ -1,4 +1,4 @@
-// Dev-only mock upstream for the reference plugin (examples/scheduling-plugin) — a stand-in for the
+// Dev-only mock upstream for the reference plugin (examples/plugins/scheduling) — a stand-in for the
 // customer's real backend, ready for when you copy the reference plugin into plugins/. NOT part
 // of the app: stdlib only, in-memory (state resets on restart), no auth. Point SCHEDULING_UPSTREAM
 // at your real service in production.