create-astram-app 0.1.3 → 0.3.0

package/template/frontend/src/shell/Sidebar.jsx

@@ -0,0 +1,257 @@
+/**
+ * Sidebar — the collapsible icon-rail navigation. THEME-ADAPTIVE: a light-gray panel
+ * in light mode, deep navy in dark (driven by the `--sidebar*` tokens in index.css),
+ * so every surface/border/hover reads correctly in both themes. Desktop rail toggles
+ * w-64 ↔ w-14; mobile = drawer (AppShell handles the overlay).
+ *
+ * All colors come from `sidebar-*` tokens (bg-sidebar, text-sidebar-foreground,
+ * border-sidebar-border, bg-sidebar-accent, …) — NO hardcoded `white/x` literals, which
+ * only looked right on the old always-dark rail.
+ */
+import { NavLink, useNavigate } from 'react-router-dom';
+import { LogOut, Zap } from 'lucide-react';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
+import { Avatar, AvatarFallback } from '@/components/ui/avatar';
+import { cn } from '@/lib/utils';
+import { branding } from '@/config/branding';
+import { useAuth } from '@/auth/AuthContext';
+import { NAV_SECTIONS } from './nav';
+
+/** Two-letter initials from a display name (fallback 'U'), never a UUID. */
+function initialsOf(name) {
+  if (!name) return 'U';
+  const clean = name.includes('@') ? name.split('@')[0] : name;
+  const parts = clean.trim().split(/[\s._-]+/).filter(Boolean);
+  const letters = parts.length >= 2 ? parts[0][0] + parts[1][0] : clean.slice(0, 2);
+  return letters.replace(/[^a-zA-Z0-9]/g, '').slice(0, 2).toUpperCase() || 'U';
+}
+
+/**
+ * The signed-in user's profile card (OCA `.dash-profile-card` pattern): a CENTERED,
+ * vertical, CLICKABLE card — round avatar over name over role — that navigates to
+ * Account → Profile, with a hover tint and a bottom divider. Identity comes from the
+ * /auth/me profile (display NAMES, never UUIDs); falls back to the interim login hint.
+ * Collapses to just the avatar in the icon-rail (with a tooltip carrying the identity).
+ */
+function UserCard({ collapsed, onNavigate }) {
+  const { profile, identityHint } = useAuth();
+  const navigate = useNavigate();
+  const name = profile?.name || (identityHint ? identityHint.split('@')[0] : 'Signed in');
+  const company = profile?.company?.name || '';
+  const role = profile?.roles?.[0]?.name || '';
+  const initials = initialsOf(profile?.name || identityHint);
+
+  const goProfile = () => {
+    navigate('/account/profile');
+    onNavigate?.();
+  };
+
+  if (collapsed) {
+    // Rail: just the avatar, tooltip carries the identity; still clicks to the profile.
+    return (
+      <div className="flex justify-center border-b border-sidebar-border py-3">
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button className="rounded-lg" aria-label="Account" onClick={goProfile}>
+              <Avatar className="size-9 shrink-0 rounded-full ring-1 ring-sidebar-border">
+                <AvatarFallback className="rounded-full bg-primary/15 text-[11px] font-semibold text-primary">
+                  {initials}
+                </AvatarFallback>
+              </Avatar>
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="right" className="text-xs">
+            <div className="font-semibold">{name}</div>
+            {company && <div className="opacity-70">{company}</div>}
+            {role && <div className="opacity-70">{role}</div>}
+          </TooltipContent>
+        </Tooltip>
+      </div>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={goProfile}
+      aria-label="Open profile"
+      className="flex w-full flex-col items-center gap-1.5 border-b border-sidebar-border px-3 py-3.5 text-center transition-colors hover:bg-sidebar-accent"
+    >
+      {/* Big round avatar (OCA 56px). Brand-tinted fallback with the initials. */}
+      <Avatar className="size-14 rounded-full ring-1 ring-sidebar-border">
+        <AvatarFallback className="rounded-full bg-primary/15 text-base font-semibold text-primary">
+          {initials}
+        </AvatarFallback>
+      </Avatar>
+      <span className="mt-0.5 truncate text-sm font-semibold text-sidebar-foreground">{name}</span>
+      {company && (
+        <span className="truncate text-[11px] text-sidebar-foreground/60">{company}</span>
+      )}
+      {role && (
+        <span className="truncate font-mono text-[0.6rem] uppercase tracking-[0.08em] text-sidebar-foreground/50">
+          {role}
+        </span>
+      )}
+    </button>
+  );
+}
+
+function BrandTile({ collapsed }) {
+  return (
+    <div
+      className={cn(
+        // Logo is CENTER-aligned in both states (collapsed rail + expanded).
+        'flex items-center justify-center border-b border-sidebar-border py-3.5',
+        collapsed ? 'px-0' : 'px-4',
+      )}
+    >
+      {collapsed ? (
+        // The rail is too narrow for the wordmark — show the compact accent mark.
+        <div className="accent-glow flex size-8 shrink-0 items-center justify-center rounded-lg bg-primary">
+          <Zap className="size-4 text-white" />
+        </div>
+      ) : (
+        // Theme-adaptive logo: the COLOR logo on the light rail, the WHITE variant on
+        // the dark rail (the sidebar surface now follows the theme).
+        <>
+          <img src={branding.logo.light} alt={branding.appName} className="h-7 w-auto dark:hidden" />
+          <img
+            src={branding.logo.dark}
+            alt={branding.appName}
+            className="hidden h-7 w-auto dark:block"
+          />
+        </>
+      )}
+    </div>
+  );
+}
+
+function Item({ item, collapsed, onNavigate }) {
+  const Icon = item.icon;
+  // Use NavLink's render-prop CHILDREN form (bulletproof across versions) and apply
+  // the active styling to an INNER element — avoids relying on the className-function
+  // form (which was rendering as a literal string in this setup).
+  const link = (
+    // `end` for exact-match items; items with `matchPrefix` (e.g. Account, whose real
+    // routes are /account/*) stay active across all their sub-routes.
+    <NavLink to={item.path} end={!item.matchPrefix} onClick={onNavigate} className="block">
+      {({ isActive }) => (
+        <span
+          className={cn(
+            'group flex min-h-9 items-center rounded-lg text-sm font-medium transition-all',
+            collapsed ? 'mx-auto size-9 justify-center' : 'gap-3 px-2.5 py-2',
+            isActive
+              ? 'bg-primary text-white shadow-lg shadow-primary/25'
+              : 'text-sidebar-foreground/70 hover:bg-sidebar-accent hover:text-sidebar-foreground',
+          )}
+        >
+          <Icon className="size-4 shrink-0" />
+          {!collapsed && <span className="truncate">{item.label}</span>}
+          {!collapsed && item.badge && (
+            <span
+              className={cn(
+                'ml-auto rounded border px-1.5 py-px text-[10px] font-semibold tracking-wide',
+                // Themed badge — reads on both the light and dark rail.
+                isActive
+                  ? 'border-white/30 bg-white/20 text-white'
+                  : 'border-primary/40 bg-primary/10 text-primary',
+              )}
+            >
+              {item.badge}
+            </span>
+          )}
+        </span>
+      )}
+    </NavLink>
+  );
+
+  if (!collapsed) return link;
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{link}</TooltipTrigger>
+      <TooltipContent side="right" className="flex items-center gap-2 text-xs">
+        {item.label}
+        {item.badge && <span className="opacity-60">{item.badge}</span>}
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+
+export default function Sidebar({ collapsed, onLogout, onNavigate, mobile = false }) {
+  const isRail = collapsed && !mobile;
+  // Phase E slice 1: `can` (not the `useCan` hook) is used here because it's a plain
+  // function applied inside a `.filter()` over a static per-render array — calling a
+  // HOOK conditionally per array item would violate the Rules of Hooks. One hook call
+  // (`useAuth()`) up front, then `can(item.gate)` per item is safe. An item with no
+  // `gate` (Dashboard/Notes/Cross-tenant/Account) is never filtered — only admin nav
+  // items declare a gate. This is a UX convenience (hide items the caller can't use);
+  // the server's decide() on each page's list route remains the real enforcement.
+  const { can } = useAuth();
+  const visibleSections = NAV_SECTIONS.map((section) => ({
+    ...section,
+    items: section.items.filter((item) => !item.gate || can(item.gate)),
+  })).filter((section) => section.items.length > 0);
+
+  return (
+    <TooltipProvider delayDuration={0}>
+      <div
+        className={cn(
+          'sidebar-panel flex h-full flex-col transition-[width] duration-200',
+          mobile ? 'w-64' : isRail ? 'w-14' : 'w-64',
+        )}
+      >
+        <BrandTile collapsed={isRail} />
+
+        {/* Signed-in user profile card (clickable → Account → Profile) — collapses to
+            just the avatar in the icon-rail. */}
+        <UserCard collapsed={isRail} onNavigate={onNavigate} />
+
+        <nav className="flex-1 space-y-4 overflow-y-auto px-2 py-3">
+          {visibleSections.map((section) => (
+            <div key={section.label}>
+              {!isRail && (
+                <p className="mb-1 px-2 text-[10px] font-semibold uppercase tracking-widest text-sidebar-foreground/40">
+                  {section.label}
+                </p>
+              )}
+              <div className="space-y-0.5">
+                {section.items.map((item) => (
+                  <Item key={item.label} item={item} collapsed={isRail} onNavigate={onNavigate} />
+                ))}
+              </div>
+            </div>
+          ))}
+        </nav>
+
+        {/* Bottom: sign out (replaces the old collapse button — collapse now lives
+            in the header beside the breadcrumb). */}
+        <div className="border-t border-sidebar-border p-2">
+          {(() => {
+            const btn = (
+              <button
+                onClick={onLogout}
+                className={cn(
+                  'flex w-full items-center rounded-lg text-sm font-medium text-sidebar-foreground/60 transition-colors hover:bg-destructive/10 hover:text-destructive',
+                  isRail ? 'mx-auto size-9 justify-center' : 'gap-3 px-2.5 py-2',
+                )}
+                aria-label="Sign out"
+              >
+                <LogOut className="size-4 shrink-0" />
+                {!isRail && <span>Sign out</span>}
+              </button>
+            );
+            if (!isRail) return btn;
+            return (
+              <Tooltip>
+                <TooltipTrigger asChild>{btn}</TooltipTrigger>
+                <TooltipContent side="right" className="text-xs">
+                  Sign out
+                </TooltipContent>
+              </Tooltip>
+            );
+          })()}
+        </div>
+      </div>
+    </TooltipProvider>
+  );
+}

package/template/frontend/src/shell/nav.js

@@ -0,0 +1,103 @@
+/**
+ * The app navigation — a plain static menu (no role/redux coupling). Each item has
+ * an icon, label, path, and optional badge. Grouped into labelled sections.
+ *
+ * `gate` (Phase E slice 1): an optional permission KEY the item is hidden without. The
+ * Sidebar filters items via `useCan(item.gate)` — reading the `@astram/sdk` auth-facts
+ * projection (a UX convenience: hiding an unusable nav entry; NEVER the security
+ * boundary — the server's decide() on the underlying @Classified route is the real
+ * enforcement regardless of what the nav shows). Every `gate` value below was VERIFIED
+ * against the actual `@Classified({ typeKey, action })` on that page's list route (not
+ * guessed):
+ *   - Companies → `identity:company:read`  (identity.controller.ts `GET companies`)
+ *   - Users     → `identity:user:read`     (identity.controller.ts `GET users`)
+ *   - Roles     → `identity:role:read`     (identity.controller.ts `GET roles`)
+ *   - Access    → `identity:role:read`     (grant-admin.controller.ts backs this page
+ *                 via `GET access/role-grants` + `GET permission-catalog`, BOTH gated
+ *                 `role:read` — "managing/reading grants IS role administration")
+ *   - Audit     → `identity:role:read`     (audit.controller.ts `GET audit`)
+ *   - Cross-tenant → `identity:role:read`  (cross-tenant-grant.controller.ts `GET
+ *                 cross-tenant-grants` / `GET .../inbox` / `GET .../offerable-types`,
+ *                 all gated `role:read` — reading/managing cross-tenant grants IS role
+ *                 administration; the OFFER write is separately `cross_tenant_grant:share`)
+ * Dashboard / Account are left UNGATED — self/owned surfaces every authenticated
+ * caller may reach (no admin-only list route backs them).
+ */
+import {
+  Building2,
+  Handshake,
+  History,
+  KeyRound,
+  LayoutDashboard,
+  ShieldCheck,
+  UserCog,
+  Users,
+} from 'lucide-react';
+
+export const NAV_SECTIONS = [
+  {
+    label: 'Overview',
+    items: [{ icon: LayoutDashboard, label: 'Dashboard', path: '/dashboard', badge: null }],
+  },
+  {
+    label: 'Identity',
+    items: [
+      {
+        icon: Building2,
+        label: 'Companies',
+        path: '/companies',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:company:read',
+      },
+      {
+        icon: Users,
+        label: 'Users',
+        path: '/users',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:user:read',
+      },
+      {
+        icon: ShieldCheck,
+        label: 'Roles',
+        path: '/roles',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:role:read',
+      },
+      {
+        icon: KeyRound,
+        label: 'Access',
+        path: '/access',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:role:read',
+      },
+      {
+        icon: Handshake,
+        label: 'Cross-tenant',
+        path: '/cross-tenant',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:role:read',
+      },
+      {
+        icon: History,
+        label: 'Audit',
+        path: '/audit',
+        badge: null,
+        matchPrefix: true,
+        gate: 'identity:role:read',
+      },
+    ],
+  },
+  {
+    label: 'Settings',
+    // `/account` redirects to `/account/profile`; `matchPrefix` keeps the nav item
+    // highlighted across ALL /account/* sub-tabs (profile / password / 2fa).
+    items: [
+      { icon: UserCog, label: 'Account', path: '/account', badge: null, matchPrefix: true },
+    ],
+  },
+];

package/template/frontend/src/theme/ThemeProvider.jsx

@@ -0,0 +1,14 @@
+/**
+ * ThemeProvider — light/dark/system via next-themes (OCA-style dual theme).
+ * Stamps `.dark` on <html>; the tokens in index.css do the rest. `attribute="class"`
+ * matches the `@custom-variant dark (&:is(.dark *))` in index.css.
+ */
+import { ThemeProvider as NextThemes } from 'next-themes';
+
+export function ThemeProvider({ children }) {
+  return (
+    <NextThemes attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+      {children}
+    </NextThemes>
+  );
+}

package/template/frontend/src/theme/ThemeToggle.jsx

@@ -0,0 +1,44 @@
+/**
+ * ThemeToggle — an OCA-style Light/Dark/System segmented control (in the user menu
+ * or standalone). Uses next-themes; the active segment is highlighted.
+ */
+import { useEffect, useState } from 'react';
+import { useTheme } from 'next-themes';
+import { Monitor, Moon, Sun } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+const OPTIONS = [
+  { value: 'light', icon: Sun, label: 'Light' },
+  { value: 'dark', icon: Moon, label: 'Dark' },
+  { value: 'system', icon: Monitor, label: 'System' },
+];
+
+export default function ThemeToggle({ compact = false }) {
+  const { theme, setTheme } = useTheme();
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  const active = mounted ? theme : 'system';
+
+  return (
+    <div className="inline-flex items-center gap-0.5 rounded-lg border border-border bg-muted/50 p-0.5">
+      {OPTIONS.map(({ value, icon: Icon, label }) => (
+        <button
+          key={value}
+          type="button"
+          onClick={() => setTheme(value)}
+          aria-label={label}
+          title={label}
+          className={cn(
+            'flex items-center gap-1.5 rounded-md px-2 py-1 text-xs font-medium transition-colors',
+            active === value
+              ? 'bg-background text-foreground shadow-sm'
+              : 'text-muted-foreground hover:text-foreground',
+          )}
+        >
+          <Icon className="size-3.5" />
+          {!compact && <span>{label}</span>}
+        </button>
+      ))}
+    </div>
+  );
+}

package/template/frontend/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "strict": false,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}

package/template/frontend/vite.config.js

@@ -0,0 +1,30 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+import { fileURLToPath, URL } from 'node:url';
+
+/**
+ * __APP_NAME__ frontend — Vite config (shadcn/ui + Tailwind v4).
+ *
+ * `/api` is proxied to the framework server (default :3000), stripping the `/api`
+ * prefix so the browser calls same-origin `/api/auth/login` while the server sees
+ * `/auth/login`. `@` aliases `src/` (the shadcn import convention).
+ */
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': {
+        target: process.env.API_URL ?? 'http://localhost:3000',
+        changeOrigin: true,
+        rewrite: (path) => path.replace(/^\/api/, ''),
+      },
+    },
+  },
+});

package/template/server/_env.example

@@ -2,7 +2,6 @@
 #
 # Every value below has a safe default, so the app boots with NO .env file at all.
 # Copy this file to `.env` and override only what you need. `.env` is gitignored.
-#
 # These are read by `loadAppConfig()` from the installed @astram/guard framework.
 
 # HTTP port the app listens on (default: 3000).
@@ -13,21 +12,34 @@ NODE_ENV=development
 
 # --- ADR-0018 connection-pool budget (all optional; framework defaults apply) ---
 # Uncomment + tune only if your deployment needs to.
-# SHIELD_POOL_WORKERS=1
-# SHIELD_DB_MAX_CONNECTIONS=50
-# SHIELD_POOL_HEADROOM=5
-# SHIELD_POOL_MAX_CORE=10
-# SHIELD_POOL_MAX_APP_CRUD=10
-# SHIELD_POOL_MAX_SCHEMA_SVC=5
+# POOL_WORKERS=1
+# APP_DB_MAX_CONNECTIONS=50
+# POOL_HEADROOM=5
+# POOL_MAX_CORE=10
+# POOL_MAX_APP_CRUD=10
+# POOL_MAX_SCHEMA_SVC=5
 
 # --- OPTIONAL: real authentication (only if you set ShieldModule.forRoot({ auth: true })) ---
 # Auth needs a live MariaDB + Redis and a refresh-token HMAC key. These are
 # REQUIRED once auth is enabled (the app fails closed without the HMAC key) — but
-# irrelevant (unread) while auth is off. Point them at your MariaDB/Redis.
-# SHIELD_DB_HOST=127.0.0.1
-# SHIELD_DB_PORT=3306
-# SHIELD_DB_USER=shield_core
-# SHIELD_DB_PASSWORD=change-me
-# SHIELD_DB_DATABASE=shield_identity
-# SHIELD_REDIS_URL=redis://127.0.0.1:6379
-# SHIELD_REFRESH_HMAC_KEY=change-me-to-a-long-random-secret   # REQUIRED when auth is on
+# irrelevant (unread) while auth is off.
+#
+# Runtime app DB account (DML — the running server uses this):
+# APP_DB_HOST=127.0.0.1
+# APP_DB_PORT=3306
+# APP_DB_USER=shield_core
+# APP_DB_PASSWORD=change-me
+# APP_DB_NAME=shield_identity
+#
+# Deploy-time DDL account (CREATE/ALTER/DROP — used only by `npm run migration:run`,
+# NEVER by the running server; least-privilege). Host/port/db inherit APP_DB_* above.
+# DDL_DB_USER=shield_migrate
+# DDL_DB_PASSWORD=change-me
+#
+# Redis + refresh-token secret:
+# REDIS_URL=redis://127.0.0.1:6379
+# REFRESH_HMAC_KEY=change-me-to-a-long-random-secret   # REQUIRED when auth is on
+
+# --- Migrations (optional; @astram/identity's migrations run automatically) ---
+# APP_MIGRATION_DIR=migrations         # your app's own migrations, run after identity's
+# APP_MIGRATION_TABLE=schema_migrations

package/template/server/package.json

@@ -11,17 +11,20 @@
     "start": "node --env-file-if-exists=.env dist/main.js",
     "dev": "node scripts/dev.mjs",
     "test": "vitest run",
+    "migration:run": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate",
+    "migration:status": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate:status",
+    "migration:revert": "node --env-file-if-exists=.env node_modules/@astram/migrate/dist/cli.js migrate:revert",
     "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
     "guide:sync": "node scripts/sync-astram-guide.mjs",
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
     "@astram/core": "^1.0.0",
-    "@astram/engine": "^0.1.0",
-    "@astram/guard": "^0.3.0",
+    "@astram/engine": "^0.1.3",
+    "@astram/guard": "^0.5.0",
     "@astram/guide": "^0.1.0",
-    "@astram/identity": "^0.1.0",
-    "@astram/migrate": "^0.1.0",
+    "@astram/identity": "^0.2.0",
+    "@astram/migrate": "^0.2.0",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",

package/template/server/src/app.module.ts

@@ -35,10 +35,36 @@ import { DemoController } from './health/demo.controller';
  * You then get framework-owned `POST /auth/{login,mfa,refresh,logout}` for free —
  * no controllers to write. (Leaving `auth` off keeps the zero-config enforcement
  * boot; turning it on requires the config above, by design — fail-closed.)
+ *
+ * ── OPTIONAL: the identity ADMIN CONSOLE (companies/users/roles CRUD) ──────────
+ * The framework also ships the identity management surface — company/user/role CRUD
+ * (memberships, access, audit in later versions) — as controllers you mount by
+ * importing ONE module. `@astram/guard` never imports `@astram/identity` (the
+ * dependency graph is identity → guard), so the consumer wires it (ADR-0026):
+ *   1. Turn auth on (above), pass the identity permission keys (so the frontend admin
+ *      nav lights up), AND pass `recordAuthorization` (so the decision guard actually
+ *      GRANTS — without it, decide() denies every classified route):
+ *        import { identityAuthActionKeys, identityControlPlaneKeys, IdentityFeatureModule,
+ *                 createIdentityAuthzPool, buildIdentityRecordAuthorization } from '@astram/identity';
+ *        const authzPool = createIdentityAuthzPool();
+ *        imports: [
+ *          ShieldModule.forRoot({ auth: true,
+ *            identityActionKeys: identityAuthActionKeys, identityControlPlaneKeys,
+ *            recordAuthorization: buildIdentityRecordAuthorization(authzPool) }),
+ *          IdentityFeatureModule.forRoot(),   // mounts /identity/{companies,users,roles}
+ *        ],
+ *   `IdentityFeatureModule.forRoot()` self-wires the engine from your `APP_DB_*` env
+ *   (no separate engine setup). Every route is `@Classified` — enforced by the same
+ *   deny-by-default guard; `recordAuthorization` makes that guard render REAL decisions
+ *   from your roles' grants. Omit the module and login still works; the admin pages 404.
  */
 @Module({
-  // Enforcement-only by default (boots with no config). For real login, use:
-  //   imports: [ShieldModule.forRoot({ auth: true })],
+  // Enforcement-only by default (boots with no config). For real login + the identity
+  // admin console, use (see the OPTIONAL blocks above for the full form):
+  //   imports: [
+  //     ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys }),
+  //     IdentityFeatureModule.forRoot(),
+  //   ],
   imports: [ShieldModule.forRoot()],
   controllers: [HealthController, DemoController],
 })

package/template/server/src/health/demo.controller.ts

@@ -2,15 +2,23 @@ import { Controller, Get } from '@nestjs/common';
 import { Public } from '@astram/guard';
 
 /**
- * Demonstration routes proving the deny-by-default enforcement seam (ADR-0002).
+ * Demonstration route proving the enforcement seam (ADR-0002).
  *
- * - `GET /demo/public`       → `@Public()`  → REACHABLE (200).
- * - `GET /demo/unclassified` → no metadata  → DENIED by the global guard (403).
+ * - `GET /demo/public` → `@Public()` → REACHABLE (200): an explicit opt-out of the
+ *   deny-by-default global guard.
  *
- * The second handler carries NO classification decorator on purpose: it shows
- * that forgetting to declare a route locks the door (deny-by-default) rather than
- * silently exposing it. This controller is illustrative — delete it once you've
- * seen enforcement work; a real feature would classify every route.
+ * Deny-by-default has TWO layers, and they differ in WHEN they bite:
+ *   1. **Boot-time (fail-closed, strongest):** the identity boot check (`verifyGatable`)
+ *      scans every route and ABORTS BOOT if any non-`@Public` route lacks `@Classified`.
+ *      A forgotten declaration doesn't just get denied at request time — the app won't
+ *      start. That is why the illustrative "unclassified route" below is a COMMENT, not a
+ *      live handler: a live one would prevent this app from booting. Uncomment it only to
+ *      SEE the boot abort, then re-comment (or classify it).
+ *   2. **Request-time (per-request):** even absent the boot check, the global guard denies
+ *      an unclassified route with 403.
+ *
+ * This controller is illustrative — delete it once you've seen enforcement work; a real
+ * feature classifies every route with `@Public()` or `@Classified(...)`.
  */
 @Controller('demo')
 export class DemoController {
@@ -20,9 +28,12 @@ export class DemoController {
     return { message: 'public route reachable — explicit @Public() opt-out' };
   }
 
-  // NOTE: intentionally NO @Public() / @Classified() — must be DENIED (403).
-  @Get('unclassified')
-  unclassifiedRoute(): { message: string } {
-    return { message: 'this body must never be reached — the guard denies first' };
-  }
+  // Intentionally NO @Public() / @Classified(). Kept as a COMMENT because the boot-time
+  // `verifyGatable` (fail-closed) aborts boot on any unclassified route — a live handler
+  // here would stop the app from starting. Uncomment to witness the boot abort, then
+  // re-comment or classify it.
+  // @Get('unclassified')
+  // unclassifiedRoute(): { message: string } {
+  //   return { message: 'this body must never be reached — the guard denies first' };
+  // }
 }