@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': minor
+'@objectstack/plugin-auth': minor
+---
+
+feat(spec,plugin-auth): a `demoStaff` entry names its line manager, and the development boot writes it
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+
+A `demoStaff` entry declares one optional key, `manager`: the `email` of another entry of the same `demoStaff` list, compared without regard to case. It is named by address because the address identifies an account everywhere the platform provisions one; a display name is a label a person can edit. Before, the entry was strict and refused the key, so a fresh demo's `manager` approval rung reached nobody until someone ran Setup → Users → Set Manager by hand.
+
+`defineStack` (and so `os validate`) refuses, with `STACK_CROSS_REFERENCE_INVALID` 422, a `manager` that is the address of no entry, an entry that names itself, and managers that form a loop. A manager written as a display name is refused at the entry's path, saying it takes an address. `reportsTo`, `managerEmail`, `managerId` (and so `manager_id`) and `supervisor` are pointed to `manager`.
+
+On an `os dev` boot, `@objectstack/plugin-auth` links each declared manager in a second pass, once every entry has its account and still before the application seed runs. Each link goes through the same checks as `POST /api/v1/auth/admin/set-user-manager`. A link is written only when the account has no manager, so a manager someone set by hand is left as it is on every later boot; a manager cleared by hand reads as no manager and is written again. A link that cannot be written (the manager's own entry was not provisioned, or the set-manager checks refuse it) is reported on the boot log under the subordinate's address. `DemoStaffOutcome` gains `managersLinked` and `managersKept`.
@@ -32,6 +32,7 @@ const result = DemoStaffSchema.parse(data);
 | **email** | `string` | ✅ | Sign-in address of the demo account |
 | **position** | `string` | optional | A position this application declares in `positions`, assigned to the demo account |
 | **permissionSets** | `string[]` | optional | Permission sets this application declares in `permissions`, granted to the demo account |
+| **manager** | `string` | optional | Line manager of the demo account: the email of another demoStaff entry, written as its manager_id by the development boot |
 
 
 ---
 
@@ -2517,16 +2517,23 @@ export class AuthPlugin implements Plugin {
         }
       },
       defaultOrganizationId: async () => (tenancy ? await tenancy.defaultOrgId() : null),
+      logger: ctx.logger,
     });
 
     for (const failure of outcome.failed) {
       ctx.logger.warn(`[auth] demoStaff: ${failure.email} was not provisioned — ${failure.message}`);
     }
-    if (outcome.created.length > 0 || outcome.assignmentsAdded > 0) {
+    if (outcome.managersKept.length > 0) {
+      ctx.logger.info(
+        `[auth] demoStaff: ${outcome.managersKept.join(', ')} already had a manager other than the declared one, ` +
+          'set by hand; it was left as it is.',
+      );
+    }
+    if (outcome.created.length > 0 || outcome.assignmentsAdded > 0 || outcome.managersLinked > 0) {
       ctx.logger.info(
         `[auth] demoStaff: ${outcome.created.length} demo account(s) created, ${outcome.present.length} already ` +
-          `present, ${outcome.assignmentsAdded} assignment(s) added — they sign in with the development seed ` +
-          `password (${password}).`,
+          `present, ${outcome.assignmentsAdded} assignment(s) added, ${outcome.managersLinked} manager(s) linked — ` +
+          `they sign in with the development seed password (${password}).`,
       );
     } else {
       ctx.logger.debug(`[auth] demoStaff: all ${outcome.present.length} demo account(s) already present`);
 
@@ -31,6 +31,7 @@ import { SecurityPlugin } from '@objectstack/plugin-security';
 import { AuthPlugin, type DemoStaffingService } from './auth-plugin.js';
 import type { AuthManager } from './auth-manager.js';
 import type { DemoStaffOutcome, DemoStaffRefusal } from './demo-staff.js';
+import type { DemoStaffParsed } from '@objectstack/spec/system';
 
 const SYS = { isSystem: true } as const;
 const BASE = 'http://localhost:3000';
@@ -102,12 +103,12 @@ describe('the development boot provisions the stack`s demo accounts (#25777)', (
     vi.restoreAllMocks();
   });
 
-  async function boot(options: { baseUrl?: string } = {}) {
+  async function boot(options: { baseUrl?: string; staff?: readonly DemoStaffParsed[] } = {}) {
     const step = vi.spyOn(
       AuthPlugin.prototype as unknown as { maybeProvisionDemoStaff(ctx: PluginContext): Promise<StaffingAnswer> },
       'maybeProvisionDemoStaff',
     );
-    const auth = new AuthPlugin({ secret: SECRET, baseUrl: options.baseUrl ?? BASE, demoStaff: STAFF });
+    const auth = new AuthPlugin({ secret: SECRET, baseUrl: options.baseUrl ?? BASE, demoStaff: options.staff ?? STAFF });
     kernel = new ObjectKernel({ logger: { level: 'silent' } });
     await kernel.use(sqliteDriverPlugin());
     await kernel.use(new ObjectQLPlugin());
@@ -288,4 +289,42 @@ describe('the development boot provisions the stack`s demo accounts (#25777)', (
     // On a development boot the developer loses the accounts: warned.
     expect((await rerun()).logs.map((l) => l.level)).toEqual(['warn']);
   }, 30_000);
+  /**
+   * The managers: Paralegal 1 reports to Legal Counsel 1 (declared before it,
+   * named in another case), and Legal Counsel 1 to Legal Lead (declared after
+   * it), so both orders of the second pass are on the real composition.
+   */
+  const MANAGED_STAFF: DemoStaffParsed[] = [
+    { ...STAFF[0]!, manager: 'lead@legal.example' },
+    { ...STAFF[1]!, manager: 'COUNSEL1@legal.example' },
+    { name: 'Legal Lead', email: 'lead@legal.example' },
+  ];
+
+  it('8. a fresh dev database: every declared manager is sys_user.manager_id before the seed runs', async () => {
+    const { answer, rows, userId } = await boot({ staff: MANAGED_STAFF });
+    expect(answer).toMatchObject({ failed: [], managersLinked: 2, managersKept: [] });
+
+    const counsel = await userId('counsel1@legal.example');
+    const lead = await userId('lead@legal.example');
+    expect((await rows('sys_user', { id: counsel }))[0]!.manager_id).toBe(lead);
+    expect((await rows('sys_user', { id: await userId('para1@legal.example') }))[0]!.manager_id).toBe(counsel);
+    expect((await rows('sys_user', { id: lead }))[0]!.manager_id ?? null).toBeNull();
+  }, 30_000);
+
+  it('9. the next boot leaves a manager set by hand as it is, and writes a cleared one again', async () => {
+    const { ql, rows, userId, rerun } = await boot({ staff: MANAGED_STAFF });
+    const admin = await userId(SEED_EMAIL);
+    const counsel = await userId('counsel1@legal.example');
+    const para = await userId('para1@legal.example');
+    // An operator re-points Paralegal 1 to the admin and clears Legal Counsel 1's.
+    await ql.update('sys_user', { id: para, manager_id: admin }, { context: SYS } as never);
+    await ql.update('sys_user', { id: counsel, manager_id: null }, { context: SYS } as never);
+
+    const { answer, logs } = await rerun();
+    expect(answer).toMatchObject({ failed: [], managersLinked: 1, managersKept: ['para1@legal.example'] });
+    expect((await rows('sys_user', { id: para }))[0]!.manager_id).toBe(admin);
+    expect((await rows('sys_user', { id: counsel }))[0]!.manager_id).toBe(await userId('lead@legal.example'));
+    expect(logs.filter((l) => l.level === 'warn')).toEqual([]);
+    expect(logs.map((l) => l.message).join('\n')).toContain('para1@legal.example already had a manager');
+  }, 30_000);
 });
@@ -233,3 +233,180 @@ describe('provisioning — a failure after sign-up says the account exists', ()
     expect(outcome.assignmentsAdded).toBe(0);
   });
 });
+
+/**
+ * A `sys_user` table the manager pass reads and writes, behind the engine
+ * surface both the provisioning and the set-manager write use. Every update is
+ * recorded, so "left as it is" is read as "never written", not as a value that
+ * happens to match. `sys_member` answers no rows: no tenancy fact recorded, so
+ * the cross-organization screen stays out of these cases, as it does for any
+ * identity without one.
+ */
+function managerEngine(users: Array<Record<string, unknown>>) {
+  const updates: Array<Record<string, unknown>> = [];
+  const engine: DemoStaffEngine = {
+    async find(object, query) {
+      const matched = object === 'sys_user' ? selectRows(users, (query.where ?? {}) as Record<string, unknown>) : [];
+      return typeof query.limit === 'number' ? matched.slice(0, query.limit) : matched;
+    },
+    async update(object, data, options) {
+      assertEngineUpdateDispatch(data, options as Parameters<typeof assertEngineUpdateDispatch>[1]);
+      updates.push({ object, ...data });
+      const row = users.find((u) => u.id === data.id);
+      if (object === 'sys_user' && row) Object.assign(row, data);
+      return undefined;
+    },
+    async insert() {
+      throw new Error('these entries carry no position or permission set, so nothing is inserted');
+    },
+  };
+  let next = 0;
+  const signUp = async ({ email, name }: { email: string; name: string }) => {
+    users.push({ id: `u_${++next}`, email, name, manager_id: null });
+  };
+  return { engine, updates, signUp };
+}
+
+const managerLinks = (updates: Array<Record<string, unknown>>) =>
+  updates.filter((u) => 'manager_id' in u).map((u) => [u.id, u.manager_id]);
+
+describe('provisioning — each declared manager is linked once every entry has its account', () => {
+  const STAFF = [
+    // Names a manager declared AFTER it: the link waits for the second pass.
+    { name: 'Legal Counsel 1', email: 'counsel1@legal.example', manager: 'LEAD@legal.example' },
+    { name: 'Legal Lead', email: 'lead@legal.example' },
+  ];
+  const deps = (engine: DemoStaffEngine, signUp: (a: { email: string; name: string }) => Promise<void>) => ({
+    engine,
+    password: 'admin123',
+    signUp,
+    defaultOrganizationId: async () => null,
+  });
+
+  it('a fresh database: the manager declared after the entry is linked, through the set-manager write', async () => {
+    const users: Array<Record<string, unknown>> = [];
+    const { engine, updates, signUp } = managerEngine(users);
+
+    const outcome = await provisionDemoStaff(STAFF, deps(engine, signUp));
+
+    expect(outcome).toMatchObject({
+      created: ['counsel1@legal.example', 'lead@legal.example'],
+      failed: [],
+      managersLinked: 1,
+      managersKept: [],
+    });
+    const byEmail = (email: string) => users.find((u) => u.email === email)!;
+    expect(byEmail('counsel1@legal.example').manager_id).toBe(byEmail('lead@legal.example').id);
+    expect(managerLinks(updates)).toEqual([[byEmail('counsel1@legal.example').id, byEmail('lead@legal.example').id]]);
+  });
+
+  it('a re-run writes nothing: the declared link is in place', async () => {
+    const users: Array<Record<string, unknown>> = [
+      { id: 'u_c1', email: 'counsel1@legal.example', manager_id: 'u_lead' },
+      { id: 'u_lead', email: 'lead@legal.example', manager_id: null },
+    ];
+    const { engine, updates, signUp } = managerEngine(users);
+
+    const outcome = await provisionDemoStaff(STAFF, deps(engine, signUp));
+
+    expect(outcome).toMatchObject({ created: [], failed: [], managersLinked: 0, managersKept: [] });
+    expect(managerLinks(updates)).toEqual([]);
+  });
+
+  it('a re-run leaves a manager set by hand as it is, and says so', async () => {
+    const users: Array<Record<string, unknown>> = [
+      { id: 'u_c1', email: 'counsel1@legal.example', manager_id: 'u_someone_else' },
+      { id: 'u_lead', email: 'lead@legal.example', manager_id: null },
+    ];
+    const { engine, updates, signUp } = managerEngine(users);
+
+    const outcome = await provisionDemoStaff(STAFF, deps(engine, signUp));
+
+    expect(outcome).toMatchObject({ failed: [], managersLinked: 0, managersKept: ['counsel1@legal.example'] });
+    expect(managerLinks(updates)).toEqual([]);
+    expect(users[0]!.manager_id).toBe('u_someone_else');
+  });
+
+  it('a re-run writes the declared manager again on an account whose manager was cleared', async () => {
+    const users: Array<Record<string, unknown>> = [
+      { id: 'u_c1', email: 'counsel1@legal.example', manager_id: null },
+      { id: 'u_lead', email: 'lead@legal.example', manager_id: null },
+    ];
+    const { engine, updates, signUp } = managerEngine(users);
+
+    expect(await provisionDemoStaff(STAFF, deps(engine, signUp))).toMatchObject({ failed: [], managersLinked: 1 });
+    expect(managerLinks(updates)).toEqual([['u_c1', 'u_lead']]);
+  });
+
+  it('a manager whose entry could not be provisioned is reported on the subordinate, never skipped', async () => {
+    const users: Array<Record<string, unknown>> = [];
+    const { engine, updates, signUp } = managerEngine(users);
+
+    const outcome = await provisionDemoStaff(
+      STAFF,
+      deps(engine, async (account) => {
+        if (account.email === 'lead@legal.example') throw new Error('the sign-up door refused the address');
+        await signUp(account);
+      }),
+    );
+
+    expect(outcome.created).toEqual(['counsel1@legal.example']);
+    expect(outcome.managersLinked).toBe(0);
+    expect(outcome.failed).toEqual([
+      { email: 'lead@legal.example', message: 'the sign-up door refused the address' },
+      {
+        email: 'counsel1@legal.example',
+        message:
+          'its manager lead@legal.example has no account, so the manager link was not written: that demo account ' +
+          'was not provisioned on this boot (its own line says why).',
+      },
+    ]);
+    expect(managerLinks(updates)).toEqual([]);
+  });
+
+  it('the set-manager write`s own degradation warning reaches the boot logger', async () => {
+    // The cross-organization screen cannot read `sys_member`: the set-manager
+    // write accepts the link without it and says so once, on the logger the
+    // provisioning was handed.
+    const users: Array<Record<string, unknown>> = [
+      { id: 'u_c1', email: 'counsel1@legal.example', manager_id: null },
+      { id: 'u_lead', email: 'lead@legal.example', manager_id: null },
+    ];
+    const { engine, updates, signUp } = managerEngine(users);
+    const find = engine.find.bind(engine);
+    engine.find = async (object, query, options) => {
+      if (object === 'sys_member') throw new Error('sys_member is unreachable');
+      return find(object, query, options);
+    };
+    const warned: string[] = [];
+
+    const outcome = await provisionDemoStaff(STAFF, {
+      ...deps(engine, signUp),
+      logger: { warn: (msg) => warned.push(msg) },
+    });
+
+    expect(outcome).toMatchObject({ failed: [], managersLinked: 1 });
+    expect(managerLinks(updates)).toEqual([['u_c1', 'u_lead']]);
+    expect(warned).toHaveLength(1);
+    expect(warned[0]).toContain('the cross-organization screen could not read sys_member');
+  });
+
+  it('a link the set-manager write refuses is reported with its code and reason', async () => {
+    // A directory-owned identity: the set-manager write's refusal 5. The
+    // provisioning carries no copy of that rule; this is the shared one.
+    const users: Array<Record<string, unknown>> = [
+      { id: 'u_c1', email: 'counsel1@legal.example', manager_id: null, source: 'idp_provisioned' },
+      { id: 'u_lead', email: 'lead@legal.example', manager_id: null },
+    ];
+    const { engine, updates, signUp } = managerEngine(users);
+
+    const outcome = await provisionDemoStaff(STAFF, deps(engine, signUp));
+
+    expect(outcome.managersLinked).toBe(0);
+    expect(outcome.failed.map((f) => f.email)).toEqual(['counsel1@legal.example']);
+    expect(outcome.failed[0]!.message).toContain(
+      'its manager link to lead@legal.example was refused [PERMISSION_DENIED, idp_provisioned]',
+    );
+    expect(managerLinks(updates)).toEqual([]);
+  });
+});