§10 public pages + menu items, the blessed explicit alias (todo §10); a plugin may mark a page and its menu option public. A no-permission route/nav node is already anonymous-reachable, so per the human's pick this BLESSES that as a first-class, explicit choice (keep the default; add an explicit alias — not a secure-by-default flip). New optional public?: boolean on Route (src/plugin.ts) + NavNode (src/nav.ts) = "open to everyone, signed in or not", honored outright in isAuthorized (router.ts) + filterByRoles (nav.ts), and MUTUALLY EXCLUSIVE with permission — discovery shapeError recursively rejects a route/nav node setting both, failing the boot loud (never silently picks one). public is filter-only (toRenderNode never emits it). The shell (views/partials/shell.ejs) now renders a Sign in link instead of the profile/sign-out block for an anonymous visitor, so a public page in the native shell (ctx.chrome; ctx.user may be null) isn't a broken "Guest / Sign out". Reference plugin demos it: a public /scheduling Overview route + a public "Overview" nav child (the "Scheduling" header now shows for everyone), the shifts list still behind scheduling:read. Hardened the latent gap the shell newly leans on: claimsToUser rejects an empty email like it does an empty sub. Tests-first (348 → 354 units): router/nav/discovery (public open + reject-both + loads), shell (anon → Sign in, no logout form), app (public route anon-200), shifts (overview handler), jwt-middleware (empty email). Docs: plugin-contract.md ("Public pages & menu items" + route shape + shape-error note) + README (menu system + reference snippet). E2E: visual.spec asserts the public Overview is anon-200 + shown in the member's nav while the gated Shifts redirects/filters. stability-reviewer: APPROVE, no Critical/High/Medium (addressed its one Low — the empty-email hardening). typecheck + 354 units + full scripts/ci.sh gate (visual 10 · auth 1 · oauth 2 · full 7) green.

src/app.test.ts

@@ -329,6 +329,7 @@ const demoPlugin: Plugin = {
     { handler: () => ({ json: { ok: true } }), method: "GET", path: "/data" },
     { handler: () => ({ redirect: "/demo/hello/world" }), method: "POST", path: "/go" },
     { handler: () => ({ html: "secret" }), method: "GET", path: "/secret", permission: "demo:read" },
+    { handler: () => ({ html: "open to all" }), method: "GET", path: "/public-page", public: true }, // §10 blessed public
     { handler: () => ({ data: { who: "Plainpages" }, view: "page" }), method: "GET", path: "/page" },
   ],
 };
@@ -383,6 +384,11 @@ test("mounts plugin routes: params, html/json/redirect/view results, and the per
   assert.equal(denied.status, 303);
   assert.equal(denied.headers.get("location"), "/login?return_to=%2Fdemo%2Fsecret");
 
+  // a route marked public (§10) is reachable anonymously — no gate, no redirect.
+  const open = await fetch(url + "/demo/public-page", { redirect: "manual" });
+  assert.equal(open.status, 200);
+  assert.match(await open.text(), /open to all/);
+
   // known path + wrong method → 405 with Allow; unknown path → 404
   const wrong = await fetch(url + "/demo/data", { method: "DELETE" });
   assert.equal(wrong.status, 405);
@@ -393,9 +399,11 @@ test("mounts plugin routes: params, html/json/redirect/view results, and the per
 test("a plugin view renders the native chrome; its forms are CSRF-guarded via ctx.verifyCsrf (§7)", async (t) => {
   const dir = mkdtempSync(join(tmpdir(), "pp-plugins-"));
   mkdirSync(join(dir, "panelkit", "views"), { recursive: true });
-  // The view composes the core shell from ctx.chrome — branding, the global nav, the Sign-out form.
+  // The view composes the core shell from ctx.chrome — branding, the global nav — and its own
+  // CSRF-guarded form carrying chrome.csrfToken (the representative way a plugin form gets the token,
+  // independent of the shell's auth-dependent profile/sign-out block).
   writeFileSync(join(dir, "panelkit", "views", "panel.ejs"),
-    `<%- include("partials/shell", { brand: chrome.brand, csrfToken: chrome.csrfToken, nav: include("partials/nav-tree", { nodes: chrome.nav }), title, user: chrome.user }) %>`);
+    `<%- include("partials/shell", { body: '<form method="post" action="/panelkit/save"><input type="hidden" name="_csrf" value="' + chrome.csrfToken + '" /></form>', brand: chrome.brand, csrfToken: chrome.csrfToken, nav: include("partials/nav-tree", { nodes: chrome.nav }), title, user: chrome.user }) %>`);
   t.after(() => rmSync(dir, { force: true, recursive: true }));
 
   const plugin: Plugin = {
@@ -422,7 +430,7 @@ test("a plugin view renders the native chrome; its forms are CSRF-guarded via ct
   const url = `http://localhost:${(app.address() as AddressInfo).port}`;
 
   // GET renders the shell: branding (DEFAULT_MENU), the (ungated) plugin nav, and a CSRF cookie
-  // whose token is embedded in the Sign-out form (double-submit).
+  // whose token is embedded in the plugin's own form (double-submit).
   const res = await fetch(url + "/panelkit/panel");
   assert.equal(res.status, 200);
   const body = await res.text();

src/discovery.test.ts

@@ -51,6 +51,8 @@ const badCases: Array<{ name: string; files: Record<string, string>; match: RegE
   { name: "non-function dashboard", files: { "weirddash/plugin.ts": `export default { apiVersion: "1.0.0", dashboard: "nope" };` }, match: /weirddash.*dashboard.*function/s },
   { name: "reserved dashboard id shadows the gated dashboard", files: { "dashboard/plugin.ts": full("dashboard") }, match: /dashboard.*reserved/s },
   { name: "duplicate nav id across plugins", files: { "a/plugin.ts": full("a").replace("a:root", "dup"), "b/plugin.ts": full("b").replace("b:root", "dup") }, match: /nav id "dup"/ },
+  { name: "a route marked public AND permission is contradictory (§10)", files: { "contra/plugin.ts": `export default { apiVersion: "1.0.0", routes: [{ method: "GET", path: "/", public: true, permission: "x", handler: () => ({ html: "x" }) }] };` }, match: /contra.*public.*permission/s },
+  { name: "a nav node marked public AND permission is contradictory (§10)", files: { "contranav/plugin.ts": `export default { apiVersion: "1.0.0", nav: [{ id: "n", label: "N", public: true, permission: "x" }] };` }, match: /contranav.*public.*permission/s },
   { name: "two plugins claim the public home", files: { "a/plugin.ts": `export default { apiVersion: "1.0.0", home: () => ({ html: "a" }) };`, "b/plugin.ts": `export default { apiVersion: "1.0.0", home: () => ({ html: "b" }) };` }, match: /home/ },
   { name: "two plugins claim the gated dashboard", files: { "a/plugin.ts": `export default { apiVersion: "1.0.0", dashboard: () => ({ html: "a" }) };`, "b/plugin.ts": `export default { apiVersion: "1.0.0", dashboard: () => ({ html: "b" }) };` }, match: /dashboard/ },
 ];
@@ -61,6 +63,14 @@ for (const c of badCases) {
   });
 }
 
+test("a route + nav node may be marked public (§10) and load fine", async (t) => {
+  const dir = scaffold(t, { "pub/plugin.ts": `export default { apiVersion: "1.0.0", nav: [{ href: "/pub", id: "n", label: "N", public: true }], routes: [{ method: "GET", path: "/", public: true, handler: () => ({ html: "x" }) }] };` });
+  const plugins = await discoverPlugins({ dir });
+  assert.equal(plugins.length, 1);
+  assert.equal(plugins[0]?.routes?.[0]?.public, true);
+  assert.equal(plugins[0]?.nav?.[0]?.public, true);
+});
+
 test("a plugin may declare `home` (public /) and `dashboard` (gated /dashboard) handlers (§10)", async (t) => {
   const dir = scaffold(t, { "portal/plugin.ts": `export default { apiVersion: "1.0.0", home: () => ({ view: "home" }), dashboard: () => ({ view: "dash" }) };` });
   const plugins = await discoverPlugins({ dir });

src/discovery.ts

@@ -93,6 +93,23 @@ function shapeError(manifest: PluginManifest): string | null {
   for (const slot of ["home", "dashboard"] as const) {
     if (manifest[slot] !== undefined && typeof manifest[slot] !== "function") return `"${slot}" must be a function (a route handler)`;
   }
+  // `public` and `permission` are contradictory on the same route/nav node (§10) — "open to all" vs
+  // "needs this role". Refuse rather than silently pick one, so the author's intent is unambiguous.
+  for (const route of Array.isArray(manifest.routes) ? manifest.routes : []) {
+    if (route?.public === true && route.permission != null) return `route "${route.method} ${route.path}" sets both public and permission — they are mutually exclusive`;
+  }
+  const navContradiction = findPublicNavContradiction(manifest.nav);
+  if (navContradiction) return navContradiction;
+  return null;
+}
+
+// Recurse the nav fragment: a node that is both `public` and `permission`-gated is contradictory (§10).
+function findPublicNavContradiction(nodes: PluginManifest["nav"]): string | null {
+  for (const node of Array.isArray(nodes) ? nodes : []) {
+    if (node?.public === true && node.permission != null) return `nav node "${node.label ?? node.id ?? "?"}" sets both public and permission — they are mutually exclusive`;
+    const inChild = findPublicNavContradiction(node?.children);
+    if (inChild) return inChild;
+  }
   return null;
 }
 

src/jwt-middleware.test.ts

@@ -59,7 +59,9 @@ test("verifyToken rejects a bad signature and an unknown kid", async () => {
 
 test("claimsToUser requires sub + email, defaults roles to [], keeps only string roles", () => {
   assert.throws(() => claimsToUser({ email: "a@b.c", exp: NOW }), /sub/);
+  assert.throws(() => claimsToUser({ email: "a@b.c", exp: NOW, sub: "" }), /sub/); // empty sub rejected too
   assert.throws(() => claimsToUser({ exp: NOW, sub: "u" }), /email/);
+  assert.throws(() => claimsToUser({ email: "", exp: NOW, sub: "u" }), /email/); // empty email rejected (the shell keys signed-in vs anonymous off it)
   assert.deepEqual(claimsToUser({ email: "a@b.c", sub: "u" }).roles, []); // roles absent
   assert.deepEqual(claimsToUser({ email: "a@b.c", roles: ["a", 1, "b"], sub: "u" }).roles, ["a", "b"]);
 });

src/jwt-middleware.ts

@@ -58,13 +58,14 @@ export function validateClaims(payload: Record<string, unknown>, options: Verify
   }
 }
 
-// Map verified claims → the request User. sub/email are required (the tokenizer always sets
-// them); roles defaults to [] and keeps only string entries (defensive).
+// Map verified claims → the request User. sub/email are required and non-empty (the tokenizer
+// always sets them; an empty email would read as anonymous in the shell); roles defaults to [] and
+// keeps only string entries (defensive).
 export function claimsToUser(payload: Record<string, unknown>): User {
   const sub = payload["sub"];
   if (typeof sub !== "string" || sub === "") throw new TokenError("token missing sub");
   const email = payload["email"];
-  if (typeof email !== "string") throw new TokenError("token missing email");
+  if (typeof email !== "string" || email === "") throw new TokenError("token missing email");
   const roles = payload["roles"];
   return { email, id: sub, roles: Array.isArray(roles) ? roles.filter((r): r is string => typeof r === "string") : [] };
 }

src/nav.test.ts

@@ -45,6 +45,22 @@ test("composeNav drops gated subtrees, empty headers, and (with no roles) all ga
   assert.deepEqual(composeNav(), []);
 });
 
+test("composeNav keeps a node marked public for everyone — the blessed public alias (§10)", () => {
+  // A header with one public child + one gated child: with no roles, the public child keeps the
+  // header alive (the gated child is filtered out) — so a plugin can show a public menu option to all.
+  const frag: NavNode[][] = [[{
+    icon: "i-cal", id: "sched", label: "Scheduling",
+    children: [
+      { href: "/scheduling", id: "overview", label: "Overview", public: true },
+      { href: "/scheduling/shifts", id: "shifts", label: "Shifts", permission: "scheduling:read" },
+    ],
+  }]];
+  // `public` is filter-only (like id/permission) — never rendered into the output node.
+  assert.deepEqual(composeNav(frag, {}, []), [
+    { icon: "i-cal", label: "Scheduling", children: [{ href: "/scheduling", label: "Overview" }] },
+  ]);
+});
+
 test("composeNav applies the override: rename, group, order, hide (then filters)", () => {
   const base: NavNode[][] = [[
     { href: "/a", id: "a", label: "Alpha" },

src/nav.ts

@@ -1,7 +1,7 @@
 // composeNav (todo §1): merge each plugin's nav fragment into one tree, apply the central
 // override, then permission-filter per user. Pure and I/O-free — menu gating reads the JWT
-// `roles` claim (README "The menu system"), never Keto. A node is visible iff it declares no
-// `permission` or `roles` includes that permission token; a gated header hides its whole
+// `roles` claim (README "The menu system"), never Keto. A node is visible iff it is `public`, or
+// declares no `permission`, or `roles` includes that permission token; a gated header hides its whole
 // subtree, and a pure header left with no children is dropped. The §2 config/menu.ts supplies
 // the override (+ branding); this helper only transforms data, so its result is per-deployment
 // up to the final role filter and emits clean nodes ready for nav-tree.ejs (no id/permission).
@@ -16,6 +16,7 @@ export interface NavNode {
   label: string;
   open?: boolean;
   permission?: string; // required role token; consumed by the filter, never rendered
+  public?: boolean; // §10: show to everyone, signed in or not — the blessed alias for "no permission", stated outright; consumed by the filter, never rendered. Mutually exclusive with permission (discovery refuses both).
 }
 
 // Central override (config/menu.ts, §2). Targets nodes by `id`; applied rename → group →
@@ -105,7 +106,7 @@ function hideTree(nodes: NavNode[], hide: Set<string>): NavNode[] {
 function filterByRoles(nodes: NavNode[], roles: Set<string>): NavNode[] {
   const out: NavNode[] = [];
   for (const n of nodes) {
-    if (n.permission != null && !roles.has(n.permission)) continue; // gated → drop node + subtree
+    if (n.public !== true && n.permission != null && !roles.has(n.permission)) continue; // gated → drop node + subtree (public always shows)
     if (!n.children) { out.push(n); continue; }
     const children = filterByRoles(n.children, roles);
     if (children.length === 0 && n.href == null) continue; // empty pure header → drop

src/plugin.ts

@@ -30,6 +30,10 @@ export interface Route {
   method: HttpMethod;
   path: string; // relative to the plugin's mount path `/<id>`; ":name" segments → ctx.params.name
   permission?: string; // coarse gate (a role token); checked before the handler runs
+  // Mark the page reachable by anyone, signed in or not (§10). The same as omitting `permission`
+  // — a no-permission route is already open — but stated outright, so "public" is a deliberate
+  // choice, not an accident. Mutually exclusive with `permission` (discovery refuses both).
+  public?: boolean;
 }
 
 // A permission token this plugin introduces — declared for docs/seeding. Tokens are a shared

src/router.test.ts

@@ -55,11 +55,13 @@ test("allowedMethods lists methods at a path (GET implies HEAD); empty when the
   assert.deepEqual(allowedMethods(plugins, "/x/missing"), []);
 });
 
-test("isAuthorized: open routes pass; gated routes require the role token", () => {
+test("isAuthorized: open routes pass; gated routes require the role token; public is explicitly open", () => {
   const open: Route = { handler: noop, method: "GET", path: "/" };
   const gated: Route = { handler: noop, method: "GET", path: "/", permission: "x:read" };
+  const pub: Route = { handler: noop, method: "GET", path: "/", public: true }; // §10 blessed public alias
   assert.equal(isAuthorized(open, []), true);
   assert.equal(isAuthorized(gated, []), false);
   assert.equal(isAuthorized(gated, ["x:read"]), true);
   assert.equal(isAuthorized(gated, ["other"]), false);
+  assert.equal(isAuthorized(pub, []), true); // open to anonymous, like omitting permission — but stated outright
 });

src/router.ts

@@ -74,8 +74,9 @@ export function allowedMethods(plugins: Plugin[], pathname: string): string[] {
   return [...methods].sort();
 }
 
-// Coarse permission gate: a route with no `permission` is open; otherwise the user's roles (from
-// the session JWT, §4) must include the token. The same rule composeNav uses for the menu.
+// Coarse permission gate: a route marked `public` (or one with no `permission`) is open; otherwise
+// the user's roles (from the session JWT, §4) must include the token. The same rule composeNav uses
+// for the menu. `public` and `permission` are mutually exclusive (discovery refuses both, §10).
 export function isAuthorized(route: Route, roles: string[]): boolean {
-  return route.permission == null || roles.includes(route.permission);
+  return route.public === true || route.permission == null || roles.includes(route.permission);
 }

src/shell.test.ts

@@ -12,6 +12,7 @@ test("app shell renders sidebar, topbar and the content slot", async () => {
     title: "People",
     brand: { name: "Acme Console", sub: "v2" },
     csrfToken: "tok.sig",
+    user: { email: "ada@acme.io", initials: "AD", name: "ada" }, // a signed-in identity → profile + Sign out
     nav: '<a id="nav-marker" href="/x">Overview</a>',
     body: '<section id="body-marker">page</section>',
     actions: '<button id="action-marker">Add</button>',
@@ -42,6 +43,12 @@ test("app shell renders sidebar, topbar and the content slot", async () => {
   assert.match(html, /<use href="#i-menu"\s*\/?>/); // hamburger references the menu icon
 });
 
+test("app shell offers Sign in (not Sign out) to an anonymous visitor — so a public page in the shell works (§10)", async () => {
+  const html = await render({ title: "Overview", brand: { name: "Acme" }, nav: "", body: "x" }); // no user → Guest
+  assert.match(html, /href="\/login"[^>]*>[\s\S]*?Sign in/); // a path to sign in
+  assert.doesNotMatch(html, /action="\/logout"/); // a guest has no session to end
+});
+
 test("app shell renders a configured logo + default theme, falls back to the brand mark", async () => {
   const branded = await render({ brand: { logo: "/public/brand/logo.svg", name: "Acme" }, theme: "dark" });
   assert.match(branded, /<img class="brand-logo" src="\/public\/brand\/logo\.svg"/);