create-astram-app 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-astram-app",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "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/README.md

@@ -80,7 +80,15 @@ the credential store, MFA, session handling and the decision authority; you writ
 ### Before you deploy with auth on
 
 - Pass an `emailSender` (or `'disabled'`): outside `NODE_ENV=development|test` boot fails
-  without one. Set `NODE_ENV=production` explicitly; `npm start` does not set it.
+  without one. Set `NODE_ENV=production` explicitly; `npm start` does not set it. The easiest is
+  `emailSender: 'env'`: the provider (SMTP, Brevo, SendGrid or Mailgun) comes from `EMAIL_PROVIDER`
+  and the MESSAGING block in `server/_env.example`, with no mail code in the app. It needs
+  `@astram/messaging` installed (the template already lists it) and, outside development, a
+  `SECRETS_PROVIDER` for the credentials. Every framework email is then bounded and audited, and
+  admins can invite pending users from the Users page.
+- Keep the framework pins in `server/package.json` exact (`@astram/core`, `engine`, `guard`,
+  `identity`, `migrate`): the packages pin each other exactly, and a `^` range can install a
+  second `@astram/core`. `npm ls @astram/core` must show one copy.
 - Set `RESET_LINK_BASE_URL` and `EMAIL_CHANGE_LINK_BASE_URL` to your public reset-password and
   confirm-email pages: with an `emailSender`, production boot fails when either is unset or
   points at localhost.
@@ -134,9 +142,12 @@ ASTRAM_BOOTSTRAP_OPERATOR=jane.doe npm run bootstrap:org -- --file ../deploy/org
 ```
 
 - Flags: `--apply`, `--claim-unowned-roles`, `--reissue-links`, `--link-ttl-hours <n>`,
-  `--links-to-stdout`, `--interactive` (prompt for root passwords without echo).
+  `--links-to-stdout`, `--email-links`, `--interactive` (prompt for root passwords without echo).
 - Every non-root user gets a one-time set-password link, printed once, only to a terminal
   (pass `--links-to-stdout` to print them to a pipe). Links are never logged or written to a file.
+  With `emailSender` configured, `--email-links` emails each link to its user instead. Root
+  users' links are never emailed (a root link is a platform takeover): they are printed to a
+  terminal as before, or reported as not delivered.
 - Root passwords come from `ASTRAM_BOOTSTRAP_ROOT_PASSWORD_<USERNAME>` (a `secret-ref:` outside
   development) or `--interactive`. Put the printed root uuids in `SHIELD_ROOT_IDS` and pass
   `rootIdsFromEnv()` to both `forRoot` calls (see `server/_env.example`).

package/template/frontend/src/auth/resetWording.js

@@ -0,0 +1,28 @@
+// resetWording.js — the reset page's words (G-010 R11, AC-15). An invite link carries
+// `purpose=invite`; it opens the same page and posts the same token to the same
+// `POST /auth/reset-password`, so the marker changes wording only and grants nothing.
+
+const RESET = Object.freeze({
+  isInvite: false,
+  title: 'Choose a new password',
+  subtitle: 'Enter a new password for your account.',
+  submit: 'Reset password',
+  success: 'Your password has been reset. Please sign in with your new password.',
+  deadLink: 'Request a new reset link',
+});
+
+const INVITE = Object.freeze({
+  isInvite: true,
+  title: 'Set your password',
+  subtitle: 'Choose a password to finish setting up your account.',
+  submit: 'Set password',
+  success: 'Your password is set. Please sign in.',
+  deadLink: 'Ask your administrator for a new invite',
+});
+
+/**
+ * @param {string | null | undefined} purpose the link's `purpose` query value
+ */
+export function resetWording(purpose) {
+  return purpose === 'invite' ? INVITE : RESET;
+}

package/template/frontend/src/auth/resetWording.test.mjs

@@ -0,0 +1,35 @@
+// resetWording.test.mjs — G-010 AC-15: an invite link (`purpose=invite`) opens the same reset
+// page with "Set your password" wording; any other link keeps the reset wording. The marker only
+// changes words: the page posts the same token to the same route either way.
+//
+//   node --test src/auth/resetWording.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { resetWording } from './resetWording.js';
+
+describe('resetWording', () => {
+  test('purpose=invite → set-password wording', () => {
+    const w = resetWording('invite');
+    assert.equal(w.isInvite, true);
+    assert.equal(w.title, 'Set your password');
+    assert.equal(w.subtitle, 'Choose a password to finish setting up your account.');
+    assert.equal(w.submit, 'Set password');
+    assert.equal(w.success, 'Your password is set. Please sign in.');
+    assert.equal(w.deadLink, 'Ask your administrator for a new invite');
+  });
+
+  test('anything else → today’s reset wording', () => {
+    for (const purpose of [null, undefined, '', 'reset', 'INVITE', 'invite ']) {
+      const w = resetWording(purpose);
+      assert.equal(w.isInvite, false);
+      assert.equal(w.title, 'Choose a new password');
+      assert.equal(w.subtitle, 'Enter a new password for your account.');
+      assert.equal(w.submit, 'Reset password');
+      assert.equal(
+        w.success,
+        'Your password has been reset. Please sign in with your new password.',
+      );
+      assert.equal(w.deadLink, 'Request a new reset link');
+    }
+  });
+});

package/template/frontend/src/pages/ResetPassword.jsx

@@ -18,6 +18,7 @@ import { Label } from '@/components/ui/label';
 import { Card, CardContent } from '@/components/ui/card';
 import ThemeToggle from '@/theme/ThemeToggle';
 import { branding } from '@/config/branding';
+import { resetWording } from '@/auth/resetWording';
 
 const MIN_PASSWORD_LEN = 8;
 
@@ -26,6 +27,8 @@ export default function ResetPassword() {
   const navigate = useNavigate();
   const [params] = useSearchParams();
   const token = params.get('token') ?? '';
+  // G-010: invite links carry `purpose=invite` (wording only; the same token, the same route).
+  const words = resetWording(params.get('purpose'));
 
   const [next, setNext] = useState('');
   const [confirm, setConfirm] = useState('');
@@ -59,7 +62,7 @@ export default function ResetPassword() {
     setBusy(false);
 
     if (r.ok) {
-      toast.success('Your password has been reset. Please sign in with your new password.');
+      toast.success(words.success);
       navigate('/login', { replace: true });
       return;
     }
@@ -89,10 +92,8 @@ export default function ResetPassword() {
               className="hidden h-9 w-auto dark:block"
             />
             <div className="text-center">
-              <h1 className="text-xl font-bold tracking-tight">Choose a new password</h1>
-              <p className="mt-1 text-sm text-muted-foreground">
-                Enter a new password for your account.
-              </p>
+              <h1 className="text-xl font-bold tracking-tight">{words.title}</h1>
+              <p className="mt-1 text-sm text-muted-foreground">{words.subtitle}</p>
             </div>
           </div>
 
@@ -105,12 +106,16 @@ export default function ResetPassword() {
 
           {linkDead ? (
             <div className="text-center">
-              <Link
-                to="/forgot-password"
-                className="inline-flex items-center gap-1.5 text-sm font-medium text-primary hover:underline"
-              >
-                Request a new reset link
-              </Link>
+              {words.isInvite ? (
+                <p className="text-sm text-muted-foreground">{words.deadLink}</p>
+              ) : (
+                <Link
+                  to="/forgot-password"
+                  className="inline-flex items-center gap-1.5 text-sm font-medium text-primary hover:underline"
+                >
+                  {words.deadLink}
+                </Link>
+              )}
             </div>
           ) : (
             <form onSubmit={onSubmit} className="space-y-4" noValidate>
@@ -143,7 +148,7 @@ export default function ResetPassword() {
                 ) : (
                   <>
                     <KeyRound className="size-4" />
-                    Reset password
+                    {words.submit}
                   </>
                 )}
               </Button>

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

@@ -8,18 +8,24 @@
  * The user EDIT page (/users/edit/:uuid) is where the Assignments (membership + posting)
  * editor will live in Phase 5 — UserForm leaves a clear placeholder for it.
  *
+ * Invite (G-010): a "Sign-in" column shows whether each user has set a password yet
+ * (`row.signInStatus`, computed server-side), with an Invite button for pending users when the
+ * caller holds identity:user:invite (`inviteAction.js`; UX only, the server decides).
+ *
  * ⛔ No raw UUIDs: columns render username/email/status; `row.id` is a key/route param only.
  */
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useEffect, useMemo, useState } from 'react';
 import { Outlet, useNavigate, useSearchParams } from 'react-router-dom';
-import { Users } from 'lucide-react';
+import { Send, Users } 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';
 import ConfirmDialog from '@/components/ConfirmDialog';
 import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { INVITE_PERMISSION, canInvite, inviteOutcome } from './inviteAction';
 
 /** Compact absolute date — e.g. "13 Jul 2026"; '—' when missing/invalid. */
 function formatDate(v) {
@@ -35,6 +41,38 @@ function formatDate(v) {
   }
 }
 
+/** Sign-in status badge text (server-computed `signInStatus`). */
+const SIGN_IN_LABEL = { pending: 'Pending', active: 'Active', none: 'No sign-in' };
+
+/** The Sign-in column: status badge + Invite for pending users (G-010). Not sortable. */
+function signInColumn(holdsInvite, invitingId, onInvite) {
+  return {
+    key: 'signInStatus',
+    label: 'Sign-in',
+    sortable: false,
+    render: (row) => (
+      <div className="flex items-center gap-2">
+        <Badge variant={row.signInStatus === 'active' ? 'success' : 'secondary'}>
+          {SIGN_IN_LABEL[row.signInStatus] ?? '—'}
+        </Badge>
+        {canInvite(row, holdsInvite) && (
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            disabled={invitingId === row.id}
+            onClick={() => onInvite(row)}
+            aria-label={`Invite ${row.fields?.username || 'this user'}`}
+          >
+            <Send className="size-4" />
+            Invite
+          </Button>
+        )}
+      </div>
+    ),
+  };
+}
+
 // Sortable columns (server-side): Username, Email, Status, Created.
 const COLUMNS = [
   {
@@ -121,6 +159,9 @@ export default function UsersPage() {
     setSearchParams(p, { replace: true });
   }, [query, setSearchParams]);
 
+  const holdsInvite = useCan(INVITE_PERMISSION);
+  const [invitingId, setInvitingId] = useState(null);
+
   const [deleteTarget, setDeleteTarget] = useState(null);
   const [deleteBusy, setDeleteBusy] = useState(false);
 
@@ -152,6 +193,40 @@ export default function UsersPage() {
   const onPageChange = useCallback((page) => setQuery((q) => ({ ...q, page })), []);
   const onLimitChange = useCallback((limit) => setQuery((q) => ({ ...q, limit, page: 1 })), []);
 
+  const onInvite = useCallback(
+    async (row) => {
+      if (!token || invitingId) return;
+      setInvitingId(row.id);
+      const outcome = inviteOutcome(await identity.inviteUser(token, row.id));
+      setInvitingId(null);
+      if (outcome.kind === 'error') {
+        toast.error(outcome.text);
+        return;
+      }
+      if (outcome.link) {
+        // The one-time link is shown nowhere else: copy it, or show it once if the copy fails.
+        try {
+          await navigator.clipboard.writeText(outcome.link);
+          toast.success(outcome.text);
+        } catch {
+          toast.success(outcome.text.replace('Link copied', 'Copy this link now'), {
+            description: outcome.link,
+            duration: 60_000,
+          });
+        }
+      } else {
+        toast.success(outcome.text);
+      }
+    },
+    [identity, token, invitingId],
+  );
+
+  const columns = useMemo(() => {
+    const out = [...COLUMNS];
+    out.splice(3, 0, signInColumn(holdsInvite, invitingId, onInvite));
+    return out;
+  }, [holdsInvite, invitingId, onInvite]);
+
   const onConfirmDelete = async () => {
     if (!deleteTarget) return;
     setDeleteBusy(true);
@@ -185,7 +260,7 @@ export default function UsersPage() {
         />
 
         <EntityList
-          columns={COLUMNS}
+          columns={columns}
           rows={rows}
           search={query.search}
           sortBy={query.sortBy}

package/template/frontend/src/pages/users/inviteAction.js

@@ -0,0 +1,37 @@
+// inviteAction.js — the Users page's Invite action (G-010 R13, AC-16). Pure logic, tested by
+// inviteAction.test.mjs; UsersPage renders from it. Showing or hiding the action is UX only: the
+// server decides (`POST /identity/users/:uuid/invite` needs identity:user:invite, the tenant wall
+// and the dominance ceiling).
+
+/** The permission key the invite route is gated on. */
+export const INVITE_PERMISSION = 'identity:user:invite';
+
+/**
+ * Show Invite for this row? Only for users whose sign-in is still pending (created or invited,
+ * no password yet) and only when the caller holds {@link INVITE_PERMISSION}.
+ * @param {{ signInStatus?: string } | null | undefined} row
+ * @param {boolean} holdsInvite
+ */
+export function canInvite(row, holdsInvite) {
+  return Boolean(holdsInvite && row && row.signInStatus === 'pending');
+}
+
+/**
+ * The toast for an `identity.inviteUser` result. A returned one-time link (only when the app opted
+ * in to `returnLinkToAdmin`) is handed back for the page to copy to the clipboard.
+ * @param {{ ok: boolean, emailed?: boolean, link?: string, error?: string }} result
+ * @returns {{ kind: 'success' | 'error', text: string, link?: string }}
+ */
+export function inviteOutcome(result) {
+  if (!result || !result.ok) {
+    return { kind: 'error', text: (result && result.error) || 'Could not invite the user.' };
+  }
+  if (result.link) {
+    return {
+      kind: 'success',
+      text: result.emailed ? 'Invite sent · Link copied' : 'Link copied',
+      link: result.link,
+    };
+  }
+  return { kind: 'success', text: 'Invite sent' };
+}

package/template/frontend/src/pages/users/inviteAction.test.mjs

@@ -0,0 +1,63 @@
+// inviteAction.test.mjs — G-010 AC-16: the Users page shows Invite only for users whose sign-in
+// is still pending, and only to callers holding identity:user:invite (UX only; the server decides).
+//
+//   node --test src/pages/users/inviteAction.test.mjs
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { INVITE_PERMISSION, canInvite, inviteOutcome } from './inviteAction.js';
+
+describe('canInvite', () => {
+  test('the permission key is identity:user:invite', () => {
+    assert.equal(INVITE_PERMISSION, 'identity:user:invite');
+  });
+
+  test('pending users, for a caller who holds the key', () => {
+    assert.equal(canInvite({ id: 'u1', signInStatus: 'pending' }, true), true);
+  });
+
+  test('never for active users, users with no credential, or unknown status', () => {
+    for (const signInStatus of ['active', 'none', undefined, 'PENDING']) {
+      assert.equal(canInvite({ id: 'u1', signInStatus }, true), false);
+    }
+  });
+
+  test('never without the permission, or without a row', () => {
+    assert.equal(canInvite({ id: 'u1', signInStatus: 'pending' }, false), false);
+    assert.equal(canInvite(null, true), false);
+  });
+});
+
+describe('inviteOutcome', () => {
+  test('emailed → "Invite sent"', () => {
+    assert.deepEqual(inviteOutcome({ ok: true, emailed: true }), {
+      kind: 'success',
+      text: 'Invite sent',
+    });
+  });
+
+  test('a returned link → copy it, "Link copied"; emailed too → both', () => {
+    const link = 'https://app.example/reset-password?token=t&purpose=invite';
+    assert.deepEqual(inviteOutcome({ ok: true, emailed: false, link }), {
+      kind: 'success',
+      text: 'Link copied',
+      link,
+    });
+    assert.deepEqual(inviteOutcome({ ok: true, emailed: true, link }), {
+      kind: 'success',
+      text: 'Invite sent · Link copied',
+      link,
+    });
+  });
+
+  test('failures show the service message (409 reasons included)', () => {
+    const reason = 'This user has already set a password. Use forgot-password instead.';
+    assert.deepEqual(inviteOutcome({ ok: false, status: 409, error: reason }), {
+      kind: 'error',
+      text: reason,
+    });
+    assert.deepEqual(inviteOutcome({ ok: false, status: 500, error: '' }), {
+      kind: 'error',
+      text: 'Could not invite the user.',
+    });
+  });
+});

package/template/server/_env.example

@@ -135,6 +135,43 @@ NODE_ENV=development
 # Upload size cap in bytes (default 10 MiB; above the 50 MiB ceiling fails boot).
 # OBJECT_STORAGE_MAX_BYTES=10485760
 
+# --- OPTIONAL: MESSAGING — email delivery (G-010) ---
+# Read only when src/app.module.ts passes ShieldModule.forRoot({ auth: true, emailSender: 'env' })
+# (install @astram/messaging). Password resets, admin invites, email-change confirmation and
+# security notices go out through this provider; every send is bounded and audited.
+# One of smtp | brevo | sendgrid | mailgun | disabled (no default: unset fails boot).
+# EMAIL_PROVIDER=brevo
+# EMAIL_FROM_ADDRESS=no-reply@example.com
+# EMAIL_FROM_NAME=Example
+# Provider credentials: outside development/test they MUST be `secret-ref:` references, which
+# needs SECRETS_PROVIDER configured (above). A literal value fails boot.
+# BREVO_API_KEY=secret-ref:mail/brevo-api-key
+# SENDGRID_API_KEY=secret-ref:mail/sendgrid-api-key
+# MAILGUN_API_KEY=secret-ref:mail/mailgun-api-key
+# MAILGUN_DOMAIN=mg.example.com
+# MAILGUN_REGION=us
+# Optional https base for an HTTP provider (a relay or test stub); http is refused.
+# EMAIL_API_BASE_URL=
+# SMTP: TLS is starttls (default, port 587) or implicit (465); none only to a loopback host
+# outside development/test. Certificates are always verified; SMTP_TLS_CA adds a private CA.
+# SMTP_HOST=smtp.example.com
+# SMTP_PORT=587
+# SMTP_TLS=starttls
+# SMTP_USER=mailer
+# SMTP_PASSWORD=secret-ref:mail/smtp-password
+# SMTP_TLS_CA=/etc/ssl/private-ca.pem
+# Per-send bound in ms (default 10000, max 30000; one retry on a temporary failure inside it).
+# MESSAGE_SEND_TIMEOUT_MS=10000
+# 1 = check reachability and credentials at boot without sending (a failure refuses boot).
+# MESSAGE_BOOT_PROBE=1
+# SMS and WhatsApp: ports only this release; anything but `disabled` fails boot.
+# SMS_PROVIDER=disabled
+# WHATSAPP_PROVIDER=disabled
+# Admin invites (POST /identity/users/:uuid/invite): link lifetime in hours (1-168, default 72)
+# and invites per admin per hour (default 30).
+# INVITE_LINK_TTL_HOURS=72
+# INVITE_RATE_PER_ADMIN=30
+
 # --- OPTIONAL: organisation bootstrap (`npm run bootstrap:org`; needs IdentityFeatureModule wired) ---
 # Platform-root user uuids, comma-separated, lower-case canonical form. Read by rootIdsFromEnv()
 # in src/app.module.ts (pass it to BOTH forRoot calls); bootstrap:org prints the uuid of each root.

package/template/server/package.json

@@ -21,12 +21,13 @@
     "postinstall": "node scripts/sync-astram-guide.mjs"
   },
   "dependencies": {
-    "@astram/core": "^1.8.0",
-    "@astram/engine": "^0.10.0",
-    "@astram/guard": "^0.17.0",
+    "@astram/core": "1.9.0",
+    "@astram/engine": "0.10.1",
+    "@astram/guard": "0.18.0",
     "@astram/guide": "^0.2.8",
-    "@astram/identity": "^0.14.0",
-    "@astram/migrate": "^0.6.0",
+    "@astram/identity": "0.15.0",
+    "@astram/messaging": "^0.1.1",
+    "@astram/migrate": "0.6.1",
     "@astram/sdk": "^0.2.0",
     "@nestjs/common": "^11.2.7",
     "@nestjs/core": "^11.2.7",

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

@@ -39,7 +39,14 @@ import { DemoController } from './health/demo.controller';
  *   4. Outside development/test (`NODE_ENV`), `auth: true` also requires an
  *      `emailSender` (or `emailSender: 'disabled'`) — otherwise boot fails closed —
  *      and, with a sender, public `RESET_LINK_BASE_URL` / `EMAIL_CHANGE_LINK_BASE_URL`
- *      (not localhost; see `.env.example`).
+ *      (not localhost; see `.env.example`). The simplest sender is configuration only:
+ *      `ShieldModule.forRoot({ auth: true, emailSender: 'env' })` with `EMAIL_PROVIDER`
+ *      (smtp | brevo | sendgrid | mailgun | disabled), `EMAIL_FROM_ADDRESS` and the
+ *      provider's variables (MESSAGING block in `.env.example`; credentials must be
+ *      `secret-ref:` values outside development/test, so set up `SECRETS_PROVIDER` first).
+ *      Admins can then invite users (`POST /identity/users/:uuid/invite`, the Users page
+ *      Invite button); `IdentityFeatureModule.forRoot({ invite: { returnLinkToAdmin: true } })`
+ *      also shows the one-time link to the admin once.
  * 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.)

package/template/server/src/bootstrap-org.args.ts

@@ -15,6 +15,8 @@ export interface BootstrapArgs {
   /** Link lifetime in whole hours; the runner validates the range. */
   linkTtlHours: number | undefined;
   linksToStdout: boolean;
+  /** Email the set-password links (needs a configured emailSender) instead of printing them. */
+  emailLinks: boolean;
   /** Prompt for the root passwords (no echo) instead of reading the environment. */
   interactive: boolean;
 }
@@ -28,7 +30,7 @@ export class BootstrapArgsError extends Error {
 
 export const BOOTSTRAP_USAGE =
   'usage: npm run bootstrap:org -- --file <path> [--apply] [--claim-unowned-roles] ' +
-  '[--reissue-links] [--link-ttl-hours <n>] [--links-to-stdout] [--interactive]';
+  '[--reissue-links] [--link-ttl-hours <n>] [--links-to-stdout | --email-links] [--interactive]';
 
 export function parseBootstrapArgs(argv: readonly string[]): BootstrapArgs {
   const args: BootstrapArgs = {
@@ -38,6 +40,7 @@ export function parseBootstrapArgs(argv: readonly string[]): BootstrapArgs {
     reissueLinks: false,
     linkTtlHours: undefined,
     linksToStdout: false,
+    emailLinks: false,
     interactive: false,
   };
   for (let i = 0; i < argv.length; i += 1) {
@@ -64,6 +67,9 @@ export function parseBootstrapArgs(argv: readonly string[]): BootstrapArgs {
       case '--links-to-stdout':
         args.linksToStdout = true;
         break;
+      case '--email-links':
+        args.emailLinks = true;
+        break;
       case '--interactive':
         args.interactive = true;
         break;
@@ -83,5 +89,8 @@ export function parseBootstrapArgs(argv: readonly string[]): BootstrapArgs {
     }
   }
   if (args.file === '') throw new BootstrapArgsError('--file <path> is required');
+  if (args.emailLinks && args.linksToStdout) {
+    throw new BootstrapArgsError('--email-links cannot be combined with --links-to-stdout');
+  }
   return args;
 }

package/template/server/src/bootstrap-org.ts

@@ -12,10 +12,13 @@ import {
 } from './bootstrap-org.args';
 
 /**
- * `npm run bootstrap:org -- --file org.json [--apply]`: creates your organisation (tenants,
+ * `npm run bootstrap:org -- --file org.json [--apply] [--email-links]`: creates your organisation (tenants,
  * companies, roles, users, grants) from a declarative file, through the framework's own
  * services, against THIS app's `AppModule` (so grants can name your own object types).
  * Without `--apply` it is a dry run that prints the plan and writes nothing.
+ * Set-password links print to the terminal; with `--email-links` (needs an `emailSender` in
+ * `ShieldModule.forRoot`) each one is emailed instead and none is printed, except ROOT links:
+ * those are never emailed and print only to a terminal (or with `--links-to-stdout`).
  *
  * No security logic lives here: `runOrgBootstrap` (from `@astram/identity`) does the work.
  * Same boot order as `main.ts`: `resolveBootSecrets()` runs BEFORE `AppModule` is loaded,
@@ -63,6 +66,7 @@ async function run(args: BootstrapArgs): Promise<number> {
       reissueLinks: args.reissueLinks,
       ...(args.linkTtlHours !== undefined ? { linkTtlHours: args.linkTtlHours } : {}),
       linksToStdout: args.linksToStdout,
+      emailLinks: args.emailLinks,
       ...(process.env.ASTRAM_BOOTSTRAP_OPERATOR !== undefined
         ? { operator: process.env.ASTRAM_BOOTSTRAP_OPERATOR }
         : {}),
@@ -78,7 +82,12 @@ async function run(args: BootstrapArgs): Promise<number> {
     // Counts only: links and passwords were already shown through `out`, never repeated.
     console.log(
       `${report.applied ? 'applied' : 'dry run (nothing written; pass --apply to write)'}: ` +
-        `${report.plan.entries.length} planned, ${report.links} link(s) issued, ` +
+        `${report.plan.entries.length} planned, ${report.links} link(s) issued` +
+        (args.emailLinks
+          ? ` (${report.linksEmailed} emailed, ${report.linksPrintedRoots} root link(s) printed, ` +
+            `${report.linksNotEmailed} not delivered)`
+          : '') +
+        ', ' +
         `${report.rootIds.length} root(s)`,
     );
     return 0;
@@ -104,7 +113,8 @@ async function main(): Promise<void> {
   } catch (err) {
     process.exitCode = 1;
     if (err instanceof OrgBootstrapError) {
-      if (err.code === 'not_wired') {
+      // `--email-links` without a sender is also `not_wired`; its own message says what to set.
+      if (err.code === 'not_wired' && !err.message.startsWith('--email-links')) {
         console.error(
           'wire IdentityFeatureModule in AppModule before running bootstrap:org (see the header of src/app.module.ts)',
         );