Built-in Groups admin screen (todo §5); /admin/groups list (search/sort/paginate) + create/delete + membership (add/remove users & nested groups), writing only to Keto — gated admin-only + CSRF-guarded like Users (Kratos read only to label pickers). A group = Keto subject set Group:<name>#members, exists while it has ≥1 member: create writes the first-member tuple, delete removes all by partial-filter. Extracted shared admin-nav.ts (Dashboard·Users·Groups); new generic rowHeader <th scope=row> data-table cell. Stability-reviewer run as a local PR: symmetric subject UUID-validation, duplicate-name rejection, malformed-%→404. 228→237 units + typecheck green; core Keto interactions boot-verified live

README.md

@@ -534,6 +534,8 @@ src/context.ts       RequestContext handed to handlers + buildContext()
 src/config.ts        Env loader — Ory endpoints, cookie/CSRF secrets, JWKS, port; validated at boot
 src/dashboard.ts     buildDashboardModel(): the home "/" People list view model (mock data, wires the §1 helpers)
 src/admin-users.ts   Built-in Users admin screen (§5): list Kratos identities (filter/sort/paginate) + create/edit/deactivate/delete/recovery; gated + CSRF-guarded
+src/admin-groups.ts  Built-in Groups admin screen (§5): list Keto subject sets + create/delete + membership (add/remove users & nested groups); writes only to Keto, gated + CSRF-guarded
+src/admin-nav.ts     adminNav(): the shared sidebar nav for the built-in admin screens (Dashboard · Users · Groups)
 src/shell-context.ts buildShellContext(): brand/theme/user view-model shared by the dashboard + admin screens (real signed-in user, no demo profile)
 src/icons.ts         Used-icon registry + sprite builder from lucide-static (regenerates partials/icons.ejs)
 src/list-query.ts    parseListQuery(): read a list URL → { q, filters, sort, page, pageSize }
@@ -544,7 +546,7 @@ src/discovery.ts     discoverPlugins(): scan plugins/, import + validate each pl
 src/router.ts        matchRoute()/allowedMethods()/isAuthorized(): map method+path → plugin route, params, permission gate (§2)
 src/view-resolver.ts renderPluginView(): render plugins/<id>/views/<view>.ejs; plugin views can include() core partials (§2)
 src/menu-config.ts   loadMenuConfig()/defineMenu(): read config/menu.ts (central override + branding), validated at boot (§2)
-views/               Core EJS templates (index = the app-shell People dashboard, admin/ = the Users admin list + create/edit form, auth = themed Kratos self-service page, 403/404/500, partials/ incl. app shell, nav tree, filter bar, data table, pagination, form field, auth card, alert, flow body, user-form body, menu/popover, theme switch, icon sprite)
+views/               Core EJS templates (index = the app-shell People dashboard, admin/ = the Users list + create/edit form and the Groups list + create form + membership detail, auth = themed Kratos self-service page, 403/404/500, partials/ incl. app shell, nav tree, filter bar, data table, pagination, form field, auth card, alert, flow body, user-form/group-form/group-detail bodies, menu/popover, theme switch, icon sprite)
 public/              Static assets under /public/ (css/styles.css + auth.css, favicon, robots.txt)
 config/menu.ts       Central menu override + branding (optional; defaults apply if absent)
 ory/                 Ory service config (kratos/: identity schema, kratos.yml, oidc/ SSO claims mapper, tokenizer/ session→JWT claims mapper + dev signing JWKS; keto/: keto.yml + namespaces.keto.ts OPL — role/group/resource; hydra/hydra.yml: OAuth2 issuer + login/consent URLs) + storage init (postgres/init/init.sql: one DB per service)

public/css/styles.css

@@ -673,6 +673,8 @@ th[aria-sort="descending"] .sort-ico { transform: rotate(180deg); }
   border: 1px solid var(--border); border-radius: var(--radius);
 }
 .form-actions { display: flex; gap: 10px; justify-content: flex-end; }
+.card-title { margin: 0; font-size: 14px; font-weight: 600; }
+.inline-form { display: flex; flex-wrap: wrap; gap: 10px; align-items: center; }
 .admin-actions { flex-flow: row wrap; gap: 10px; align-items: center; }
 .admin-actions form { margin: 0; }
 .btn-danger { color: var(--neg); border-color: var(--neg-bd); }

src/admin-groups.test.ts

@@ -0,0 +1,112 @@
+// Built-in Groups admin screen (§5): the pure view-model + Keto-tuple builders. A group is a
+// Keto subject set (Group:<name>#members); membership tuples carry users (subject_id) or nested
+// groups (subject_set). The HTTP routing/gate/CSRF + live Keto/Kratos calls are exercised over
+// HTTP in app.test.ts.
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  buildGroupDetailModel,
+  buildGroupFormModel,
+  buildGroupsListModel,
+  groupsFromTuples,
+  isValidGroupName,
+  memberTuple,
+  memberView,
+  parseSubject,
+} from "./admin-groups.ts";
+import type { RelationTuple } from "./keto-client.ts";
+
+const uid = (n: number) => `01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b${String(n).padStart(2, "0")}`;
+const userTuple = (group: string, n: number): RelationTuple =>
+  ({ namespace: "Group", object: group, relation: "members", subject_id: `user:${uid(n)}` });
+const groupTuple = (group: string, child: string): RelationTuple =>
+  ({ namespace: "Group", object: group, relation: "members", subject_set: { namespace: "Group", object: child, relation: "members" } });
+
+test("isValidGroupName accepts URL-safe names, rejects empties/spaces/uppercase/leading punctuation", () => {
+  for (const ok of ["eng", "team-a", "a1_b9", "x"]) assert.equal(isValidGroupName(ok), true, ok);
+  for (const bad of ["", "Eng", "a b", "-bad", "_bad", "a/b", "a".repeat(65)]) assert.equal(isValidGroupName(bad), false, bad);
+});
+
+test("parseSubject + memberTuple map the form value to the user/nested-group subject (else null)", () => {
+  assert.deepEqual(parseSubject(`user:${uid(1)}`), { subject_id: `user:${uid(1)}` });
+  assert.deepEqual(parseSubject("group:eng"), { subject_set: { namespace: "Group", object: "eng", relation: "members" } });
+  // Both forms are validated: a non-UUID user / invalid group name is rejected, not written blindly.
+  for (const bad of ["", "user:", "user:not-a-uuid", "group:", "group:Bad Name", "nope:x", "plain"]) assert.equal(parseSubject(bad), null, bad);
+
+  assert.deepEqual(memberTuple("design", `user:${uid(2)}`), { namespace: "Group", object: "design", relation: "members", subject_id: `user:${uid(2)}` });
+  assert.deepEqual(memberTuple("design", "group:eng"), { namespace: "Group", object: "design", relation: "members", subject_set: { namespace: "Group", object: "eng", relation: "members" } });
+  assert.equal(memberTuple("design", "bad"), null);
+});
+
+test("groupsFromTuples collapses membership tuples → distinct groups + member counts, sorted by name", () => {
+  const tuples = [userTuple("eng", 1), userTuple("eng", 2), groupTuple("eng", "design"), userTuple("design", 3)];
+  assert.deepEqual(groupsFromTuples(tuples), [
+    { memberCount: 1, name: "design" },
+    { memberCount: 3, name: "eng" },
+  ]);
+});
+
+test("memberView resolves a user subject to its email (else the raw id) and a subject_set to the group", () => {
+  const emails = new Map([[uid(1), "ada@example.com"]]);
+  assert.deepEqual(memberView(userTuple("eng", 1), emails), { kind: "user", label: "ada@example.com", subject: `user:${uid(1)}` });
+  assert.deepEqual(memberView(userTuple("eng", 9), emails), { kind: "user", label: `user:${uid(9)}`, subject: `user:${uid(9)}` });
+  assert.deepEqual(memberView(groupTuple("eng", "design"), emails), { kind: "group", label: "design", subject: "group:design" });
+});
+
+test("buildGroupsListModel filters by search, sorts, paginates; the name links to the detail page", () => {
+  const groups = Array.from({ length: 30 }, (_, i) => ({ memberCount: i + 1, name: `team-${String(i).padStart(2, "0")}` }));
+
+  const all = buildGroupsListModel({ groups, url: "http://x/admin/groups" });
+  assert.equal(all.pagination.summary.total, 30);
+  assert.equal(all.table.rows.length, 25); // default page size
+  assert.equal(all.shell.title, "Groups");
+  // The group name is the row header, linking to its detail page.
+  const first = all.table.rows[0]!.cells[0] as { rowHeader: { href: string; text: string } };
+  assert.equal(first.rowHeader.text, "team-00");
+  assert.equal(first.rowHeader.href, "/admin/groups/team-00");
+
+  // Search narrows + shows a pill.
+  const one = buildGroupsListModel({ groups, url: "http://x/admin/groups?q=team-07" });
+  assert.equal(one.pagination.summary.total, 1);
+  assert.deepEqual(one.filterBar.pills.map((p) => p.label), ["Search"]);
+
+  // Sort by members descending puts the biggest group first.
+  const desc = buildGroupsListModel({ groups, url: "http://x/admin/groups?sort=-members" });
+  assert.equal((desc.table.rows[0]!.cells[0] as { rowHeader: { text: string } }).rowHeader.text, "team-29");
+});
+
+test("buildGroupFormModel: a create form with a required name field + member options, no group of its own", () => {
+  const options = [{ label: "ada@example.com", value: `user:${uid(1)}` }, { label: "eng (group)", value: "group:eng" }];
+  const m = buildGroupFormModel({ csrfToken: "tok.sig", memberOptions: options });
+  assert.equal(m.shell.title, "New group");
+  assert.equal(m.form.action, "/admin/groups");
+  assert.equal(m.form.submitLabel, "Create group");
+  assert.equal(m.form.csrfToken, "tok.sig");
+  assert.equal(m.form.nameField.name, "name");
+  assert.equal(m.form.nameField.required, true);
+  assert.deepEqual(m.form.memberOptions, options);
+
+  // An error (e.g. a taken/invalid name) re-renders with the submitted values.
+  const err = buildGroupFormModel({ error: "That name is taken.", memberOptions: options, values: { member: "group:eng", name: "Eng" } });
+  assert.equal(err.error, "That name is taken.");
+  assert.equal(err.form.nameField.value, "Eng");
+  assert.equal(err.form.selectedMember, "group:eng");
+});
+
+test("buildGroupDetailModel: members → rows, add-options exclude current members + the group itself, delete/remove wired", () => {
+  const members = [memberView(userTuple("eng", 1), new Map([[uid(1), "ada@example.com"]])), memberView(groupTuple("eng", "design"), new Map())];
+  const candidates = [
+    { label: "ada@example.com", value: `user:${uid(1)}` }, // already a member → excluded
+    { label: "grace@example.com", value: `user:${uid(2)}` },
+    { label: "design (group)", value: "group:design" }, // already a member → excluded
+    { label: "eng (group)", value: "group:eng" }, // the group itself → excluded
+    { label: "ops (group)", value: "group:ops" },
+  ];
+  const m = buildGroupDetailModel({ candidates, group: { name: "eng" }, members });
+  assert.equal(m.shell.title, "eng");
+  assert.equal(m.members.rows.length, 2);
+  assert.equal(m.members.action, "/admin/groups/eng/members/delete");
+  assert.equal(m.add.action, "/admin/groups/eng/members");
+  assert.deepEqual(m.add.options.map((o) => o.value), [`user:${uid(2)}`, "group:ops"]);
+  assert.equal(m.delete.action, "/admin/groups/eng/delete");
+});

src/admin-groups.ts

@@ -0,0 +1,410 @@
+// Built-in Groups admin screen (todo §5): list / create / delete Keto groups and manage their
+// membership. A group is a Keto subject set `Group:<name>#members`; a membership tuple's subject is
+// a user (`subject_id = user:<id>`) or a nested group (`subject_set = Group:<other>#members`). Writes
+// go only to Keto (README "stateless"); there is no group store. Keto has no "create object" — a
+// group exists exactly while it has ≥1 member, so creating one writes its first-member tuple and
+// deleting one removes every member tuple. The pure builders turn tuples + the request URL into the
+// building-block view models; `handleAdminGroups` is the imperative shell app.ts dispatches to — it
+// gates (admin only), CSRF-guards every mutation, and maps each action to a RouteResult.
+
+import { ADMIN_GROUPS_BASE, ADMIN_PERMISSION, adminNav } from "./admin-nav.ts";
+import type { FieldConfig } from "./admin-users.ts";
+import { readFormBody } from "./body.ts";
+import type { RequestContext, User } from "./context.ts";
+import { CSRF_FIELD, verifyCsrfRequest } from "./csrf.ts";
+import { GuardError } from "./guards.ts";
+import type { KetoClient, RelationQuery, RelationTuple, SubjectSet } from "./keto-client.ts";
+import type { KratosAdmin } from "./kratos-admin.ts";
+import { parseListQuery } from "./list-query.ts";
+import { DEFAULT_MENU, type MenuConfig } from "./menu-config.ts";
+import { paginate } from "./paginate.ts";
+import type { RouteResult } from "./plugin.ts";
+import { buildShellContext } from "./shell-context.ts";
+
+const GROUP_NS = "Group";
+const MEMBERS = "members";
+const DEFAULT_PAGE_SIZE = 25;
+const PAGE_SIZES = [25, 50, 100];
+// One Keto page of candidate users is fetched for the member pickers (mirrors admin-users).
+const LIST_FETCH_SIZE = 250;
+const GROUP_NAME = /^[a-z0-9][a-z0-9_-]*$/; // URL-safe; doubles as the path segment
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; // a Kratos identity id
+
+export interface GroupView {
+  memberCount: number;
+  name: string;
+}
+
+// A member's view model: a user (label = email) or a nested group (label = group name). `subject`
+// is the form value that round-trips it — `user:<id>` or `group:<name>` (see parseSubject).
+export interface MemberView {
+  kind: "group" | "user";
+  label: string;
+  subject: string;
+}
+
+// One option in a member <select>.
+export interface MemberOption {
+  label: string;
+  value: string; // `user:<id>` | `group:<name>`
+}
+
+export function isValidGroupName(name: string): boolean {
+  return name.length <= 64 && GROUP_NAME.test(name);
+}
+
+// Map a member-picker value → the Keto subject (subject_id for a user, subject_set for a nested
+// group). Returns null for anything unrecognised (a crafted/empty POST).
+export function parseSubject(value: string): { subject_id: string } | { subject_set: SubjectSet } | null {
+  const sep = value.indexOf(":");
+  if (sep <= 0) return null;
+  const rest = value.slice(sep + 1);
+  if (!rest) return null;
+  // Validate both subject forms so a crafted POST can't write a dangling tuple (the pickers only
+  // ever offer real users/groups): a user id is a Kratos UUID, a nested group a valid group name.
+  if (value.slice(0, sep) === "user") return UUID.test(rest) ? { subject_id: `user:${rest}` } : null;
+  if (value.slice(0, sep) === "group") return isValidGroupName(rest) ? { subject_set: { namespace: GROUP_NS, object: rest, relation: MEMBERS } } : null;
+  return null;
+}
+
+// The full membership tuple for adding/removing `value` to/from `group` (null if value is invalid).
+export function memberTuple(group: string, value: string): RelationTuple | null {
+  const subject = parseSubject(value);
+  return subject ? { namespace: GROUP_NS, object: group, relation: MEMBERS, ...subject } : null;
+}
+
+// Collapse the namespace's membership tuples → distinct groups + member counts, sorted by name.
+export function groupsFromTuples(tuples: RelationTuple[]): GroupView[] {
+  const counts = new Map<string, number>();
+  for (const t of tuples) counts.set(t.object, (counts.get(t.object) ?? 0) + 1);
+  return [...counts].map(([name, memberCount]) => ({ memberCount, name })).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function memberView(tuple: RelationTuple, emailById: Map<string, string>): MemberView {
+  if (tuple.subject_set) return { kind: "group", label: tuple.subject_set.object, subject: `group:${tuple.subject_set.object}` };
+  const subjectId = tuple.subject_id ?? "";
+  const id = subjectId.startsWith("user:") ? subjectId.slice("user:".length) : subjectId;
+  return { kind: "user", label: emailById.get(id) ?? subjectId, subject: subjectId };
+}
+
+// ---- list view model ----
+
+interface ListState {
+  page: number;
+  pageSize: number;
+  q: string;
+  sort: string | null;
+}
+
+const SORT: Record<string, (g: GroupView) => number | string> = {
+  members: (g) => g.memberCount,
+  name: (g) => g.name,
+};
+const COLUMNS = [
+  { key: "name", label: "Group" },
+  { key: "members", label: "Members" },
+];
+
+function detailHref(name: string): string {
+  return `${ADMIN_GROUPS_BASE}/${encodeURIComponent(name)}`;
+}
+
+function listHref(state: ListState, overrides: Partial<ListState> = {}): string {
+  const s = { ...state, ...overrides };
+  const p = new URLSearchParams();
+  if (s.q) p.set("q", s.q);
+  if (s.sort) p.set("sort", s.sort);
+  if (s.page > 1) p.set("page", String(s.page));
+  if (s.pageSize !== DEFAULT_PAGE_SIZE) p.set("pageSize", String(s.pageSize));
+  const qs = p.toString();
+  return qs ? `${ADMIN_GROUPS_BASE}?${qs}` : ADMIN_GROUPS_BASE;
+}
+
+export function buildGroupsListModel(opts: {
+  csrfToken?: string;
+  groups: GroupView[];
+  menu?: MenuConfig;
+  url: URL | URLSearchParams | string;
+  user?: User | null;
+}) {
+  const menu = opts.menu ?? DEFAULT_MENU;
+  const query = parseListQuery(opts.url, { defaultPageSize: DEFAULT_PAGE_SIZE });
+  const sort = query.sort && SORT[query.sort.field] ? query.sort : null;
+  const sortToken = sort ? (sort.dir === "desc" ? `-${sort.field}` : sort.field) : null;
+  const needle = query.q.toLowerCase();
+
+  let list = opts.groups.filter((g) => !needle || g.name.toLowerCase().includes(needle));
+  if (sort) {
+    const get = SORT[sort.field]!;
+    const dir = sort.dir === "desc" ? -1 : 1;
+    list = [...list].sort((a, b) => {
+      const av = get(a), bv = get(b);
+      const cmp = typeof av === "number" && typeof bv === "number" ? av - bv : String(av).localeCompare(String(bv));
+      return cmp * dir;
+    });
+  }
+
+  const page = paginate(list.length, query.page, query.pageSize, { boundaries: 1, siblings: 1 });
+  const start = (page.page - 1) * page.pageSize;
+  const rows = list.slice(start, start + page.pageSize);
+  const state: ListState = { page: page.page, pageSize: page.pageSize, q: query.q, sort: sortToken };
+
+  return {
+    filterBar: listFilterBar(state),
+    nav: adminNav(opts.user?.roles ?? [], menu, "groups"),
+    pagination: listPagination(state, page),
+    shell: buildShellContext({
+      breadcrumbs: [{ href: ADMIN_GROUPS_BASE, label: "Admin" }, { label: "Groups" }],
+      csrfToken: opts.csrfToken ?? "",
+      menu,
+      title: "Groups",
+      user: opts.user ?? null,
+    }),
+    table: listTable(rows, state, sort),
+  };
+}
+
+function listTable(rows: GroupView[], state: ListState, sort: { dir: "asc" | "desc"; field: string } | null) {
+  return {
+    caption: "Groups",
+    columns: COLUMNS.map((c) => {
+      const dir = sort && sort.field === c.key ? sort.dir : undefined;
+      const next = dir === "asc" ? `-${c.key}` : c.key;
+      return { href: listHref(state, { page: 1, sort: next }), label: c.label, sort: dir, sortable: true };
+    }),
+    rows: rows.map((g) => ({
+      cells: [{ rowHeader: { href: detailHref(g.name), text: g.name } }, String(g.memberCount)],
+      name: g.name,
+    })),
+  };
+}
+
+function listFilterBar(state: ListState) {
+  const pills: { label: string; remove: string; value: string }[] = [];
+  if (state.q) pills.push({ label: "Search", remove: listHref(state, { page: 1, q: "" }), value: state.q });
+  return {
+    applyLabel: "Apply",
+    clearHref: ADMIN_GROUPS_BASE,
+    label: "Filter groups",
+    pills,
+    rows: [[
+      { label: "Search groups", name: "q", placeholder: "Search group name…", type: "search", value: state.q },
+      { type: "spacer" },
+    ]],
+  };
+}
+
+function listPagination(state: ListState, page: ReturnType<typeof paginate>) {
+  const hidden: { name: string; value: string }[] = [];
+  if (state.q) hidden.push({ name: "q", value: state.q });
+  if (state.sort) hidden.push({ name: "sort", value: state.sort });
+  return {
+    label: "Groups pagination",
+    next: { href: page.next ? listHref(state, { page: page.next }) : undefined },
+    pages: page.pages.map((p) =>
+      p.ellipsis ? { ellipsis: true }
+        : p.current ? { current: true, label: String(p.page) }
+          : { href: listHref(state, { page: p.page as number }), label: String(p.page) }),
+    prev: { href: page.prev ? listHref(state, { page: page.prev }) : undefined },
+    rows: { hidden, label: "Rows", name: "pageSize", options: PAGE_SIZES, submitLabel: "Go", value: state.pageSize },
+    summary: { from: page.from, to: page.to, total: page.total },
+  };
+}
+
+// ---- create form + detail view models ----
+
+export function buildGroupFormModel(opts: {
+  csrfToken?: string;
+  error?: string;
+  memberOptions: MemberOption[];
+  menu?: MenuConfig;
+  user?: User | null;
+  values?: { member?: string; name?: string };
+}) {
+  const menu = opts.menu ?? DEFAULT_MENU;
+  const nameField: FieldConfig = {
+    autocomplete: "off", hint: "Lowercase letters, digits, dashes and underscores.", icon: "i-layers",
+    id: "name", label: "Group name", name: "name", required: true, value: opts.values?.name ?? "",
+  };
+  return {
+    error: opts.error,
+    form: {
+      action: ADMIN_GROUPS_BASE,
+      cancelHref: ADMIN_GROUPS_BASE,
+      csrfToken: opts.csrfToken ?? "",
+      memberOptions: opts.memberOptions,
+      nameField,
+      selectedMember: opts.values?.member ?? "",
+      submitLabel: "Create group",
+    },
+    nav: adminNav(opts.user?.roles ?? [], menu, "groups"),
+    shell: buildShellContext({
+      breadcrumbs: [{ href: ADMIN_GROUPS_BASE, label: "Groups" }, { label: "New" }],
+      csrfToken: opts.csrfToken ?? "",
+      menu,
+      title: "New group",
+      user: opts.user ?? null,
+    }),
+  };
+}
+
+export function buildGroupDetailModel(opts: {
+  candidates: MemberOption[];
+  csrfToken?: string;
+  error?: string;
+  group: { name: string };
+  members: MemberView[];
+  menu?: MenuConfig;
+  user?: User | null;
+}) {
+  const menu = opts.menu ?? DEFAULT_MENU;
+  const name = opts.group.name;
+  const base = detailHref(name);
+  const taken = new Set(opts.members.map((m) => m.subject));
+  const self = `group:${name}`; // a group can't be a member of itself
+  const options = opts.candidates.filter((c) => c.value !== self && !taken.has(c.value));
+  return {
+    add: { action: `${base}/members`, options },
+    csrfToken: opts.csrfToken ?? "",
+    delete: { action: `${base}/delete` },
+    error: opts.error,
+    group: { name },
+    members: { action: `${base}/members/delete`, rows: opts.members },
+    nav: adminNav(opts.user?.roles ?? [], menu, "groups"),
+    shell: buildShellContext({
+      breadcrumbs: [{ href: ADMIN_GROUPS_BASE, label: "Groups" }, { label: name }],
+      csrfToken: opts.csrfToken ?? "",
+      menu,
+      title: name,
+      user: opts.user ?? null,
+    }),
+  };
+}
+
+// ---- request handler (imperative shell) ----
+
+export interface AdminGroupsDeps {
+  csrfSecret: string;
+  keto: KetoClient;
+  kratosAdmin: KratosAdmin;
+  menu: MenuConfig;
+  render: (view: string, data: Record<string, unknown>) => Promise<string>;
+}
+
+// Drain every page of a relation-tuple query.
+async function pagedTuples(keto: KetoClient, query: RelationQuery): Promise<RelationTuple[]> {
+  const out: RelationTuple[] = [];
+  let pageToken: string | undefined;
+  do {
+    const page = await keto.listRelations({ ...query, ...(pageToken ? { pageToken } : {}) });
+    out.push(...page.tuples);
+    pageToken = page.nextPageToken ?? undefined;
+  } while (pageToken);
+  return out;
+}
+
+// Build the member-picker options (every user by email + every existing group) and the id→email map
+// detail rows render with. One Kratos page + one Keto scan; ample for an admin tool.
+async function memberCandidates(keto: KetoClient, kratosAdmin: KratosAdmin): Promise<{ emailById: Map<string, string>; options: MemberOption[] }> {
+  const { identities } = await kratosAdmin.listIdentities({ pageSize: LIST_FETCH_SIZE });
+  const emailById = new Map<string, string>();
+  const userOptions: MemberOption[] = [];
+  for (const it of identities) {
+    const trait = it.traits?.["email"];
+    const email = typeof trait === "string" ? trait : it.id;
+    emailById.set(it.id, email);
+    userOptions.push({ label: email, value: `user:${it.id}` });
+  }
+  const groups = groupsFromTuples(await pagedTuples(keto, { namespace: GROUP_NS, relation: MEMBERS }));
+  return { emailById, options: [...userOptions, ...groups.map((g) => ({ label: `${g.name} (group)`, value: `group:${g.name}` }))] };
+}
+
+// A group exists exactly while it has ≥1 member.
+async function groupExists(keto: KetoClient, name: string): Promise<boolean> {
+  const page = await keto.listRelations({ namespace: GROUP_NS, object: name, relation: MEMBERS, pageSize: 1 });
+  return page.tuples.length > 0;
+}
+
+// Decode a path segment without letting malformed %-encoding throw (→ caller treats it as not found).
+function safeDecode(seg: string): string | null {
+  try { return decodeURIComponent(seg); } catch { return null; }
+}
+
+export async function handleAdminGroups(ctx: RequestContext, csrfToken: string, deps: AdminGroupsDeps): Promise<RouteResult | null> {
+  const path = ctx.url.pathname;
+  if (path !== ADMIN_GROUPS_BASE && !path.startsWith(`${ADMIN_GROUPS_BASE}/`)) return null;
+
+  if (!ctx.user) throw new GuardError(401, "authentication required", "/login");
+  if (!ctx.roles.includes(ADMIN_PERMISSION)) throw new GuardError(403, "admin role required");
+
+  const { keto, kratosAdmin, menu, render } = deps;
+  const user = ctx.user;
+  const method = (ctx.req.method ?? "GET").toUpperCase();
+  const seg = path.slice(ADMIN_GROUPS_BASE.length).split("/").filter(Boolean);
+
+  let form: URLSearchParams | undefined;
+  if (method === "POST") {
+    form = await readFormBody(ctx.req);
+    if (!verifyCsrfRequest({ cookieHeader: ctx.req.headers.cookie, secret: deps.csrfSecret, submitted: form.get(CSRF_FIELD) })) {
+      throw new GuardError(403, "invalid CSRF token");
+    }
+  }
+
+  const renderList = async (): Promise<RouteResult> => {
+    const groups = groupsFromTuples(await pagedTuples(keto, { namespace: GROUP_NS, relation: MEMBERS }));
+    return { html: await render("admin/groups", { model: buildGroupsListModel({ csrfToken, groups, menu, url: ctx.url, user }) }) };
+  };
+  const renderForm = async (extra: { error?: string; values?: { member?: string; name?: string } }): Promise<RouteResult> => {
+    const { options } = await memberCandidates(keto, kratosAdmin);
+    return { html: await render("admin/group-form", { model: buildGroupFormModel({ csrfToken, memberOptions: options, menu, user, ...extra }) }) };
+  };
+  const renderDetail = async (name: string): Promise<RouteResult> => {
+    const { emailById, options } = await memberCandidates(keto, kratosAdmin);
+    const members = (await pagedTuples(keto, { namespace: GROUP_NS, object: name, relation: MEMBERS })).map((t) => memberView(t, emailById));
+    return { html: await render("admin/group-detail", { model: buildGroupDetailModel({ candidates: options, csrfToken, group: { name }, members, menu, user }) }) };
+  };
+
+  // /admin/groups — list (GET) · create (POST)
+  if (seg.length === 0) {
+    if (method === "GET") return renderList();
+    if (method === "POST") {
+      const name = (form!.get("name") ?? "").trim();
+      const tuple = memberTuple(name, (form!.get("member") ?? "").trim());
+      const reject = (error: string): Promise<RouteResult> =>
+        renderForm({ error, values: { member: form!.get("member") ?? "", name } }).then((r) => ({ ...r, status: 400 }));
+      if (!isValidGroupName(name)) return reject("Group names use lowercase letters, digits, dashes and underscores.");
+      if (!tuple) return reject("Pick a member to add as the group's first member.");
+      if (await groupExists(keto, name)) return reject("A group with that name already exists.");
+      await keto.writeTuple(tuple);
+      return { redirect: detailHref(name) };
+    }
+    return null;
+  }
+
+  // /admin/groups/new — create form
+  if (seg.length === 1 && seg[0] === "new" && method === "GET") return renderForm({});
+
+  // /admin/groups/:name …
+  const name = safeDecode(seg[0]!);
+  if (name === null || !isValidGroupName(name)) return { html: await render("404", { title: "Not found" }), status: 404 };
+  const base = detailHref(name);
+
+  if (seg.length === 1 && method === "GET") return renderDetail(name);
+
+  if (seg.length === 2 && seg[1] === "members" && method === "POST") {
+    const tuple = memberTuple(name, (form!.get("member") ?? "").trim());
+    // Skip an invalid member or a self-nest (the picker already excludes both).
+    if (tuple && tuple.subject_set?.object !== name) await keto.writeTuple(tuple);
+    return { redirect: base };
+  }
+  if (seg.length === 2 && seg[1] === "delete" && method === "POST") {
+    await keto.deleteTuple({ namespace: GROUP_NS, object: name, relation: MEMBERS }); // removes every member tuple
+    return { redirect: ADMIN_GROUPS_BASE };
+  }
+  if (seg.length === 3 && seg[1] === "members" && seg[2] === "delete" && method === "POST") {
+    const tuple = memberTuple(name, (form!.get("member") ?? "").trim());
+    if (tuple) await keto.deleteTuple(tuple);
+    return { redirect: base };
+  }
+  return null;
+}

src/admin-nav.ts

@@ -0,0 +1,23 @@
+// Shared sidebar nav for the built-in admin screens (todo §5). Both the Users and Groups
+// screens render the same admin section (Dashboard · Users · Groups), with `current` set on the
+// active item. Extracted so the two screens can't drift. The global config-driven menu wiring
+// (an admin section gated per user) is the separate §5 menu item; this is the local in-screen nav.
+
+import { type MenuConfig } from "./menu-config.ts";
+import { composeNav, type NavNode } from "./nav.ts";
+
+export const ADMIN_PERMISSION = "admin"; // role token gating every admin screen
+export const ADMIN_USERS_BASE = "/admin/users";
+export const ADMIN_GROUPS_BASE = "/admin/groups";
+
+type AdminScreen = "dashboard" | "groups" | "users";
+
+export function adminNav(roles: string[], menu: MenuConfig, current: AdminScreen): NavNode[] {
+  const gated = (id: AdminScreen, href: string, icon: string, label: string): NavNode =>
+    ({ ...(current === id ? { current: true } : {}), href, icon, id, label, permission: ADMIN_PERMISSION });
+  return composeNav([[
+    { href: "/", icon: "i-grid", id: "dashboard", label: "Dashboard" },
+    gated("users", ADMIN_USERS_BASE, "i-users", "Users"),
+    gated("groups", ADMIN_GROUPS_BASE, "i-layers", "Groups"),
+  ]], menu.override, roles);
+}

src/admin-users.ts

@@ -5,6 +5,7 @@
 // imperative shell app.ts dispatches to — it gates (admin only), CSRF-guards every mutation, and
 // maps each action to a RouteResult (render a page, or redirect after a write — PRG).
 
+import { ADMIN_PERMISSION, ADMIN_USERS_BASE, adminNav } from "./admin-nav.ts";
 import { readFormBody } from "./body.ts";
 import type { RequestContext, User } from "./context.ts";
 import { CSRF_FIELD, verifyCsrfRequest } from "./csrf.ts";
@@ -13,13 +14,10 @@ import type { Identity, KratosAdmin, RecoveryCode } from "./kratos-admin.ts";
 import { KratosError } from "./kratos-public.ts";
 import { parseListQuery } from "./list-query.ts";
 import { DEFAULT_MENU, type MenuConfig } from "./menu-config.ts";
-import { composeNav, type NavNode } from "./nav.ts";
 import { paginate } from "./paginate.ts";
 import type { RouteResult } from "./plugin.ts";
 import { buildShellContext } from "./shell-context.ts";
 
-export const ADMIN_USERS_BASE = "/admin/users";
-export const ADMIN_PERMISSION = "admin"; // role token gating every admin screen
 const SCHEMA_ID = "default"; // matches kratos.yml identity.default_schema_id
 const DEFAULT_PAGE_SIZE = 25;
 const PAGE_SIZES = [25, 50, 100];
@@ -106,13 +104,6 @@ const COLUMNS = [
   { key: "status", label: "Status" },
 ];
 
-function adminNav(roles: string[], menu: MenuConfig, currentId: string): NavNode[] {
-  return composeNav([[
-    { href: "/", icon: "i-grid", id: "dashboard", label: "Dashboard" },
-    { ...(currentId === "users" ? { current: true } : {}), href: ADMIN_USERS_BASE, icon: "i-users", id: "users", label: "Users", permission: ADMIN_PERMISSION },
-  ]], menu.override, roles);
-}
-
 // Canonical list URL from the current state + per-link overrides; omits defaults so links stay tidy.
 function listHref(state: ListState, overrides: Partial<ListState> = {}): string {
   const s = { ...state, ...overrides };

src/app.test.ts

@@ -10,7 +10,7 @@ import { createApp } from "./app.ts";
 import { CSRF_COOKIE, issueCsrfToken } from "./csrf.ts";
 import { can, check, GuardError, requireSession } from "./guards.ts";
 import { staticJwks } from "./jwks.ts";
-import type { KetoClient } from "./keto-client.ts";
+import type { KetoClient, RelationTuple, SubjectSet } from "./keto-client.ts";
 import type { Identity, KratosAdmin } from "./kratos-admin.ts";
 import { KratosError, type Flow, type FlowType, type KratosPublic, type Session, type UiNode } from "./kratos-public.ts";
 import { SESSION_COOKIE } from "./login.ts";
@@ -532,6 +532,90 @@ test("admin Users screen: gate, list/filter, create, edit, deactivate, delete, r
   assert.equal((await get(`/admin/users/${randomUUID()}`)).status, 404);
 });
 
+// Built-in Groups admin screen (§5): gate + list/create/membership/delete over HTTP against a
+// fake in-memory Keto (tuples are the only state) and a stub Kratos admin (resolves member emails).
+const sameSet = (a?: SubjectSet, b?: SubjectSet): boolean =>
+  (!a && !b) || (!!a && !!b && a.namespace === b.namespace && a.object === b.object && a.relation === b.relation);
+const matchesTuple = (t: RelationTuple, f: Partial<RelationTuple>): boolean =>
+  (f.namespace === undefined || t.namespace === f.namespace) &&
+  (f.object === undefined || t.object === f.object) &&
+  (f.relation === undefined || t.relation === f.relation) &&
+  (f.subject_id === undefined || t.subject_id === f.subject_id) &&
+  (f.subject_set === undefined || sameSet(t.subject_set, f.subject_set));
+
+test("admin Groups screen: gate, list, create, detail/membership, delete (CSRF-guarded)", async (t) => {
+  const ada = "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b01";
+  const grace = "01902d5e-7b6c-7e3a-9f21-3c8d1e0a4b02";
+  const identities: Identity[] = [
+    { id: ada, schema_id: "default", state: "active", traits: { email: "ada@example.com" } },
+    { id: grace, schema_id: "default", state: "active", traits: { email: "grace@example.com" } },
+  ];
+  const tuples: RelationTuple[] = [{ namespace: "Group", object: "eng", relation: "members", subject_id: `user:${ada}` }];
+  const keto: KetoClient = {
+    check: async () => false,
+    deleteTuple: async (f) => { for (let i = tuples.length - 1; i >= 0; i--) if (matchesTuple(tuples[i]!, f)) tuples.splice(i, 1); },
+    expand: async () => ({ type: "leaf" }),
+    listRelations: async (q = {}) => ({ nextPageToken: null, tuples: tuples.filter((t) => matchesTuple(t, q)) }),
+    writeTuple: async (tp) => { if (!tuples.some((t) => matchesTuple(t, tp) && sameSet(t.subject_set, tp.subject_set))) tuples.push(tp); },
+  };
+  const kratosAdmin = stubAdmin({ listIdentities: async () => ({ identities, nextPageToken: null }) });
+  const csrfSecret = "groups-secret";
+  const app = createApp({ csrfSecret, jwks: staticJwks([ecJwk]), keto, kratosAdmin });
+  await new Promise<void>((r) => app.listen(0, r));
+  t.after(() => app.close());
+  const url = `http://localhost:${(app.address() as AddressInfo).port}`;
+  const nowSec = Math.floor(Date.now() / 1000);
+  const token = issueCsrfToken(csrfSecret);
+  const cookie = (roles: string[]) => `${SESSION_COOKIE}=${mintJwt({ email: "admin@x", exp: nowSec + 600, roles, sub: "admin1" })}; ${CSRF_COOKIE}=${token}`;
+  const get = (path: string, roles: string[] = ["admin"]) => fetch(url + path, { headers: { cookie: cookie(roles) }, redirect: "manual" });
+  const post = (path: string, body: string) =>
+    fetch(url + path, { body, headers: { "content-type": "application/x-www-form-urlencoded", cookie: cookie(["admin"]) }, method: "POST", redirect: "manual" });
+
+  // Gate: anonymous → /login; a signed-in non-admin → 403.
+  const anon = await fetch(url + "/admin/groups", { redirect: "manual" });
+  assert.equal(anon.status, 303);
+  assert.equal(anon.headers.get("location"), "/login");
+  assert.equal((await get("/admin/groups", [])).status, 403);
+
+  // List: the existing group shows + the "add" link.
+  const listHtml = await (await get("/admin/groups")).text();
+  assert.match(listHtml, /href="\/admin\/groups\/eng"/);
+  assert.match(listHtml, /href="\/admin\/groups\/new"/);
+
+  // Create: the form renders; a valid post writes the first-member tuple and redirects to the detail.
+  assert.match(await (await get("/admin/groups/new")).text(), /Create group/);
+  const created = await post("/admin/groups", `_csrf=${token}&name=design&member=user:${grace}`);
+  assert.equal(created.status, 303);
+  assert.equal(created.headers.get("location"), "/admin/groups/design");
+  assert.ok(tuples.some((tp) => tp.object === "design" && tp.subject_id === `user:${grace}`));
+
+  // An invalid name, a duplicate name, or a missing CSRF token are all refused, nothing written.
+  const before = tuples.length;
+  assert.equal((await post("/admin/groups", `_csrf=${token}&name=Bad Name&member=user:${grace}`)).status, 400);
+  assert.equal((await post("/admin/groups", `_csrf=${token}&name=eng&member=user:${grace}`)).status, 400); // already exists
+  assert.equal((await post("/admin/groups", `name=x&member=user:${grace}`)).status, 403);
+  assert.equal(tuples.length, before);
+
+  // Detail: lists the current member by email.
+  assert.match(await (await get("/admin/groups/eng")).text(), /ada@example\.com/);
+
+  // Add a member, then remove it.
+  await post("/admin/groups/eng/members", `_csrf=${token}&member=user:${grace}`);
+  assert.ok(tuples.some((tp) => tp.object === "eng" && tp.subject_id === `user:${grace}`));
+  await post("/admin/groups/eng/members/delete", `_csrf=${token}&member=user:${grace}`);
+  assert.ok(!tuples.some((tp) => tp.object === "eng" && tp.subject_id === `user:${grace}`));
+
+  // Delete the group: removes every member tuple, back to the list.
+  const del = await post("/admin/groups/eng/delete", `_csrf=${token}`);
+  assert.equal(del.status, 303);
+  assert.equal(del.headers.get("location"), "/admin/groups");
+  assert.ok(!tuples.some((tp) => tp.object === "eng"));
+
+  // An invalid group name in the path → 404; malformed %-encoding doesn't 500.
+  assert.equal((await get("/admin/groups/Bad%20Name")).status, 404);
+  assert.equal((await get("/admin/groups/%ZZ")).status, 404);
+});
+
 test("resolveStaticPath blocks traversal and control chars, allows nested files", () => {
   assert.equal(resolveStaticPath("/srv/public", "../app.ts"), null);
   assert.equal(resolveStaticPath("/srv/public", "a\x00b"), null);

src/app.ts

@@ -3,7 +3,9 @@ import { createServer, type Server, type ServerResponse } from "node:http";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as ejs from "ejs";
-import { ADMIN_USERS_BASE, type AdminUsersDeps, handleAdminUsers } from "./admin-users.ts";
+import { ADMIN_GROUPS_BASE, ADMIN_USERS_BASE } from "./admin-nav.ts";
+import { type AdminGroupsDeps, handleAdminGroups } from "./admin-groups.ts";
+import { type AdminUsersDeps, handleAdminUsers } from "./admin-users.ts";
 import { readFormBody } from "./body.ts";
 import { buildContext, type User } from "./context.ts";
 import { CSRF_FIELD, csrfCookie, ensureCsrfToken, verifyCsrfRequest } from "./csrf.ts";
@@ -72,9 +74,11 @@ export function createApp(options: AppOptions = {}): Server {
   // building-block partials (resolved from viewsDir) and their own partials/subfolders.
   const renderView = renderPluginView({ cache, coreViewsDir: viewsDir, pluginsDir });
 
-  // Built-in admin screens (§5) — wired only when the Kratos admin client is present (the writes
+  // Built-in admin screens (§5) — wired only when their Ory clients are present (the writes go
-  // go there). They render core views via `render` and are gated/CSRF-guarded inside the handler.
+  // there). They render core views via `render` and are gated/CSRF-guarded inside the handler.
+  // Users writes to Kratos; Groups writes to Keto and reads users from Kratos for the pickers.
   const adminDeps: AdminUsersDeps | null = kratosAdmin ? { csrfSecret, kratosAdmin, menu, render } : null;
+  const adminGroupsDeps: AdminGroupsDeps | null = kratosAdmin && keto ? { csrfSecret, keto, kratosAdmin, menu, render } : null;
 
   const sendHtml = (res: ServerResponse, status: number, html: string): void => {
     res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
@@ -143,9 +147,9 @@ export function createApp(options: AppOptions = {}): Server {
         return;
       }
 
-      // Built-in Users admin screens (§5). The handler gates (admin only; throws GuardError the
+      // Built-in admin screens (§5). Each handler gates (admin only; throws GuardError the catch
-      // catch maps), CSRF-guards mutations, and returns html/redirect. Set the page's CSRF cookie
+      // maps), CSRF-guards mutations, and returns html/redirect. Set the page's CSRF cookie when
-      // when freshly minted (its forms carry the matching token); null ⇒ unknown subpath → 404.
+      // freshly minted (its forms carry the matching token); null ⇒ unknown subpath → 404.
       if (adminDeps && pathname.startsWith(ADMIN_USERS_BASE)) {
         const result = await handleAdminUsers(ctx, csrf.token, adminDeps);
         if (result) {
@@ -154,6 +158,14 @@ export function createApp(options: AppOptions = {}): Server {
           return;
         }
       }
+      if (adminGroupsDeps && pathname.startsWith(ADMIN_GROUPS_BASE)) {
+        const result = await handleAdminGroups(ctx, csrf.token, adminGroupsDeps);
+        if (result) {
+          if (csrf.fresh) res.appendHeader("set-cookie", csrfCookie(csrf.token, { secure: secureCookies }));
+          await sendResult(res, result, () => Promise.reject(new Error("admin screens return html, not view")));
+          return;
+        }
+      }
 
       // Themed Kratos self-service pages (login/registration/recovery/verification/settings).
       const flowType = AUTH_FLOWS[pathname];

src/data-table.test.ts

@@ -68,6 +68,13 @@ test("data-table renders sortable headers, row-select, typed cells, badges and k
   assert.match(html, /<div class="menu-sep"><\/div><button class="menu-item danger" type="button"><svg class="ico"><use href="#i-trash"\s*\/?><\/svg>Delete<\/button>/);
 });
 
+test("data-table rowHeader cell is a <th scope=row> identifier — a link when given href, else plain text", async () => {
+  const linked = flat(await render({ columns: [{ label: "Group" }], rows: [{ cells: [{ rowHeader: { href: "/admin/groups/eng", text: "eng" } }] }] }));
+  assert.match(linked, /<th scope="row"><a class="cell-strong" href="\/admin\/groups\/eng">eng<\/a><\/th>/);
+  const plain = flat(await render({ columns: [{ label: "Group" }], rows: [{ cells: [{ rowHeader: { text: "eng" } }] }] }));
+  assert.match(plain, /<th scope="row"><span class="cell-strong">eng<\/span><\/th>/);
+});
+
 test("data-table renders a minimal table (plain string cells, no select/actions) and never throws", async () => {
   const html = flat(await render({ columns: [{ label: "Name" }], rows: [{ cells: ["Plain"] }] }));
   assert.match(html, /<table class="table"><thead><tr><th scope="col">Name<\/th><\/tr><\/thead><tbody><tr><td>Plain<\/td><\/tr><\/tbody><\/table>/);

todo.md

@@ -1,5 +1,7 @@
 # Plainpages — implementation TODO
 
+General instruction - always run the stability reviewer after each todo is done.
+
 Build order is top → bottom; each phase is roughly independent and testable.
 Conventions: **write tests first** (node --test for units, Playwright for E2E),
 tear down test containers after runs, keep deps minimal, pin all versions, run
@@ -17,7 +19,7 @@ everything via Docker.
 - [x] Request context type threaded to handlers: `{ req, res, url, params, query, user|null, roles }`. → `src/context.ts` (`RequestContext` + `buildContext`); `roles` mirror `user.roles`, the §2 router/§4 JWT middleware supply `params`/`user`.
 - [x] Error templates: add 403 + 500 (404 exists). → `views/403.ejs` + `views/500.ejs`; 500 wired into `app.ts` error handler (HTML, plain-text fallback).
 - [x] Config/env loader: Ory endpoints, cookie/CSRF secret, JWKS location, ports. → `src/config.ts` (`loadConfig`); validated at boot, dev defaults for clean-clone, prod requires real secrets; wired into `server.ts`.
-- [x] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues. → Both: no bugs/security issues. Addressed: wired `buildContext` into `app.ts`; graceful SIGTERM/SIGINT shutdown; EJS template caching in prod. Deferred `core/`/`shell/` split (premature for an 8-file scaffold; revisit at §2/§4).
+- [x] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues. → Both: no bugs/security issues. Addressed: wired `buildContext` into `app.ts`; graceful SIGTERM/SIGINT shutdown; EJS template caching in prod. Deferred `core/`/`shell/` split (premature for an 8-file scaffold; revisit at §2/§4).
 - [x] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff. → Tightened comments across `src/*.ts`, Dockerfile, and trimmed verbose/duplicated prose in README; tests + typecheck green.
 - [x] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us. → Merged related cases across jwt/cookie/app/context/config tests (59 → 42), every assertion preserved; typecheck + tests green.
 
@@ -52,7 +54,7 @@ everything via Docker.
 - [x] Per-plugin static serving: `plugins/<id>/public/` → `/public/<id>/`. → `routePublic` (pure, in `src/static.ts`), wired into `app.ts`'s existing `/public/` branch. A request `/public/<rest>` whose leading segment names a discovered plugin serves from `plugins/<id>/public/<rest>`; anything else (e.g. `css/styles.css`) stays on the core `public/`. Disambiguates by the discovered plugin-id set, so only mounted plugins expose assets and core paths are unaffected; plugin ids are URL-safe so the raw segment compares directly (no decode needed). Reuses `serveStatic` unchanged, so the sub-path keeps its decode + traversal/control-char guard (encoded `..` ⇒ 403) and HEAD support; a missing `public/` or file ⇒ 404. Tests-first: a `routePublic` unit (plugin/core split, nested asset, bare `/public/<id>`) + the `app.test.ts` plugin integration now serves a real `demo/public/app.css` (200 + `text/css`) and still 403s a traversal; typecheck + 103 units green. `config/menu.ts` central override is the next §2 item.
 - [x] `config/menu.ts` central override: reorder/rename/hide/group + branding (app name, logo, default theme). → `src/menu-config.ts` (`MenuConfig`/`Branding`/`MenuConfigInput`, `defineMenu()` identity helper, `DEFAULT_MENU`, `loadMenuConfig()`) + the operator file `config/menu.ts`. The override is `composeNav`'s existing `NavOverride` (reorder/rename/group/hide by node id, applied before the per-user filter); branding = `{ name, logo?, sub?, theme? }`. `loadMenuConfig` (imperative shell) dynamically imports `config/menu.ts` if present, validates the authored shape fail-loud (branding field types + `theme` enum, override `hide`/`order` string-arrays / `groups` array / `rename` object), merges branding over defaults; **absent file ⇒ `DEFAULT_MENU`** (clean clone). Wired: `server.ts` loads it at boot → `createApp({ menu })` → `buildDashboardModel(url, roles, menu)` feeds `menu.override` into `composeNav` and `menu.branding` (name/sub) into the shell brand. `config/menu.ts` ships defaults matching prior behaviour (name "Plainpages"/sub "Console", empty override), so a clean clone is unchanged. Added `config` to tsconfig `include` so the authored file is type-checked (Dockerfile `COPY . .` already bakes it). Tests-first: `menu-config.test.ts` (absent⇒defaults / read+merge / malformed⇒throws) + a `dashboard.test.ts` case asserting rename+hide+branding take effect; typecheck (incl. `config/`) + 107 units green; smoke-loaded the real file at boot. **Rendering branding (logo, default theme) into the app shell is the next §2 item.**
 - [x] Wire branding into the app shell. → Completes the §2 branding chain (name/sub already flowed). `shell.ejs` now renders `brand.logo` as `<img class="brand-logo" alt="">` when set, else the default `#i-box` brand-mark; the `theme` local (already forwarded to the theme-switch) is now supplied. `buildDashboardModel` puts `menu.branding.logo` into `shell.brand` and `menu.branding.theme` into `shell.theme` (both omitted when unset, so a clean clone is unchanged → brand-mark + auto theme); `views/index.ejs` forwards `theme` to the shell. Added a `.brand-logo` CSS rule (22px, matches `.brand-mark` sizing). Tests-first: `shell.test.ts` (logo replaces the mark + default theme checked; no-logo ⇒ mark + auto) + extended `dashboard.test.ts` (logo→brand, theme→shell.theme) + an `app.test.ts` integration rendering `createApp({ menu })` end-to-end (logo `<img>` + `theme-dark` checked on `/`). Default-app shell rendering is byte-equivalent, so the visual E2E is unaffected; typecheck + 109 units green. The §2 plugin host is feature-complete (remaining §2 items are the project-wide review + comment/test cleanup).
-- [x] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues. → Ran both on all of `src/`, `views/`, `config/`, Docker/tsconfig. Verdict: architecture sound + disciplined, no crash/security defect in the current path (fail-loud, traversal guards, JWT/cookie defenses all confirmed). **Fixed now:** (1) HIGH — `PluginHooks` was typed+documented but never invoked; wired it (`src/hooks.ts`: `runBootHooks`/`runRequestHooks`/`runResponseHooks`) — `server.ts` runs `onBoot` after discovery before listen, `app.ts` runs `onRequest` (before routing, first non-void short-circuits, renders against its plugin) + `onResponse` (after handler, observer, throw→500); skipped entirely when no plugin declares a hook (hot path free); `hooks.test.ts` + an `app.test.ts` integration. (2) `discovery.ts` `fail` helper retyped `: void`. (3) Documented the template trust boundary in `docs/plugin-contract.md` (raw `html`/`*.html` fields; URL sinks escaped but not scheme-checked) + tightened the Hooks prose to the wired semantics. **Deferred (reviewer-scoped, not §2):** extract a shared `buildShellContext` out of `dashboard.ts` and route the built-in screens through `matchRoute`/`isAuthorized` → §5 (premature at one call site); a `safeUrl()` helper for href sinks → §4 (no untrusted URLs until upstream data flows); doc/type-duplication + non-local `§N` refs → the §2 comment-cleanup item; HEAD-render cost + dev empty-secret fallback → negligible. typecheck + 113 units green; boot smoke-tested.
+- [x] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues. → Ran both on all of `src/`, `views/`, `config/`, Docker/tsconfig. Verdict: architecture sound + disciplined, no crash/security defect in the current path (fail-loud, traversal guards, JWT/cookie defenses all confirmed). **Fixed now:** (1) HIGH — `PluginHooks` was typed+documented but never invoked; wired it (`src/hooks.ts`: `runBootHooks`/`runRequestHooks`/`runResponseHooks`) — `server.ts` runs `onBoot` after discovery before listen, `app.ts` runs `onRequest` (before routing, first non-void short-circuits, renders against its plugin) + `onResponse` (after handler, observer, throw→500); skipped entirely when no plugin declares a hook (hot path free); `hooks.test.ts` + an `app.test.ts` integration. (2) `discovery.ts` `fail` helper retyped `: void`. (3) Documented the template trust boundary in `docs/plugin-contract.md` (raw `html`/`*.html` fields; URL sinks escaped but not scheme-checked) + tightened the Hooks prose to the wired semantics. **Deferred (reviewer-scoped, not §2):** extract a shared `buildShellContext` out of `dashboard.ts` and route the built-in screens through `matchRoute`/`isAuthorized` → §5 (premature at one call site); a `safeUrl()` helper for href sinks → §4 (no untrusted URLs until upstream data flows); doc/type-duplication + non-local `§N` refs → the §2 comment-cleanup item; HEAD-render cost + dev empty-secret fallback → negligible. typecheck + 113 units green; boot smoke-tested.
 - [x] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff. → Pass over the §2 accretion (the §0/§1 cleanup at line 21 stands). Tightened the verbose module-header blocks (`plugin.ts`, `discovery.ts`, `router.ts`, `dashboard.ts`) and collapsed the `checkApiVersion` rule comment to a one-liner that points at the contract doc (the if-chain + messages already document it). Removed now-stale forward-refs ("router wiring is the next §2 item", "rendered in the shell — next §2 item"). README: corrected the **Status** note (it undersold — §1 design system + the whole §2 plugin host are built, not just a scaffold), dropped the stale `_(planned)_`/"planned to extract" markers on **Building a plugin** and **Building blocks** (both shipped; auth guards still flagged §4), and named the real helpers. Left the security-rationale comments (jwt/cookie/static/paginate) and the EJS partials' config-doc headers intact — they carry vital info / are the only schema for untyped locals. No anchor links broke; typecheck + 113 units green.
 - [x] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us. → Reviewed all 24 test files. The suite already follows the deliberate per-module "matrix + edge" pattern from the §0/§1 merge (line 22), so most files carry no fat and force-merging distinct concerns would only hurt readability. Removed the genuine §2-era overlaps, all in `app.test.ts`: merged the two HTTP static tests into one (GET/HEAD + traversal/NUL→403), and dropped the standalone "renders the 403 error page" `ejs.renderFile` stopgap (its comment even said "403 has no first-party route yet") — the gated plugin route now exercises 403 over HTTP, so the template assertions (status + 403.ejs body + stylesheet link) moved there; also dropped the now-unused `ejs` import. Unified `view-resolver.test.ts`'s two `resolveViewPath` cases (resolve + reject) into one. 113 → 110 tests, zero coverage lost; typecheck + tests green.
 
@@ -70,7 +72,7 @@ everything via Docker.
 - [x] **One-command bootstrap** (the MVP bar): `docker compose up` brings up web + all Ory services + Postgres with *zero* manual prep. Commit working default Ory configs; auto-run migrations on first boot; auto-generate the JWKS signing key if absent; seed an admin identity + its Keto roles + a demo password (`admin`/`admin`) idempotently. Land an `OPL`/namespace bootstrap so Keto answers checks out of the box. → `src/bootstrap.ts` + a one-shot `bootstrap` compose service: runs after kratos+keto are healthy (web gates on its `service_completed_successfully`), idempotent so every `up` re-runs cleanly. (1) `ensureJwks` generates the ES256 signing key (reuses `gen-jwks.ts`) only when the committed dev key is absent — tokenizer dir mounted rw so it can land. (2) `seedAdmin` creates `admin@plainpages.local`/`admin` via the Kratos admin API (a re-run's 409 → look up + reuse the id). (3) grants `Role:admin#members@user:<id>` via the Keto write API (PUT, idempotent) — the source of truth the §4 login flow projects into the JWT. Migrations + default Ory configs already auto-run/committed (§3); OPL/namespaces load from `keto.yml` (§3). The password policy is bypassed by the admin API, so `admin`/`admin` is accepted. Tests-first: `bootstrap.test.ts` (payload builders, seed idempotency via mock fetch, generate-if-absent) + `compose.test.ts` (service wiring). Boot-verified the whole chain on the live stack: `docker compose up --wait` seeds with zero prep, Keto `check` → `allowed:true`, login with `admin@plainpages.local`/`admin` issues a session + tokenizes a JWT; re-run → "already present"; moving the committed key → "generated a JWKS signing key". JWT `roles` stays `[]` until §4 wires the Keto→`metadata_admin` projection. typecheck + 151 units green. The first-run banner (login URL + creds) and the prod-secret/SSO exception docs are the next §3 items.
 - [x] First-run banner / log line printing the login URL + seeded admin creds, with a clear "change these before production" warning. → `firstRunBanner()` in `src/bootstrap.ts` (pure, testable) renders a boxed banner — login URL · seeded email/password · "⚠ change before production" — that `main()` prints after seeding. Login URL from `APP_URL` (compose default `http://localhost:3000`, overridable per deployment); creds reuse the seeded `ADMIN_EMAIL`/`ADMIN_PASSWORD`. Tests-first (`bootstrap.test.ts`: asserts URL + creds + warning present); README **Development** notes the banner. Live-verified: rebuilt bootstrap prints the banner after the admin line; typecheck + 152 units green; stack torn down.
 - [x] Document the *only* things that can't be auto-generated: third-party **SSO provider** client id/secret (optional — password login works without them) and **production secrets** (real cookie/CSRF secret + signing key, supplied via env, replacing the dev throwaways). Everything else must work from a clean clone. → New README **What you must supply (the only manual prep)** subsection (under Configuration) consolidates the previously-scattered facts into one authoritative list: a clean clone needs nothing; exactly two production-only things can't be auto-generated — (1) production secrets (`COOKIE_SECRET`/`CSRF_SECRET` + the JWT signing key, with `REQUIRE_SECURE_SECRETS=true` refusing throwaways) and (2) optional SSO provider creds (no creds ⇒ no button). States everything else (Ory migrations, dev signing key, demo admin + Keto roles, OPL model) is generated/seeded on first boot. Cross-links the existing SSO + JWT-rotation subsections (no duplication) and adds a pointer from **Production / deployment**. All four anchors verified; docs-only — typecheck + 152 units green.
-- [x] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues. → Ran both on the whole project (weighted to the §3 Ory stack). Verdict: architecture sound + disciplined, no Critical; both independently flagged the *same* top issue. **Fixed now:** (1) HIGH (both agents) — `JWKS_URL` default was `http://kratos:4433/.well-known/jwks.json`, but Kratos does **not** republish the session-tokenizer key there (no OIDC discovery on Kratos — that's Hydra), so the §4 verifier would have fetched the wrong/empty set and *no one* could be authorized. Repointed the default to `file:///etc/config/kratos/tokenizer/jwks.json` — the exact key Kratos signs with (`kratos.yml` `jwks_url`) — and mounted that tokenizer dir **read-only into `web`** (`compose.yml`) so the verifier resolves the live key in dev *and* prod (same file bootstrap regenerates). `config.test.ts` now locks the default to the tokenizer file + asserts the committed key is a real ES256 JWKS carrying a `kid` (the regression the old `/jwks/` match missed). (2) MEDIUM (stability) — `bootstrap` had uncapped `restart: on-failure`; a *permanent* seed error would loop forever and silently hang `web` (gates on `service_completed_successfully`). Capped to `on-failure:5` (seed is idempotent — 409-create + idempotent PUT — so transient Ory blips still recover, permanent ones give up loud). (3) §3's new `web` `depends_on` made the documented `docker compose run --rm web …` typecheck/test/gen-jwks commands drag up the whole Ory stack — added `--no-deps` (README + AGENTS.md). **Deferred (reviewer-scoped, not §3):** extract `buildShellContext` out of `dashboard.ts` + route built-in screens through `matchRoute`/`isAuthorized` → §5 (forcing function arrives with the 2nd/3rd screen); seed the demo admin's `metadata_admin.roles` projection so first login is non-empty → §4 (the login-completion projection owns it); enforce Ory `*.yml` prod secrets + self-service return-URLs via env → §9 (ops). typecheck + 153 units green; both compose files validated.
+- [x] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues. → Ran both on the whole project (weighted to the §3 Ory stack). Verdict: architecture sound + disciplined, no Critical; both independently flagged the *same* top issue. **Fixed now:** (1) HIGH (both agents) — `JWKS_URL` default was `http://kratos:4433/.well-known/jwks.json`, but Kratos does **not** republish the session-tokenizer key there (no OIDC discovery on Kratos — that's Hydra), so the §4 verifier would have fetched the wrong/empty set and *no one* could be authorized. Repointed the default to `file:///etc/config/kratos/tokenizer/jwks.json` — the exact key Kratos signs with (`kratos.yml` `jwks_url`) — and mounted that tokenizer dir **read-only into `web`** (`compose.yml`) so the verifier resolves the live key in dev *and* prod (same file bootstrap regenerates). `config.test.ts` now locks the default to the tokenizer file + asserts the committed key is a real ES256 JWKS carrying a `kid` (the regression the old `/jwks/` match missed). (2) MEDIUM (stability) — `bootstrap` had uncapped `restart: on-failure`; a *permanent* seed error would loop forever and silently hang `web` (gates on `service_completed_successfully`). Capped to `on-failure:5` (seed is idempotent — 409-create + idempotent PUT — so transient Ory blips still recover, permanent ones give up loud). (3) §3's new `web` `depends_on` made the documented `docker compose run --rm web …` typecheck/test/gen-jwks commands drag up the whole Ory stack — added `--no-deps` (README + AGENTS.md). **Deferred (reviewer-scoped, not §3):** extract `buildShellContext` out of `dashboard.ts` + route built-in screens through `matchRoute`/`isAuthorized` → §5 (forcing function arrives with the 2nd/3rd screen); seed the demo admin's `metadata_admin.roles` projection so first login is non-empty → §4 (the login-completion projection owns it); enforce Ory `*.yml` prod secrets + self-service return-URLs via env → §9 (ops). typecheck + 153 units green; both compose files validated.
 - [x] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff. → Pass over the §3 Ory accretion. Killed the now-stale "the next §3 item generates/mounts" forward-refs (the JWKS shipped) in `kratos.yml` (×2) + `kratos.test.ts`. Tightened the verbose service/header blocks in `compose.yml` (web depends_on/JWKS-mount, the three Ory headers, the bootstrap block) and the `bootstrap.ts`/`gen-jwks.ts` module headers — dropping prose the README/`src/bootstrap.ts` already carry, keeping the security/stability rationale (read-only mount, bounded retry). Trimmed `config.ts`'s JWKS comment and the `kratos.yml` SSO block (kept the concrete env example), and aligned the `gen-jwks.ts` command with the README's `--no-deps`. Net −12 lines; typecheck + 153 units green. The §3 README sections (Development / What you must supply / SSO / JWT rotation) were already authored concise in §3 (todo lines 70–72) and left intact.
 - [x] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us. → Pass over the §3 Ory-stack tests. The clear overlap: the "image pinned to an exact version" AGENTS.md check was re-implemented 5× (postgres/kratos/keto/hydra + mailpit). Unified into one `compose.test.ts` scan over all three compose files (strictly stronger — auto-covers any future image) + one test asserting each Ory service & its migrate sidecar share one version (subsumes the per-service "both present + same version" halves). Dropped the now-redundant pin tests from `postgres/kratos/keto/hydra.test.ts` (each keeps its config-semantics tests; comments point pinning at `compose.test.ts`). Also trimmed `config.test.ts`'s duplicate re-validation of the committed JWKS key — `gen-jwks.test.ts` already owns key validity (round-trips a signature); the config test keeps the default-path assertion. The migrate-before-server / DSN / port / URL tests stay per-service (distinct config, distinct files — merging would hurt the per-module structure). 153 → 150 tests, zero coverage lost; typecheck + tests green.
 
@@ -88,16 +90,16 @@ everything via Docker.
 - [x] Logout: revoke Kratos session + clear cookie. → `GET /logout` (`app.ts`): clears our local `plainpages_jwt` (`clearSessionCookie`, Max-Age=0) **and** revokes the Kratos session. Kratos' own cookie lives on its origin, so we can't expire it from here — instead `kratos.createLogoutFlow(cookie)` (new `KratosPublic` method, `GET /self-service/logout/browser` → `{logoutToken, logoutUrl}`, 401⇒null) and 303 the browser to `logoutUrl`; Kratos revokes the session, clears `plainpages_session`, and lands on `/login` (`kratos.yml` `logout.after`, already configured). No active session ⇒ just clear our cookie + 303 `/login`. Wired the inert shell "Sign out" button → `<a href="/logout">` (zero-JS, matches the menu's existing link items). Tests-first: `kratos-public.test.ts` (logout flow 200→urls / 401→null + cookie forwarded), `app.test.ts` integration (active session → Kratos logout URL + cleared JWT; no session → `/login` + cleared JWT), `shell.test.ts` (sign-out link wired). typecheck + 212 units green. Boot-verified live: admin login → `/logout` 303s to the real `…/self-service/logout?token=ory_lo_…` with `plainpages_jwt` cleared, following it revokes the session (`whoami` 200→401) and redirects to `/login`; no-session `/logout` → `/login`; torn down.
 - [x] Secure cookie flags; CSRF for our own POST forms. → **Secure flag:** new explicit `SECURE_COOKIES` toggle (`config.ts`, default off — dev is http; `compose.yml` sets it `true`, `compose.override.yml`/`compose.e2e.yml` `false`), threaded through every first-party Set-Cookie (session JWT, clear, re-mint, CSRF). **CSRF:** `src/csrf.ts` — stateless **signed double-submit** token `<nonce>.<HMAC-SHA256(CSRF_SECRET, nonce)>` (node:crypto, no dep): `issueCsrfToken`/`verifyCsrfToken` (self-validating, timing-safe), `ensureCsrfToken` (reuse a genuine `plainpages_csrf` cookie, else mint — one token across tabs), `csrfCookie` (HttpOnly+Lax, secure opt-in), `verifyCsrfRequest` (cookie genuine **and** field echoes it). `src/body.ts` `readFormBody` (size-capped urlencoded reader; §5 forms reuse it). Applied to our one first-party form: **logout is now a CSRF-guarded `POST`** — `shell.ejs`'s Sign-out is a `<form method=post action=/logout>` with a hidden `_csrf` (semantic win: a state change is a form, not a GET link), `app.ts` issues the token cookie on `GET /` and verifies it on `POST /logout` (bad/missing → 403, before any Kratos call); `dashboard.ts`→`index.ejs`→shell thread the token. Kratos' own flows keep Kratos' CSRF; the host does **not** auto-gate plugin routes (they own their body/safety per the contract). Switched the cookie-setting sites to `appendHeader` so the CSRF cookie coexists with others. Tests-first: `csrf.test.ts`/`body.test.ts` + extended `config`/`dashboard`/`shell`/`app` tests (logout POST: valid→Kratos logout + cleared JWT, no-session→/login, missing/forged→403) + an Ory-free E2E (GET / issues the cookie + matching form token; tokenless POST→403). typecheck + 217 units + 8 E2E green. Boot-verified live on the full stack: GET / double-submit token matches; admin login → `POST /logout` 303s to the real `…/self-service/logout?token=ory_lo_…` with the JWT cleared; no-session→/login; forged/missing→403; torn down.
 - [x] Make sure we have E2E tests for token timeouts and refresh (maybe by shorten the token lifetime to very low or something). → New full-stack Playwright suite `e2e/auth-refresh.spec.ts` (run via `compose.e2e-auth.yml`): boots the **real** Ory stack (Postgres + Kratos + Keto + bootstrap + web), logs in the seeded admin, completes login on web → session JWT, then proves the §4 "stay signed in" hot path end-to-end — once the token lapses the next request is silently **re-minted** from the live Kratos session (fresh JWT, later `exp`, roles re-read from Keto = `["admin"]`); revoking the Kratos session (admin API) then makes the next lapsed request **clear** the stale cookie (→ anonymous). To make timeout/refresh observable in seconds not ~10m: `ory/kratos/e2e.yml` (merged via a second `-c`) shortens the tokenizer `ttl` to **8s** and points `serve.public.base_url` at `kratos:4433` (so the runner drives self-service over the compose network), and a new explicit **`JWT_CLOCK_SKEW_SEC`** config (default 60, the E2E sets `0`) makes web treat the JWT as expired the instant its ttl lapses instead of +60s. The flow is driven over HTTP (fetch + manual cookie relay) because Kratos/web sit on different hosts here — it exercises web's own server-side relay; the browser-UI login stays §8. Scoped the existing visual suite to `visual.spec.ts` (stays Ory-free/fast) so the two suites don't cross-run. Tests-first for the config knob (`config.test.ts`). Verified live: auth suite green (re-mint + clear), visual suite still 8/8 green; typecheck + 218 units green; both stacks torn down.
-- [x] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues. → Ran both on the whole project (weighted to the §4 auth hot path). Verdict: no Critical/High; both confirmed the auth core (alg-allowlist JWS verify, fail-closed `resolveSession`, key-by-`kid` cache, timing-safe CSRF, traversal guards) is sound, and that a tampered/garbage cookie **can't** drive the Ory re-mint round-trip (only a validly-signed, time-expired token sets `expired`). **Fixed now (tests-first):** (1) MEDIUM (stability) — the re-mint hot path turned an Ory *outage* into a 500 on **every** lapsed request (a dead Kratos session returns `null` and clears cleanly, but a 5xx/refused/timeout *throws* and escaped to the 500 handler). Wrapped the `remintSession` call in `app.ts` in try/catch → degrade to **anonymous** (route renders signed-out / guard bounces to `/login`), and leave the cookie untouched so it re-mints once Ory recovers; `app.test.ts` re-mint test now also asserts outage→403-not-500 + no cleared cookie. (2) MEDIUM (architecture) — a plugin folder named after a host route (`login`/`logout`/`auth`/`public`/`recovery`/`registration`/`settings`/`verification`) would **silently shadow** it (plugin routes resolve first), the one collision `findConflicts` didn't catch. Added `RESERVED_PLUGIN_IDS` (`plugin.ts`) checked in `discovery.ts` → fails boot loud, like every other conflict; documented in `docs/plugin-contract.md` Identity; `discovery.test.ts` covers it. **Deferred (reviewer-scoped, not §4):** extract `buildShellContext` out of `dashboard.ts` + thread the real `ctx.user` into the shell (kills the hardcoded "Sam Rivers" demo profile) **and** give the host its own internal route table via `matchRoute`/`isAuthorized` → **§5** (the 2nd/3rd built-in screen is the forcing function; the hardcoded user is the one user-visible §4 gap, so §5 opens with it); `/auth/complete` login-CSRF hardening + the `POST /logout` oversized-body→500 papercut → **§9** (security headers/CSRF/cookies); retarget the stale `safeUrl()` §4 reference in the contract doc → the next §4 comment-cleanup item (line 92), helper itself deferred to §5/§7 when untrusted URL data first flows. No action: forwarding the full cookie header to Kratos on re-mint (works, mild over-coupling), the deliberately-opt-in `iss`/`aud` claim checks, the `serializeCookie` length bound. typecheck + 219 units green.
+- [x] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues. → Ran both on the whole project (weighted to the §4 auth hot path). Verdict: no Critical/High; both confirmed the auth core (alg-allowlist JWS verify, fail-closed `resolveSession`, key-by-`kid` cache, timing-safe CSRF, traversal guards) is sound, and that a tampered/garbage cookie **can't** drive the Ory re-mint round-trip (only a validly-signed, time-expired token sets `expired`). **Fixed now (tests-first):** (1) MEDIUM (stability) — the re-mint hot path turned an Ory *outage* into a 500 on **every** lapsed request (a dead Kratos session returns `null` and clears cleanly, but a 5xx/refused/timeout *throws* and escaped to the 500 handler). Wrapped the `remintSession` call in `app.ts` in try/catch → degrade to **anonymous** (route renders signed-out / guard bounces to `/login`), and leave the cookie untouched so it re-mints once Ory recovers; `app.test.ts` re-mint test now also asserts outage→403-not-500 + no cleared cookie. (2) MEDIUM (architecture) — a plugin folder named after a host route (`login`/`logout`/`auth`/`public`/`recovery`/`registration`/`settings`/`verification`) would **silently shadow** it (plugin routes resolve first), the one collision `findConflicts` didn't catch. Added `RESERVED_PLUGIN_IDS` (`plugin.ts`) checked in `discovery.ts` → fails boot loud, like every other conflict; documented in `docs/plugin-contract.md` Identity; `discovery.test.ts` covers it. **Deferred (reviewer-scoped, not §4):** extract `buildShellContext` out of `dashboard.ts` + thread the real `ctx.user` into the shell (kills the hardcoded "Sam Rivers" demo profile) **and** give the host its own internal route table via `matchRoute`/`isAuthorized` → **§5** (the 2nd/3rd built-in screen is the forcing function; the hardcoded user is the one user-visible §4 gap, so §5 opens with it); `/auth/complete` login-CSRF hardening + the `POST /logout` oversized-body→500 papercut → **§9** (security headers/CSRF/cookies); retarget the stale `safeUrl()` §4 reference in the contract doc → the next §4 comment-cleanup item (line 92), helper itself deferred to §5/§7 when untrusted URL data first flows. No action: forwarding the full cookie header to Kratos on re-mint (works, mild over-coupling), the deliberately-opt-in `iss`/`aud` claim checks, the `serializeCookie` length bound. typecheck + 219 units green.
 - [x] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff. → Pass over the §4 auth accretion (the §3 cleanup at line 74 stands). The §4 comments were authored dense, so the wins are targeted: tightened the verbose client module-headers — `kratos-public.ts` (dropped the "themed flow pages build on this" forward-ref, kept the loose-`ui.nodes`-types rationale), `kratos-admin.ts` (folded the admin-port note up, trimmed the `KratosError` restatement), `keto-client.ts` (dropped the caller-listing tail). Retargeted the stale `safeUrl()` ref in `docs/plugin-contract.md` (the §4 reviewer flag at line 91): the helper was deferred to §5/§7, not §4. Left intact: app.ts's per-branch *why* comments (right altitude for scanning the request flow), config.ts's dense field notes, and the §4 README **Auth, sessions & permissions** sections (the canonical design rationale, authored concise in §4). `_(planned)_` markers stay for §9 (line 133 owns dropping them). typecheck + 219 units green.
 - [x] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us. → Pass over the §4 auth tests. The clients (`kratos-public`/`kratos-admin`/`keto-client`) and the focused units (`jwks`/`flow-view`/`guards`/`csrf`/`body`/`login`) already follow the per-module "matrix + edge" pattern, no fat to cut. Removed the two genuine §4-era overlaps: (1) `jwt-middleware.test.ts` re-ran `resolveSession`'s whole classification matrix again under `authenticate` — but `authenticate` is just `resolveSession(...).user`, so merged into one test where `resolveSession` owns the matrix and `authenticate` is asserted as its fail-closed user-projection (kept `authenticate` itself — a documented convenience export, just not double-tested). (2) `app.test.ts` had two `/auth/complete` HTTP tests (live-session vs no-session) for one route → merged into one (happy path + edge), mirroring the project's style. 219 → 217 tests, zero coverage lost; typecheck + tests green.
 
 ## 5. Built-in admin screens (writes go only to Keto/Kratos)
 - [x] Users: list (Kratos identities) with filter/sort/pagination; create/edit/deactivate/delete; trigger recovery. → `src/admin-users.ts`: pure view-model + Kratos-payload builders (`toUserView`, `buildUsersListModel`, `buildUserFormModel`, `create/updateIdentityPayload`, `setStatePayload`) + `handleAdminUsers` (the imperative shell app.ts dispatches `/admin/users*` to). Routes: `GET /admin/users` (list — filter by q/status, sortable headers, paginate; in-memory over one fetched Kratos page since the admin API has no search/sort), `GET|POST /admin/users/new`+`/` (create), `GET|POST /admin/users/:id` (edit; email is the read-only login identifier, name editable, optional initial password), `POST …/:id/state` (deactivate↔reactivate), `…/delete`, `…/recovery` (mints a code via the new `kratosAdmin.createRecoveryCode` admin endpoint, renders the link). Writes go **only to Kratos** (README "stateless"). Gated **admin-only** (anonymous→/login, non-admin→403 via `GuardError`) and every mutation is **CSRF-guarded** (signed double-submit, like logout); reuses the §1 building blocks (filter-bar/data-table/pagination/field) around the app shell. Reviewer's §5 opener done too: extracted `src/shell-context.ts` (`buildShellContext`/`shellUser`) shared by the dashboard + admin screens — kills the hardcoded "Sam Rivers" demo profile, threads the **real** signed-in user (email/derived initials; anonymous→Guest); `dashboard.ts` + `app.ts` now pass `ctx.user`. Added `readonly` to `field.ejs`, `admin` to `RESERVED_PLUGIN_IDS` (a plugin folder can't shadow the screens), `views:[viewsDir]` to the core renderer (so a subfolder view includes the shared `partials/` by root-relative name). Tests-first: `admin-users.test.ts` (mapping/selection/payload matrix), `app.test.ts` HTTP integration (gate/list-filter/create/edit/state/delete/recovery + CSRF reject), `shell-context.test.ts`, `kratos-admin.test.ts` (recovery endpoint), `discovery.test.ts` (reserved `admin`). typecheck + 228 units + 8 visual E2E green. Boot-verified live on the full Ory stack: seeded-admin login → JWT `roles:["admin"]` → `/admin/users` lists identities; create→303→listed, recovery→real Kratos code/link, state→inactive, delete→absent, forged CSRF→403; torn down. Groups/roles/menu-wiring are the next §5 items.
-- [ ] Groups: Keto subject sets — list/create/delete + membership management.
+- [x] Groups: Keto subject sets — list/create/delete + membership management. → `src/admin-groups.ts`: pure view-model + Keto-tuple builders (`groupsFromTuples`, `parseSubject`/`memberTuple`, `memberView`, `isValidGroupName`, `buildGroups{List,Detail,Form}Model`) + `handleAdminGroups` (the imperative shell app.ts dispatches `/admin/groups*` to). A group is a Keto subject set `Group:<name>#members`; a member is a user (`subject_id=user:<uuid>`) or a nested group (`subject_set=Group:<other>#members`). Keto has no create-object, so a group exists while it has ≥1 member: **create** writes the first-member tuple (requires a member, rejects a duplicate/invalid name), **delete** removes every member tuple (one delete-by-partial-filter), **add/remove member** write/delete one tuple. Routes: `GET /admin/groups` (list — search/sort/paginate over one Keto namespace scan), `GET|POST /admin/groups/new`+`/` (create), `GET /admin/groups/:name` (membership detail — members by email, add a user/nested group, remove, delete-group), `POST …/members` · `…/members/delete` · `…/delete`. Writes go **only to Keto** (README "stateless"); Kratos is read only to label the member pickers by email. Gated **admin-only** (anon→/login, non-admin→403) and every mutation **CSRF-guarded**, same as Users; reuses the §1 building blocks around the shell. Extracted `src/admin-nav.ts` (shared Dashboard·Users·Groups sidebar nav) so the two screens can't drift; added a generic `rowHeader` `<th scope=row>` data-table cell (the group name links to its detail). Tests-first: `admin-groups.test.ts` (builder/validation/subject matrix), `app.test.ts` HTTP integration (gate/list/create/dup-reject/detail/add/remove/delete + CSRF + invalid-name & malformed-`%`→404), `data-table.test.ts` (rowHeader). Stability-reviewer (treated as a local PR): APPROVE; fixed its nits — symmetric subject validation (UUID-check the user id), "already exists" feedback on create, malformed-`%`→404 (`safeDecode`). typecheck + 237 units green. Boot-verified the core Keto interactions live (namespace listing, group-collapse counts, delete-group-by-filter, single-member removal). The full-stack groups-CRUD Playwright E2E is §8's scope (line 123), as with the Users screen. Roles/permissions + global-menu wiring are the next §5 items.
 - [ ] Roles & permissions: Keto relations — assign roles to users/groups; "effective access" view via Keto expand.
 - [ ] Wire into the menu (admin section, permission-gated).
-- [ ] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
+- [ ] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
 - [ ] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff.
 - [ ] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us.
 
@@ -105,14 +107,14 @@ everything via Docker.
 - [ ] Login-challenge handler: authenticate via Kratos session, accept/reject.
 - [ ] Consent-challenge handler: show / auto-accept first-party, grant scopes, accept/reject.
 - [ ] OAuth2 client registration (admin UI or CLI).
-- [ ] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
+- [ ] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
 - [ ] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff.
 - [ ] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us.
 
 ## 7. Example plugin (reference)
 - [ ] Reference plugin (e.g. people directory or scheduling): list page fetching upstream data, a form that forwards writes upstream, permission-gated nav.
 - [ ] Verify the full plugin contract end-to-end against the README.
-- [ ] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
+- [ ] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
 - [ ] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff.
 - [ ] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us.
 
@@ -120,7 +122,7 @@ everything via Docker.
 - [ ] node --test units across helpers / router / nav / auth (tests-first throughout).
 - [ ] **Playwright full E2E**: login (password + mocked SSO), menu filtering by role, users/groups/permissions CRUD, a plugin page, logout.
 - [ ] E2E harness: bring up the full compose stack, seed Keto roles + a test identity, **tear down after**.
-- [ ] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
+- [ ] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
 - [ ] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff.
 - [ ] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us.
 
@@ -131,7 +133,7 @@ everything via Docker.
 - [ ] Structured logging / basic observability. use @larvit/log for OTLP compability - but add subtasks and stuff for supporting incoming trace id etc from a reverse-proxy etc.
 - [ ] JWT signing-key rotation runbook.
 - [ ] Refresh README `Layout` + drop `_(planned)_` markers as pieces land.
-- [ ] Run the architecture _and_ the stability reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
+- [ ] Run the architecture and the product  reviewer agents on the _whole_ project, not just the latest changes, and address their issues.
 - [ ] Go over all comments in the code and the README and try to make it shorter and more information dense. Remove not strictly needed stuff.
 - [ ] Go over all tests and combine/unify ones that cover the same stuff or are very related and could be combined in a good way. Remove tests that aren't helping, we only want tests that are actually helpful to us.
 

views/admin/group-detail.ejs

@@ -0,0 +1,16 @@
+<%#
+  Group admin detail / membership page (todo §5): the group-detail body in the app shell.
+%><%
+  const nav = include("partials/nav-tree", { nodes: model.nav });
+  const body = include("partials/group-detail-body", { add: model.add, csrfToken: model.csrfToken, del: model.delete, error: model.error, group: model.group, members: model.members });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: model.shell.brand,
+  breadcrumbs: model.shell.breadcrumbs,
+  csrfToken: model.shell.csrfToken,
+  nav,
+  theme: model.shell.theme,
+  title: model.shell.title,
+  user: model.shell.user,
+}) %>

views/admin/group-form.ejs

@@ -0,0 +1,16 @@
+<%#
+  Group admin create page (todo §5): the group-form body captured into the app shell.
+%><%
+  const nav = include("partials/nav-tree", { nodes: model.nav });
+  const body = include("partials/group-form-body", { error: model.error, form: model.form });
+-%>
+<%- include("partials/shell", {
+  body,
+  brand: model.shell.brand,
+  breadcrumbs: model.shell.breadcrumbs,
+  csrfToken: model.shell.csrfToken,
+  nav,
+  theme: model.shell.theme,
+  title: model.shell.title,
+  user: model.shell.user,
+}) %>

views/admin/groups.ejs

@@ -0,0 +1,21 @@
+<%#
+  Groups admin list (todo §5): the same building blocks as the Users screen, around the shell, but
+  backed by live Keto subject sets (src/admin-groups.ts). Filter/sort/page round-trip the URL.
+%><%
+  const nav = include("partials/nav-tree", { nodes: model.nav });
+  const filters = include("partials/filter-bar", model.filterBar);
+  const table = include("partials/data-table", model.table);
+  const pager = include("partials/pagination", model.pagination);
+  const actions = '<a class="btn btn-primary" href="/admin/groups/new"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-plus"/></svg>Add group</a>';
+-%>
+<%- include("partials/shell", {
+  actions,
+  body: filters + table + pager,
+  brand: model.shell.brand,
+  breadcrumbs: model.shell.breadcrumbs,
+  csrfToken: model.shell.csrfToken,
+  nav,
+  theme: model.shell.theme,
+  title: model.shell.title,
+  user: model.shell.user,
+}) %>

views/partials/data-table.ejs

@@ -5,8 +5,8 @@
     caption?, selectable?, actions?       sr-only caption; toggle the check / kebab columns
     columns: { label, sortable?, sort?: "asc"|"desc", href?, className? }[]
     rows:    { name?, cells: Cell[], actions?: Action[] }[]
-  Cell ∈ string | { text, className? } | { user:{name,initials} } | { badge:{tone,label} } | { html, className? }
+  Cell ∈ string | { text, className? } | { user:{name,initials} } | { rowHeader:{text,href?} } | { badge:{tone,label} } | { html, className? }
-    user cells render as <th scope="row"> — they identify the row (the row header).
+    user + rowHeader cells render as <th scope="row"> — they identify the row (the row header).
   Action = { label, icon?, href?, danger?, separatorBefore? }
 %><%
   const caption = locals.caption;
@@ -48,6 +48,8 @@
         <td><%= cell %></td>
 <% } else if (cell.user) { -%>
         <th scope="row"><span class="cell-user"><span class="avatar" aria-hidden="true"><%= cell.user.initials %></span><span class="cell-strong"><%= cell.user.name %></span></span></th>
+<% } else if (cell.rowHeader) { -%>
+        <th scope="row"><% if (cell.rowHeader.href) { %><a class="cell-strong" href="<%= cell.rowHeader.href %>"><%= cell.rowHeader.text %></a><% } else { %><span class="cell-strong"><%= cell.rowHeader.text %></span><% } %></th>
 <% } else if (cell.badge) { -%>
         <td><span class="badge <%= cell.badge.tone %>"><span class="dot"></span><%= cell.badge.label %></span></td>
 <% } else if (cell.html != null) { -%>

views/partials/group-detail-body.ejs

@@ -0,0 +1,42 @@
+<%#
+  Admin group membership body (todo §5), captured into the shell content slot. Config:
+    group   { name }
+    members { action, rows: { kind:"group"|"user", label, subject }[] }   action = remove-member endpoint
+    add     { action, options: {label,value}[] }                          action = add-member endpoint
+    del     { action }                                                     delete the whole group
+    csrfToken, error?
+%><%
+  const group = locals.group;
+  const members = locals.members;
+  const add = locals.add;
+  const del = locals.del;
+  const csrf = locals.csrfToken;
+-%>
+<div class="form-page">
+<% if (locals.error) { -%>
+<%- include("alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+  <section class="form-card" aria-labelledby="members-h">
+    <h2 class="card-title" id="members-h">Members</h2>
+<% if (members.rows.length) { -%>
+    <div class="table-wrap"><table class="table"><caption class="sr-only">Members of <%= group.name %></caption><thead><tr><th scope="col">Member</th><th scope="col">Type</th><th class="col-actions" scope="col"><span class="sr-only">Actions</span></th></tr></thead><tbody>
+<% members.rows.forEach((m) => { -%>
+      <tr><th scope="row"><span class="cell-strong"><%= m.label %></span></th><td><span class="badge info"><span class="dot"></span><%= m.kind === "group" ? "Group" : "User" %></span></td><td class="col-actions"><form method="post" action="<%= members.action %>"><input type="hidden" name="_csrf" value="<%= csrf %>"><input type="hidden" name="member" value="<%= m.subject %>"><button class="btn" type="submit"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-x"/></svg>Remove</button></form></td></tr>
+<% }) -%>
+    </tbody></table></div>
+<% } else { -%>
+    <p class="cell-muted">No members yet.</p>
+<% } -%>
+  </section>
+  <section class="form-card" aria-labelledby="add-h">
+    <h2 class="card-title" id="add-h">Add a member</h2>
+<% if (add.options.length) { -%>
+    <form class="inline-form" method="post" action="<%= add.action %>"><input type="hidden" name="_csrf" value="<%= csrf %>"><label class="sr-only" for="add-member">Member</label><span class="select"><select id="add-member" name="member" required><option value="" disabled selected>Choose a user or group…</option><% add.options.forEach((o) => { %><option value="<%= o.value %>"><%= o.label %></option><% }) %></select></span><button class="btn btn-primary" type="submit"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-plus"/></svg>Add</button></form>
+<% } else { -%>
+    <p class="cell-muted">All users and groups are already members.</p>
+<% } -%>
+  </section>
+  <section class="form-card admin-actions" aria-label="Group actions">
+    <form method="post" action="<%= del.action %>"><input type="hidden" name="_csrf" value="<%= csrf %>"><button class="btn btn-danger" type="submit"><svg class="ico ico-sm" aria-hidden="true"><use href="#i-trash"/></svg>Delete group</button></form>
+  </section>
+</div>

views/partials/group-form-body.ejs

@@ -0,0 +1,26 @@
+<%#
+  Admin group create form body (todo §5), captured into the shell content slot. Config:
+    form  { action, csrfToken, submitLabel, cancelHref, nameField: field.ejs config,
+            memberOptions: {label,value}[], selectedMember }
+    error?  string  shown when a write was rejected
+%><%
+  const form = locals.form;
+-%>
+<div class="form-page">
+<% if (locals.error) { -%>
+<%- include("alert", { text: locals.error, tone: "neg" }) %>
+<% } -%>
+  <form class="form-card" method="post" action="<%= form.action %>">
+    <input type="hidden" name="_csrf" value="<%= form.csrfToken %>">
+    <%- include("field", form.nameField) %>
+    <div class="field">
+      <label for="member">First member</label>
+      <span class="select"><select id="member" name="member" required><option value="" disabled<% if (!form.selectedMember) { %> selected<% } %>>Choose a member…</option><% form.memberOptions.forEach((o) => { %><option value="<%= o.value %>"<% if (form.selectedMember === o.value) { %> selected<% } %>><%= o.label %></option><% }) %></select></span>
+      <span class="field-hint">A group exists once it has a member; add more after creating it.</span>
+    </div>
+    <div class="form-actions">
+      <a class="btn" href="<%= form.cancelHref %>">Cancel</a>
+      <button class="btn btn-primary" type="submit"><%= form.submitLabel %></button>
+    </div>
+  </form>
+</div>