create-astram-app 0.12.6 → 0.12.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.12.6",
+  "version": "0.12.8",
   "license": "MIT",
   "description": "Scaffolder for a new Astram app — emits a running, framework-enforced NestJS server (deny-by-default, built-in auth/identity to switch on) and, with --with-frontend, a React admin/auth UI, over the immutable @astram/* framework packages.",
   "type": "module",

package/template/frontend/package.json

@@ -12,7 +12,7 @@
     "test": "node scripts/run-tests.mjs"
   },
   "dependencies": {
-    "@astram/frontend-core": "^0.8.0",
+    "@astram/frontend-core": "^0.9.0",
     "@astram/sdk": "^0.2.1",
     "@radix-ui/react-alert-dialog": "^1.1.19",
     "@radix-ui/react-avatar": "^1.1.10",

package/template/frontend/src/components/EntityFormModal.jsx

@@ -100,7 +100,7 @@ export default function EntityFormModal({
             e.preventDefault();
             if (!busy) onSubmit?.();
           }}
-          className="flex min-w-0 flex-1 flex-col overflow-hidden"
+          className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden"
         >
           <DialogHeader>
             <DialogTitle>{title}</DialogTitle>
@@ -108,8 +108,10 @@ export default function EntityFormModal({
           </DialogHeader>
 
           {/* Scrollable body: `min-w-0` propagates the shrink to children; `overflow-y-auto`
-              keeps a tall assignments editor inside the modal. */}
-          <div className="mt-4 mb-6 min-w-0 flex-1 space-y-4 overflow-y-auto">
+              keeps a tall assignments editor inside the modal. A flex column with `min-h-0`, so
+              a child that takes `flex-1 min-h-0` (the access matrix) fills the height the modal
+              has — up to the viewport in full screen — and scrolls inside itself. */}
+          <div className="mt-4 mb-6 flex min-h-0 min-w-0 flex-1 flex-col space-y-4 overflow-y-auto">
             {children}
             {error && (
               <Alert variant="destructive">

package/template/frontend/src/components/EntityList.jsx

@@ -46,6 +46,9 @@
  *   onAdd       — () => void
  *   onEdit      — (row) => void
  *   onDelete    — (row) => void
+ *   onRowClick  — (row) => void; defaults to `onEdit`. When set, a click on the row (outside its
+ *                 buttons, links and menus) or Enter/Space on the focused row opens it. Pass it,
+ *                 like `onEdit`, only when the caller may edit (UX only; the server decides).
  *   onSearchChange — (term: string) => void      (page resets to 1)
  *   onSortChange   — (sortBy: string, sortOrder) => void
  *   onPageChange   — (page: number) => void
@@ -64,6 +67,7 @@ import {
   Search,
   Trash2,
 } from 'lucide-react';
+import { shouldOpenRowOnClick, shouldOpenRowOnKey } from './rowActivation';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
@@ -332,9 +336,30 @@ export default function EntityList({
   emptyLabel = 'Nothing here yet.',
   onEdit,
   onDelete,
+  onRowClick,
   onSortChange,
 }) {
   const hasActions = Boolean(onEdit || onDelete);
+  const openRow = onRowClick ?? onEdit;
+  // Click / keyboard props for an openable row (desktop row and mobile card alike).
+  const rowOpenProps = (row) =>
+    openRow
+      ? {
+          tabIndex: 0,
+          onClick: (e) => {
+            const selection = typeof window !== 'undefined' ? window.getSelection?.() : null;
+            if (shouldOpenRowOnClick(e.target, e.currentTarget, selection?.toString() ?? '')) {
+              openRow(row);
+            }
+          },
+          onKeyDown: (e) => {
+            if (shouldOpenRowOnKey(e.key, e.target, e.currentTarget)) {
+              e.preventDefault();
+              openRow(row);
+            }
+          },
+        }
+      : {};
 
   return (
     <Card className="gap-0 overflow-hidden py-0">
@@ -405,7 +430,15 @@ export default function EntityList({
                     </TableRow>
                   ) : (
                     rows.map((row, i) => (
-                      <TableRow key={typeof row.id === 'string' ? row.id : i}>
+                      <TableRow
+                        key={typeof row.id === 'string' ? row.id : i}
+                        {...rowOpenProps(row)}
+                        className={
+                          openRow
+                            ? 'cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring'
+                            : undefined
+                        }
+                      >
                         {columns.map((col) => (
                           <TableCell key={col.key ?? col.label}>{cellValue(col, row)}</TableCell>
                         ))}
@@ -438,7 +471,12 @@ export default function EntityList({
                 rows.map((row, i) => (
                   <div
                     key={typeof row.id === 'string' ? row.id : i}
-                    className="rounded-lg border border-border bg-background p-3"
+                    {...rowOpenProps(row)}
+                    className={`rounded-lg border border-border bg-background p-3${
+                      openRow
+                        ? ' cursor-pointer transition-colors hover:bg-muted/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring'
+                        : ''
+                    }`}
                   >
                     <dl className="space-y-2">
                       {columns.map((col) => (

package/template/frontend/src/components/rowActivation.js

@@ -0,0 +1,52 @@
+// rowActivation.js — when a click or key press on a list row should open the row (EntityList's
+// `onRowClick`). Pure logic over DOM-like objects, tested by rowActivation.test.mjs. Opening a row is
+// UX only: the page passes `onRowClick` only when the caller may edit, and the server still decides.
+
+/** Elements that act on their own: a click on (or inside) one never also opens the row. */
+export const INTERACTIVE_SELECTOR = [
+  'a',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  'label',
+  '[role="button"]',
+  '[role="checkbox"]',
+  '[role="menuitem"]',
+  '[role="menu"]',
+  '[role="switch"]',
+  '[role="link"]',
+  '[contenteditable="true"]',
+].join(',');
+
+/**
+ * Should this click open the row?
+ * - The target must be inside the row element: React bubbles clicks from portalled content (a
+ *   row's dropdown menu or dialog) through the row, and those must never open it.
+ * - A click on an interactive element inside the row (a button, link, checkbox, menu) does its own
+ *   thing only.
+ * - A click that ends a text selection (the user is copying a value) does not open the row.
+ * @param {{ closest?: (selector: string) => unknown } | null | undefined} target event target
+ * @param {{ contains?: (node: unknown) => boolean } | null | undefined} rowEl the row element
+ * @param {string} [selectedText] the current text selection, if any
+ */
+export function shouldOpenRowOnClick(target, rowEl, selectedText = '') {
+  if (!target || !rowEl || typeof rowEl.contains !== 'function') return false;
+  if (!rowEl.contains(target)) return false;
+  if (typeof target.closest === 'function') {
+    const interactive = target.closest(INTERACTIVE_SELECTOR);
+    if (interactive && interactive !== rowEl && rowEl.contains(interactive)) return false;
+  }
+  return !(typeof selectedText === 'string' && selectedText.trim().length > 0);
+}
+
+/**
+ * Should this key press open the row? Enter or Space on the focused row itself (not on a control
+ * inside it, which handles its own keys).
+ * @param {string} key `KeyboardEvent.key`
+ * @param {unknown} target event target
+ * @param {unknown} rowEl the row element
+ */
+export function shouldOpenRowOnKey(key, target, rowEl) {
+  return target === rowEl && (key === 'Enter' || key === ' ');
+}

package/template/frontend/src/components/rowActivation.test.mjs

@@ -0,0 +1,69 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { shouldOpenRowOnClick, shouldOpenRowOnKey } from './rowActivation.js';
+
+/** A tiny DOM-like tree: `closest` walks parents matching a set of "interactive" node names. */
+function node(name, parent = null, interactive = false) {
+  const n = {
+    name,
+    parent,
+    interactive,
+    contains(other) {
+      for (let cur = other; cur; cur = cur.parent) if (cur === n) return true;
+      return false;
+    },
+    closest() {
+      for (let cur = n; cur; cur = cur.parent) if (cur.interactive) return cur;
+      return null;
+    },
+  };
+  return n;
+}
+
+test('a click on plain cell text opens the row', () => {
+  const row = node('tr');
+  const cell = node('td', row);
+  const text = node('span', cell);
+  assert.equal(shouldOpenRowOnClick(text, row), true);
+  assert.equal(shouldOpenRowOnClick(row, row), true);
+});
+
+test('a click on a button, link or checkbox inside the row does not open it', () => {
+  const row = node('tr');
+  const cell = node('td', row);
+  const button = node('button', cell, true);
+  const icon = node('svg', button);
+  assert.equal(shouldOpenRowOnClick(button, row), false);
+  assert.equal(shouldOpenRowOnClick(icon, row), false);
+});
+
+test('a click bubbling from portalled content (a dropdown item outside the row) never opens it', () => {
+  const row = node('tr');
+  const portal = node('div');
+  const item = node('div', portal, true);
+  const plain = node('span', portal);
+  assert.equal(shouldOpenRowOnClick(item, row), false);
+  assert.equal(shouldOpenRowOnClick(plain, row), false);
+});
+
+test('a click that ends a text selection does not open the row', () => {
+  const row = node('tr');
+  const cell = node('td', row);
+  assert.equal(shouldOpenRowOnClick(cell, row, 'Acme Ltd'), false);
+  assert.equal(shouldOpenRowOnClick(cell, row, '   '), true);
+});
+
+test('missing target or row never opens', () => {
+  const row = node('tr');
+  assert.equal(shouldOpenRowOnClick(null, row), false);
+  assert.equal(shouldOpenRowOnClick(node('td', row), null), false);
+});
+
+test('Enter or Space on the focused row opens it; on a control inside it does not', () => {
+  const row = node('tr');
+  const button = node('button', row, true);
+  assert.equal(shouldOpenRowOnKey('Enter', row, row), true);
+  assert.equal(shouldOpenRowOnKey(' ', row, row), true);
+  assert.equal(shouldOpenRowOnKey('Enter', button, row), false);
+  assert.equal(shouldOpenRowOnKey('a', row, row), false);
+});

package/template/frontend/src/pages/access/AccessForm.jsx

@@ -15,6 +15,7 @@
  */
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { useNavigate, useOutletContext, useParams, useSearchParams } from 'react-router-dom';
+import { Check } from 'lucide-react';
 import { toast } from 'sonner';
 import { useAuth } from '@/auth/AuthContext';
 import EntityFormModal from '@/components/EntityFormModal';
@@ -22,20 +23,28 @@ import { Input } from '@/components/ui/input';
 import { Checkbox } from '@/components/ui/checkbox';
 import { SearchableSelect } from '@/components/ui/searchable-select';
 import CollapsibleGroup from '@/components/access/CollapsibleGroup';
-import { extraActionsByType, matrixActions } from './accessMatrix';
+import { actionHeading, extraActionsByType, matrixActions, typeLabelOf } from './accessMatrix';
 
 const ACTIONS = ['read', 'create', 'update', 'delete'];
 
-// Column header for an action key: `manage_keys` → `manage keys` (cells carry the catalog label).
-const actionHeading = (a) => a.replace(/_/g, ' ');
-
-// Object → group mapping. An unmapped typeKey falls into "Other" (fail-safe).
+// Object → group mapping. An unmapped typeKey (an app's own types) falls into "Other".
 const GROUPS = [
   {
     label: 'Organization',
     types: ['company', 'company_branch', 'company_department', 'department', 'branch'],
   },
   { label: 'People & Access', types: ['user', 'role', 'company_membership', 'membership_posting'] },
+  {
+    label: 'Security & Sharing',
+    types: [
+      'security_policy',
+      'service_account',
+      'cross_tenant_grant',
+      'record_share',
+      'shared_resource',
+      'stored_file',
+    ],
+  },
 ];
 
 export default function AccessForm() {
@@ -88,6 +97,11 @@ export default function AccessForm() {
     return m;
   }, [catalog]);
   const keyExists = useCallback((key) => Boolean(labelOf[key]), [labelOf]);
+  // The object column shows a name from the catalog labels, never the raw type key.
+  const typeLabels = useMemo(
+    () => Object.fromEntries(typeKeys.map((t) => [t, typeLabelOf(catalog, t)])),
+    [catalog, typeKeys],
+  );
   const cellKey = useCallback((t, a) => `${moduleName}:${t}:${a}`, [moduleName]);
 
   // Declared extra (non-CRUD) actions per type, catalog order. A type without extras keeps
@@ -273,8 +287,10 @@ export default function AccessForm() {
     }
   };
 
-  const matchesSearch = (t) =>
-    !objectSearch.trim() || t.toLowerCase().includes(objectSearch.trim().toLowerCase());
+  const matchesSearch = (t) => {
+    const q = objectSearch.trim().toLowerCase();
+    return !q || t.toLowerCase().includes(q) || (typeLabels[t] ?? '').toLowerCase().includes(q);
+  };
 
   const title =
     mode === 'edit'
@@ -299,11 +315,13 @@ export default function AccessForm() {
       submitLabel="Save access"
       busy={saving || loading}
       error={error}
-      contentClassName="sm:max-w-4xl"
+      contentClassName="sm:max-w-6xl"
     >
-      <div className="grid gap-4 md:grid-cols-[240px_1fr]">
-        {/* Left rail — presets */}
-        <div className="flex flex-col gap-2 md:border-r md:border-border md:pr-4">
+      {/* Fills the modal body (`flex-1 min-h-0`); on md+ the single grid row is the full body
+          height, so the matrix below can take whatever height the modal has (full screen too). */}
+      <div className="grid min-h-0 flex-1 gap-4 md:grid-cols-[240px_1fr] md:grid-rows-[minmax(0,1fr)]">
+        {/* Left rail — presets (scrolls on its own when there are many) */}
+        <div className="flex flex-col gap-2 md:min-h-0 md:overflow-y-auto md:border-r md:border-border md:pr-4">
           <div className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
             Presets
           </div>
@@ -316,19 +334,24 @@ export default function AccessForm() {
               <button
                 key={b.key}
                 type="button"
+                aria-pressed={isApplied}
                 onClick={() => togglePreset(b)}
-                className={`flex items-start gap-2.5 rounded-lg border p-3 text-left transition-colors ${
+                className={`flex items-start gap-2.5 rounded-lg border p-3 text-left transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ${
                   isApplied ? 'border-primary bg-primary/5' : 'border-border hover:bg-muted/50'
                 }`}
               >
                 {/* Checkbox-like: presets stack (multiple can be applied); this reflects +
-                    toggles whether ALL of the preset's keys are held. Non-interactive
-                    itself (the whole card is the button) — pointer-events-none. */}
-                <Checkbox
-                  checked={isApplied}
-                  className="pointer-events-none mt-0.5"
-                  tabIndex={-1}
-                />
+                    toggles whether ALL of the preset's keys are held. The whole card is ONE
+                    toggle button (`aria-pressed`); the box is decorative, not a nested
+                    checkbox button (a <button> inside a <button> is invalid HTML). */}
+                <span
+                  aria-hidden="true"
+                  className={`mt-0.5 flex size-4 shrink-0 items-center justify-center rounded-[4px] border shadow-xs ${
+                    isApplied ? 'border-primary bg-primary text-primary-foreground' : 'border-input'
+                  }`}
+                >
+                  {isApplied && <Check className="size-3.5" />}
+                </span>
                 <div className="min-w-0">
                   <span className="text-sm font-medium text-foreground">{b.label}</span>
                   {b.description && (
@@ -344,7 +367,7 @@ export default function AccessForm() {
         </div>
 
         {/* Right pane — role + matrix */}
-        <div className="flex min-w-0 flex-col gap-3">
+        <div className="flex min-h-0 min-w-0 flex-col gap-3">
           <div className="flex flex-col gap-1">
             <label className="text-xs font-medium text-muted-foreground">Role</label>
             <SearchableSelect
@@ -365,7 +388,9 @@ export default function AccessForm() {
             placeholder="Search objects"
           />
 
-          <div className="flex max-h-[46vh] flex-col gap-2 overflow-y-auto pr-1">
+          {/* The matrix takes the remaining height and scrolls inside itself (it used to be
+              capped at 46vh, so full screen left most of the modal empty). */}
+          <div className="flex min-h-48 flex-1 flex-col gap-2 overflow-y-auto pr-1">
             {groups.map((group) => {
               const visibleTypes = group.types.filter(matchesSearch);
               if (visibleTypes.length === 0) return null;
@@ -412,7 +437,10 @@ export default function AccessForm() {
                         <tr className="text-left text-xs uppercase tracking-wide text-muted-foreground">
                           <th className="py-1 pr-3 font-medium">Object</th>
                           {columns.map((a) => (
-                            <th key={a} className="px-2 py-1 text-center font-medium capitalize">
+                            <th
+                              key={a}
+                              className="px-2 py-1 text-center font-medium whitespace-nowrap"
+                            >
                               {actionHeading(a)}
                             </th>
                           ))}
@@ -421,7 +449,9 @@ export default function AccessForm() {
                       <tbody>
                         {visibleTypes.map((t) => (
                           <tr key={t} className="border-t border-border">
-                            <td className="py-1.5 pr-3 text-foreground">{t}</td>
+                            <td className="py-1.5 pr-3 whitespace-nowrap text-foreground">
+                              {typeLabels[t] ?? t}
+                            </td>
                             {columns.map((a) => {
                               const key = cellKey(t, a);
                               const exists = keyExists(key);

package/template/frontend/src/pages/access/AccessPage.jsx

@@ -14,7 +14,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { Outlet, useNavigate, useSearchParams } from 'react-router-dom';
 import { KeyRound } from 'lucide-react';
 import { toast } from 'sonner';
-import { useAuth } from '@/auth/AuthContext';
+import { useAuth, useCan } from '@/auth/AuthContext';
 import AppShell from '@/shell/AppShell';
 import PageHeader from '@/components/PageHeader';
 import EntityList, { EntityListControls, EntityListPager } from '@/components/EntityList';
@@ -22,6 +22,8 @@ import ConfirmDialog from '@/components/ConfirmDialog';
 import { Badge } from '@/components/ui/badge';
 import { Avatar, AvatarFallback } from '@/components/ui/avatar';
 import RoleActionsMenu from './RoleActionsMenu';
+// Access chips name object types; show a readable name, never the raw type key.
+import { humanizeKey } from './accessMatrix';
 
 const MAX_CHIPS = 4;
 const DEFAULT_LIMIT = 25;
@@ -110,6 +112,11 @@ export default function AccessPage() {
   const onPageChange = useCallback((page) => setQuery((q) => ({ ...q, page })), []);
   const onLimitChange = useCallback((limit) => setQuery((q) => ({ ...q, limit, page: 1 })), []);
 
+  // Grant, revoke and duplicate all run through role-permission routes gated on
+  // identity:role:update. Without it the page is read-only: no menu, no row click, no Assign.
+  // UX only; the server decides.
+  const canEditAccess = useCan('identity:role:update');
+
   // Row menu actions.
   const onEdit = useCallback((row) => navigate(`/access/edit/${row.roleUuid}`), [navigate]);
   const onDuplicate = useCallback(
@@ -170,7 +177,7 @@ export default function AccessPage() {
           <div className="flex flex-wrap gap-1">
             {(row.chips || []).slice(0, MAX_CHIPS).map((c) => (
               <Badge key={c} variant="secondary" className="font-normal">
-                {c}
+                {humanizeKey(c)}
               </Badge>
             ))}
             {extra > 0 && <span className="text-xs text-muted-foreground">+{extra}</span>}
@@ -208,22 +215,27 @@ export default function AccessPage() {
         );
       },
     },
-    {
-      // Actions as a normal column (not EntityList's built-in Edit/Delete slot), so we can
-      // render the ⋯ menu (Edit / Duplicate / Revoke all). onEdit/onDelete stay UNSET.
-      key: 'actions',
-      label: '',
-      render: (row) => (
-        <div className="flex justify-end">
-          <RoleActionsMenu
-            role={row}
-            onEdit={onEdit}
-            onDuplicate={onDuplicate}
-            onRevokeAll={setRevokeTarget}
-          />
-        </div>
-      ),
-    },
+    // Actions as a normal column (not EntityList's built-in Edit/Delete slot), so we can
+    // render the ⋯ menu (Edit / Duplicate / Revoke all). onEdit/onDelete stay UNSET; the row
+    // itself opens Edit through `onRowClick`.
+    ...(canEditAccess
+      ? [
+          {
+            key: 'actions',
+            label: '',
+            render: (row) => (
+              <div className="flex justify-end">
+                <RoleActionsMenu
+                  role={row}
+                  onEdit={onEdit}
+                  onDuplicate={onDuplicate}
+                  onRevokeAll={setRevokeTarget}
+                />
+              </div>
+            ),
+          },
+        ]
+      : []),
   ];
 
   return (
@@ -239,7 +251,7 @@ export default function AccessPage() {
               onSearchChange={onSearchChange}
               searchPlaceholder="Search roles…"
               addLabel="Assign access"
-              onAdd={() => navigate('/access/add')}
+              onAdd={canEditAccess ? () => navigate('/access/add') : undefined}
             />
           }
         />
@@ -253,6 +265,7 @@ export default function AccessPage() {
           loading={loading}
           error={error}
           emptyLabel="No roles have access yet. Assign access to get started."
+          onRowClick={canEditAccess ? onEdit : undefined}
           onSortChange={onSortChange}
         />
 

package/template/frontend/src/pages/access/accessMatrix.js

@@ -53,3 +53,46 @@ export function matrixActions(catalog, types) {
   }
   return out;
 }
+
+/** `company_branch` → `Company branch` (the fallback when the catalog gives no type name). */
+export function humanizeKey(key) {
+  const words = String(key ?? '')
+    .split('_')
+    .filter(Boolean)
+    .join(' ');
+  return words ? words[0].toUpperCase() + words.slice(1) : '';
+}
+
+/**
+ * The object column's name for a type (G-027): the part before ": " that every catalog label of
+ * the type shares ("Users: view", "Users: invite" ⇒ "Users"), else the humanized type key. Never
+ * the raw key, which is an identifier, not a label.
+ */
+export function typeLabelOf(catalog, typeKey) {
+  let shared = null;
+  for (const row of Array.isArray(catalog) ? catalog : []) {
+    if (!row || row.typeKey !== typeKey || typeof row.label !== 'string') continue;
+    const at = row.label.indexOf(': ');
+    const prefix = at > 0 ? row.label.slice(0, at).trim() : '';
+    if (!prefix) return humanizeKey(typeKey);
+    if (shared === null) shared = prefix;
+    else if (shared !== prefix) return humanizeKey(typeKey);
+  }
+  return shared ?? humanizeKey(typeKey);
+}
+
+const ACRONYMS = new Map([
+  ['mfa', 'MFA'],
+  ['api', 'API'],
+  ['id', 'ID'],
+  ['url', 'URL'],
+]);
+
+/** A matrix column heading for an action key: `reset_mfa` → `Reset MFA`, `end_sessions` → `End sessions`. */
+export function actionHeading(action) {
+  const words = String(action ?? '')
+    .split('_')
+    .filter(Boolean)
+    .map((w, i) => ACRONYMS.get(w) ?? (i === 0 ? w[0].toUpperCase() + w.slice(1) : w));
+  return words.join(' ');
+}

package/template/frontend/src/pages/access/accessMatrix.test.mjs

@@ -5,7 +5,13 @@
 //   node --test src/pages/access/accessMatrix.test.mjs
 import { test, describe } from 'node:test';
 import assert from 'node:assert/strict';
-import { extraActionsByType, matrixActions } from './accessMatrix.js';
+import {
+  actionHeading,
+  extraActionsByType,
+  humanizeKey,
+  matrixActions,
+  typeLabelOf,
+} from './accessMatrix.js';
 
 const row = (typeKey, action, label = `${typeKey} ${action}`) => ({
   key: `app:${typeKey}:${action}`,
@@ -166,3 +172,31 @@ describe('matrixActions', () => {
     assert.deepEqual([...matrixActions([null, {}, row('t', 'go')])], ['go']);
   });
 });
+
+describe('typeLabelOf / actionHeading (G-027 labels in the matrix)', () => {
+  test('the shared label prefix names the type', () => {
+    const catalog = [row('user', 'read', 'Users: view'), row('user', 'invite', 'Users: invite')];
+    assert.equal(typeLabelOf(catalog, 'user'), 'Users');
+  });
+
+  test('labels without a shared prefix fall back to the humanized key, never the raw key', () => {
+    const mixed = [row('job', 'read', 'Jobs: view'), row('job', 'create', 'Create a job')];
+    assert.equal(typeLabelOf(mixed, 'job'), 'Job');
+    const differing = [row('job', 'read', 'Jobs: view'), row('job', 'update', 'Work: edit')];
+    assert.equal(typeLabelOf(differing, 'job'), 'Job');
+    assert.equal(typeLabelOf([], 'company_branch'), 'Company branch');
+    assert.equal(typeLabelOf(null, 'company_branch'), 'Company branch');
+  });
+
+  test('humanizeKey', () => {
+    assert.equal(humanizeKey('membership_posting'), 'Membership posting');
+    assert.equal(humanizeKey(''), '');
+  });
+
+  test('action headings keep acronyms', () => {
+    assert.equal(actionHeading('reset_mfa'), 'Reset MFA');
+    assert.equal(actionHeading('end_sessions'), 'End sessions');
+    assert.equal(actionHeading('manage_keys'), 'Manage keys');
+    assert.equal(actionHeading('read'), 'Read');
+  });
+});

package/template/frontend/src/pages/companies/CompaniesPage.jsx

@@ -155,6 +155,9 @@ export default function CompaniesPage() {
 
   // Move dialog state (G-011): the company being moved and the chosen parent option.
   const holdsUpdate = useCan(MOVE_PERMISSION);
+  // Add / Edit (and the row click) / Delete only for callers who hold the matching key. UX only.
+  const holdsCreate = useCan('identity:company:create');
+  const holdsDelete = useCan('identity:company:delete');
   const [moveTarget, setMoveTarget] = useState(null);
   const [moveParent, setMoveParent] = useState('');
   const [moveBusy, setMoveBusy] = useState(false);
@@ -252,7 +255,7 @@ export default function CompaniesPage() {
               onSearchChange={onSearchChange}
               searchPlaceholder="Search companies…"
               addLabel="Add company"
-              onAdd={() => navigate('/companies/add')}
+              onAdd={holdsCreate ? () => navigate('/companies/add') : undefined}
             />
           }
         />
@@ -266,8 +269,8 @@ export default function CompaniesPage() {
           loading={loading}
           error={error}
           emptyLabel="No companies yet. Add one to get started."
-          onEdit={(row) => navigate(`/companies/edit/${row.id}`)}
-          onDelete={(row) => setDeleteTarget(row)}
+          onEdit={holdsUpdate ? (row) => navigate(`/companies/edit/${row.id}`) : undefined}
+          onDelete={holdsDelete ? (row) => setDeleteTarget(row) : undefined}
           onSortChange={onSortChange}
         />
 

package/template/frontend/src/pages/service-accounts/ServiceAccountsPage.jsx

@@ -15,7 +15,7 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { Bot, KeyRound } from 'lucide-react';
 import { toast } from 'sonner';
-import { useAuth } from '@/auth/AuthContext';
+import { useAuth, useCan } from '@/auth/AuthContext';
 import AppShell from '@/shell/AppShell';
 import PageHeader from '@/components/PageHeader';
 import EntityList, { EntityListControls } from '@/components/EntityList';
@@ -63,6 +63,10 @@ export default function ServiceAccountsPage() {
 
   // Create / edit-access dialog: `null` closed, `{ account: null }` create, `{ account }` edit.
   const [accessDialog, setAccessDialog] = useState(null);
+  // Create needs service_account:create; the row click opens "Edit access" (roles + scope, a
+  // service_account:update write). UX only; the server decides.
+  const holdsCreate = useCan('identity:service_account:create');
+  const holdsUpdate = useCan('identity:service_account:update');
 
   // One-time key reveal + destructive-confirm state.
   const [issuedKey, setIssuedKey] = useState(null);
@@ -303,7 +307,7 @@ export default function ServiceAccountsPage() {
               onSearchChange={setSearch}
               searchPlaceholder="Search service accounts…"
               addLabel="New service account"
-              onAdd={() => setAccessDialog({ account: null })}
+              onAdd={holdsCreate ? () => setAccessDialog({ account: null }) : undefined}
             />
           }
         />
@@ -315,6 +319,7 @@ export default function ServiceAccountsPage() {
           loading={loading}
           error={error}
           emptyLabel="No service accounts yet. Create one to give an agent or script scoped API access."
+          onRowClick={holdsUpdate ? (row) => setAccessDialog({ account: row.account }) : undefined}
         />
       </div>
 

package/template/frontend/src/pages/users/UsersPage.jsx

@@ -224,6 +224,14 @@ export default function UsersPage() {
   }, [query, setSearchParams]);
 
   const holdsInvite = useCan(INVITE_PERMISSION);
+  // Add / Delete need their user key. The edit page covers the profile AND the assignments
+  // (memberships, postings), so Edit and the row click show for either. UX only.
+  const holdsCreate = useCan('identity:user:create');
+  const holdsDelete = useCan('identity:user:delete');
+  const holdsUserUpdate = useCan('identity:user:update');
+  const holdsMembershipUpdate = useCan('identity:company_membership:update');
+  const holdsPostingCreate = useCan('identity:membership_posting:create');
+  const canOpenEdit = holdsUserUpdate || holdsMembershipUpdate || holdsPostingCreate;
   const [invitingId, setInvitingId] = useState(null);
 
   // Admin sign-in actions (R11): `{ action, user }` while the code dialog is open.
@@ -329,7 +337,7 @@ export default function UsersPage() {
               onSearchChange={onSearchChange}
               searchPlaceholder="Search users…"
               addLabel="Add user"
-              onAdd={() => navigate('/users/add')}
+              onAdd={holdsCreate ? () => navigate('/users/add') : undefined}
             />
           }
         />
@@ -343,8 +351,8 @@ export default function UsersPage() {
           loading={loading}
           error={error}
           emptyLabel="No users yet. Add one to get started."
-          onEdit={(row) => navigate(`/users/edit/${row.id}`)}
-          onDelete={(row) => setDeleteTarget(row)}
+          onEdit={canOpenEdit ? (row) => navigate(`/users/edit/${row.id}`) : undefined}
+          onDelete={holdsDelete ? (row) => setDeleteTarget(row) : undefined}
           onSortChange={onSortChange}
         />
 

package/template/server/_env.example

@@ -182,6 +182,18 @@ NODE_ENV=development
 # INVITE_LINK_TTL_HOURS=72
 # INVITE_RATE_PER_ADMIN=30
 
+# --- OPTIONAL: release name for the permission catalog ---
+# Stamped once on each permission key the catalog first sees (with the date), so admins can tell
+# which release added it. 1-64 characters of letters, digits, . _ + - (a git tag or sha fits);
+# an invalid value fails boot. Unset ⇒ only the date is stored.
+# APP_RELEASE=2026-10-25
+
+# --- OPTIONAL: in-app notification retention ---
+# Read notices are deleted after the first value (days, 1-3650), every notice after the second
+# (at least the first, at most 3650), counted from when the notice was posted.
+# NOTIFICATION_READ_RETENTION_DAYS=90
+# NOTIFICATION_MAX_RETENTION_DAYS=365
+
 # --- OPTIONAL: CAPTCHA on sign-in (Cloudflare Turnstile or Google reCAPTCHA) ---
 # Read only when src/app.module.ts passes ShieldModule.forRoot({ captcha: 'env' }); a missing or
 # invalid value then fails boot. One of turnstile | recaptcha-v3 | recaptcha-v2.

package/template/server/package.json

@@ -21,13 +21,13 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "1.12.0",
-    "@astram/engine": "0.15.0",
-    "@astram/guard": "0.22.0",
+    "@astram/core": "1.13.0",
+    "@astram/engine": "0.16.1",
+    "@astram/guard": "0.24.0",
     "@astram/guide": "^0.2.8",
-    "@astram/identity": "0.18.2",
-    "@astram/messaging": "0.1.7",
-    "@astram/migrate": "0.7.2",
+    "@astram/identity": "0.20.0",
+    "@astram/messaging": "0.1.9",
+    "@astram/migrate": "0.7.3",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",