From 12f802a300f8d85979be1b4beed4ad664a040fe2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 27 Jul 2026 14:16:53 +0000
Subject: [PATCH] =?UTF-8?q?feat(console):=20scoped-invitation=20placement?=
 =?UTF-8?q?=20=E2=80=94=20invite=20straight=20into=20a=20unit=20and=20posi?=
 =?UTF-8?q?tions=20(framework=20ADR-0105=20D8)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An invitation may now carry placement intent (business unit + positions),
applied when it is accepted, so a plant admin's invitee arrives already in
the right unit and role instead of waiting on a platform admin.

- @object-ui/auth: inviteMember accepts optional businessUnitId/positions
  (better-auth invitation additionalFields); new describeDelegableScope()
  reads GET /api/v1/security/my-delegable-scope.
- InviteMemberDialog: optional Placement section listing ONLY the units the
  issuer may place into and the positions they may hand out; positions
  appear once a unit is chosen (an unanchored assignment is refused
  server-side, so offering it first would mislead).

The narrowing is convenience, not the boundary — the server authorizes the
pair against the ISSUER's adminScope at issuance and rejects the whole
invitation when out of scope. So the section is HIDDEN when the caller has
no delegable authority or the deployment exposes no delegated-administration
runtime (501 => null): never a form the server would refuse. An ordinary
invitation is byte-identical to before.

Tests: hidden with no authority, hidden with no surface, options are exactly
the delegable ones, a complete placement reaches inviteMember, a half-chosen
one does not. auth + app-shell 1955/1955; lint clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015FebXPaaGrLhGKw1LHPbpL
---
 .changeset/d8-invitation-placement-ux.md      |  29 +++
 .../InviteMemberDialog.placement.test.tsx     | 165 ++++++++++++++++++
 .../manage/InviteMemberDialog.tsx             | 121 ++++++++++++-
 packages/auth/src/AuthContext.ts              |  22 ++-
 packages/auth/src/AuthProvider.tsx            |  22 ++-
 packages/auth/src/createAuthClient.ts         |  44 ++++-
 packages/auth/src/index.ts                    |   1 +
 packages/auth/src/types.ts                    |  51 +++++-
 packages/auth/src/useAuth.ts                  |   1 +
 9 files changed, 445 insertions(+), 11 deletions(-)
 create mode 100644 .changeset/d8-invitation-placement-ux.md
 create mode 100644 packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.placement.test.tsx

diff --git a/.changeset/d8-invitation-placement-ux.md b/.changeset/d8-invitation-placement-ux.md
new file mode 100644
index 000000000..68a5d9e07
--- /dev/null
+++ b/.changeset/d8-invitation-placement-ux.md
@@ -0,0 +1,29 @@
+---
+"@object-ui/auth": minor
+"@object-ui/app-shell": minor
+---
+
+feat(console): scoped-invitation placement — invite someone straight into a
+business unit and positions (framework ADR-0105 D8)
+
+An invitation may now carry PLACEMENT INTENT: the business unit the invitee
+lands in and the positions they are assigned when they accept. A plant admin's
+invitee arrives already in the right unit and role instead of waiting on a
+platform admin to finish the job by hand.
+
+- `@object-ui/auth`: `inviteMember` accepts optional `businessUnitId` /
+  `positions` (passed through better-auth's invitation `additionalFields`), and
+  a new `describeDelegableScope()` reads
+  `GET /api/v1/security/my-delegable-scope`.
+- `InviteMemberDialog`: an optional "Placement" section listing **only** the
+  units the issuer may place into and the positions they may hand out.
+  Positions appear once a unit is chosen — an unanchored assignment is refused
+  by the server, so offering it first would mislead.
+
+The narrowing is convenience, not the boundary: the server authorizes the pair
+against the ISSUER's `adminScope` (ADR-0090 D12) at issuance and rejects the
+whole invitation when it is out of scope. Accordingly the section is **hidden**
+whenever the caller has no delegable authority, or the deployment exposes no
+delegated-administration runtime at all (the endpoint answers 501 ⇒ `null`) —
+never a form the server would refuse. An ordinary invitation is unchanged: with
+no placement chosen, the request body is byte-identical to before.
diff --git a/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.placement.test.tsx b/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.placement.test.tsx
new file mode 100644
index 000000000..5080d3083
--- /dev/null
+++ b/packages/app-shell/src/console/organizations/__tests__/InviteMemberDialog.placement.test.tsx
@@ -0,0 +1,165 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * InviteMemberDialog — scoped-invitation placement (framework ADR-0105 D8).
+ *
+ * The placement section NARROWS to what the issuer may actually delegate
+ * (`security/my-delegable-scope`); the server still authorizes the pair
+ * against the issuer's `adminScope`. So the behaviours worth pinning are the
+ * ones a user would notice going wrong:
+ *
+ *   1. no delegated authority (or no runtime exposing it) ⇒ no placement UI at
+ *      all — never a form the server would refuse;
+ *   2. the options offered are exactly the delegable ones;
+ *   3. a chosen placement reaches `inviteMember`, and a HALF-chosen one does
+ *      not (a unit with no positions is not a placement).
+ */
+
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { render, screen, fireEvent, waitFor, within } from '@testing-library/react';
+
+vi.mock('@object-ui/i18n', () => ({
+  useObjectTranslation: () => ({
+    t: (key: string, options?: Record<string, unknown>) => String(options?.defaultValue ?? key),
+  }),
+}));
+
+const inviteMember = vi.fn();
+const describeDelegableScope = vi.fn();
+vi.mock('@object-ui/auth', () => ({
+  useAuth: () => ({ inviteMember, describeDelegableScope }),
+}));
+
+// Passthrough primitives — the Select is rendered as a native <select> so the
+// test can drive it without Radix portal machinery.
+vi.mock('@object-ui/components', () => ({
+  Dialog: ({ open, children }: any) => (open ? <div>{children}</div> : null),
+  DialogContent: (p: any) => <div {...p} />,
+  DialogDescription: (p: any) => <p {...p} />,
+  DialogFooter: (p: any) => <div {...p} />,
+  DialogHeader: (p: any) => <div {...p} />,
+  DialogTitle: (p: any) => <h2 {...p} />,
+  Button: ({ children, ...rest }: any) => <button {...rest}>{children}</button>,
+  Input: (p: any) => <input {...p} />,
+  Label: (p: any) => <label {...p} />,
+  Select: ({ value, onValueChange, children }: any) => (
+    <select data-testid="select" value={value} onChange={(e) => onValueChange(e.target.value)}>
+      <option value="" />
+      {children}
+    </select>
+  ),
+  SelectContent: (p: any) => <>{p.children}</>,
+  SelectItem: ({ value, children }: any) => <option value={value}>{children}</option>,
+  SelectTrigger: (p: any) => <>{p.children}</>,
+  SelectValue: () => null,
+}));
+vi.mock('lucide-react', () => ({
+  Loader2: () => <span />,
+  Copy: () => <span />,
+  Check: () => <span />,
+}));
+vi.mock('sonner', () => ({ toast: { success: vi.fn(), error: vi.fn() } }));
+
+import { InviteMemberDialog } from '../manage/InviteMemberDialog';
+
+const DELEGABLE = {
+  isTenantAdmin: false,
+  placeableBusinessUnitIds: ['bu_plant_a', 'bu_plant_a_qc'],
+  assignablePositions: ['qc_inspector'],
+  scopes: [],
+};
+
+const renderDialog = () =>
+  render(
+    <InviteMemberDialog organizationId="org-42" open onOpenChange={() => {}} />,
+  );
+
+const fillEmail = () =>
+  fireEvent.change(screen.getByTestId('invite-email-input'), {
+    target: { value: 'p@x.test' },
+  });
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  inviteMember.mockResolvedValue({ id: 'inv-1', email: 'p@x.test', role: 'member' });
+});
+
+describe('InviteMemberDialog — placement (ADR-0105 D8)', () => {
+  it('hides placement entirely when the caller may delegate nothing', async () => {
+    describeDelegableScope.mockResolvedValue({
+      isTenantAdmin: false,
+      placeableBusinessUnitIds: [],
+      assignablePositions: [],
+      scopes: [],
+    });
+    renderDialog();
+    await waitFor(() => expect(describeDelegableScope).toHaveBeenCalled());
+    expect(screen.queryByTestId('invite-placement-section')).not.toBeInTheDocument();
+  });
+
+  it('hides placement when the deployment does not expose the surface at all', async () => {
+    describeDelegableScope.mockResolvedValue(null);
+    renderDialog();
+    await waitFor(() => expect(describeDelegableScope).toHaveBeenCalled());
+    expect(screen.queryByTestId('invite-placement-section')).not.toBeInTheDocument();
+  });
+
+  it('offers exactly the delegable units, and positions only once a unit is chosen', async () => {
+    describeDelegableScope.mockResolvedValue(DELEGABLE);
+    renderDialog();
+    await screen.findByTestId('invite-placement-section');
+
+    const unitSelect = within(screen.getByTestId('invite-placement-section')).getByTestId('select');
+    expect(unitSelect).toHaveTextContent('bu_plant_a');
+    expect(unitSelect).toHaveTextContent('bu_plant_a_qc');
+    // Positions appear only after a unit is picked — an unanchored assignment
+    // is refused by the gate, so offering it first would be misleading.
+    expect(screen.queryByTestId('invite-positions')).not.toBeInTheDocument();
+
+    fireEvent.change(unitSelect, { target: { value: 'bu_plant_a' } });
+    await screen.findByTestId('invite-positions');
+    expect(screen.getByTestId('invite-position-qc_inspector')).toBeInTheDocument();
+  });
+
+  it('sends a complete placement with the invitation', async () => {
+    describeDelegableScope.mockResolvedValue(DELEGABLE);
+    const { container } = renderDialog();
+    await screen.findByTestId('invite-placement-section');
+
+    fillEmail();
+    fireEvent.change(within(screen.getByTestId('invite-placement-section')).getByTestId('select'), {
+      target: { value: 'bu_plant_a' },
+    });
+    fireEvent.click(await screen.findByTestId('invite-position-qc_inspector'));
+    fireEvent.submit(container.querySelector('form')!);
+
+    await waitFor(() => expect(inviteMember).toHaveBeenCalledTimes(1));
+    expect(inviteMember).toHaveBeenCalledWith({
+      organizationId: 'org-42',
+      email: 'p@x.test',
+      role: 'member',
+      businessUnitId: 'bu_plant_a',
+      positions: ['qc_inspector'],
+    });
+  });
+
+  it('a unit with no positions is NOT a placement — the invite goes out plain', async () => {
+    describeDelegableScope.mockResolvedValue(DELEGABLE);
+    const { container } = renderDialog();
+    await screen.findByTestId('invite-placement-section');
+
+    fillEmail();
+    fireEvent.change(within(screen.getByTestId('invite-placement-section')).getByTestId('select'), {
+      target: { value: 'bu_plant_a' },
+    });
+    fireEvent.submit(container.querySelector('form')!);
+
+    await waitFor(() => expect(inviteMember).toHaveBeenCalledTimes(1));
+    expect(inviteMember).toHaveBeenCalledWith({
+      organizationId: 'org-42',
+      email: 'p@x.test',
+      role: 'member',
+    });
+  });
+});
diff --git a/packages/app-shell/src/console/organizations/manage/InviteMemberDialog.tsx b/packages/app-shell/src/console/organizations/manage/InviteMemberDialog.tsx
index 1ea68b4da..f993220a8 100644
--- a/packages/app-shell/src/console/organizations/manage/InviteMemberDialog.tsx
+++ b/packages/app-shell/src/console/organizations/manage/InviteMemberDialog.tsx
@@ -24,7 +24,7 @@ import {
   SelectValue,
 } from '@object-ui/components';
 import { useAuth } from '@object-ui/auth';
-import type { AuthInvitation } from '@object-ui/auth';
+import type { AuthInvitation, DelegableScope } from '@object-ui/auth';
 import { useObjectTranslation } from '@object-ui/i18n';
 import { Loader2, Copy, Check } from 'lucide-react';
 import { toast } from 'sonner';
@@ -51,7 +51,7 @@ export function InviteMemberDialog({
   onInvited,
 }: InviteMemberDialogProps) {
   const { t } = useObjectTranslation();
-  const { inviteMember } = useAuth();
+  const { inviteMember, describeDelegableScope } = useAuth();
 
   const [email, setEmail] = useState('');
   const [role, setRole] = useState<Role>('member');
@@ -60,6 +60,17 @@ export function InviteMemberDialog({
   const [createdInvitation, setCreatedInvitation] = useState<AuthInvitation | null>(null);
   const [copied, setCopied] = useState(false);
 
+  // ── [framework ADR-0105 D8] Placement intent ────────────────────────────
+  // The invitation may carry the unit the invitee lands in and the positions
+  // they get on acceptance. The options are NARROWED to what this issuer may
+  // actually delegate (`my-delegable-scope`); the server still authorizes the
+  // pair against their adminScope, so this is convenience, not the boundary.
+  // No delegable authority (or no runtime exposing it) ⇒ the whole section is
+  // hidden rather than offering a form the server would refuse.
+  const [delegable, setDelegable] = useState<DelegableScope | null>(null);
+  const [businessUnitId, setBusinessUnitId] = useState<string>('');
+  const [positions, setPositions] = useState<string[]>([]);
+
   useEffect(() => {
     if (open) {
       setEmail('');
@@ -67,9 +78,31 @@ export function InviteMemberDialog({
       setError(null);
       setCreatedInvitation(null);
       setCopied(false);
+      setBusinessUnitId('');
+      setPositions([]);
     }
   }, [open]);
 
+  useEffect(() => {
+    if (!open) return;
+    let cancelled = false;
+    describeDelegableScope?.()
+      .then((scope) => {
+        if (!cancelled) setDelegable(scope);
+      })
+      .catch(() => {
+        /* absent surface — placement stays hidden */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [open, describeDelegableScope]);
+
+  const canPlace =
+    !!delegable &&
+    delegable.placeableBusinessUnitIds.length > 0 &&
+    delegable.assignablePositions.length > 0;
+
   const handleSubmit = useCallback(
     async (e: React.FormEvent) => {
       e.preventDefault();
@@ -81,6 +114,12 @@ export function InviteMemberDialog({
           organizationId,
           email: email.trim(),
           role,
+          // Placement travels only when BOTH halves are chosen — a unit with
+          // no positions (or the reverse) is not a placement, and sending a
+          // half-intent would have the server reject an otherwise fine invite.
+          ...(canPlace && businessUnitId && positions.length > 0
+            ? { businessUnitId, positions }
+            : {}),
         });
         setCreatedInvitation(inv);
         onInvited?.(inv);
@@ -90,7 +129,7 @@ export function InviteMemberDialog({
         setIsSubmitting(false);
       }
     },
-    [email, role, organizationId, inviteMember, onInvited],
+    [email, role, organizationId, inviteMember, onInvited, canPlace, businessUnitId, positions],
   );
 
   const handleCopy = useCallback(async () => {
@@ -197,6 +236,82 @@ export function InviteMemberDialog({
                   </SelectContent>
                 </Select>
               </div>
+              {/* [framework ADR-0105 D8] Placement — only for issuers who
+                  actually hold delegated authority. Options come from
+                  `my-delegable-scope`, so a delegate sees their own subtree and
+                  the positions they may hand out; the server re-checks. */}
+              {canPlace && (
+                <div
+                  className="grid gap-3 rounded-md border border-dashed p-3"
+                  data-testid="invite-placement-section"
+                >
+                  <div className="grid gap-1">
+                    <Label className="text-sm">
+                      {t('organization.invitations.placementLabel', {
+                        defaultValue: 'Placement (optional)',
+                      })}
+                    </Label>
+                    <p className="text-xs text-muted-foreground">
+                      {t('organization.invitations.placementDescription', {
+                        defaultValue:
+                          'Applied when the invitation is accepted. Only units and positions you may delegate are listed.',
+                      })}
+                    </p>
+                  </div>
+
+                  <div className="grid gap-2">
+                    <Label htmlFor="invite-business-unit" className="text-xs">
+                      {t('organization.invitations.businessUnitLabel', { defaultValue: 'Business unit' })}
+                    </Label>
+                    <Select value={businessUnitId} onValueChange={setBusinessUnitId}>
+                      <SelectTrigger id="invite-business-unit" data-testid="invite-business-unit-select">
+                        <SelectValue
+                          placeholder={t('organization.invitations.businessUnitPlaceholder', {
+                            defaultValue: 'No placement',
+                          })}
+                        />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {delegable!.placeableBusinessUnitIds.map((id) => (
+                          <SelectItem key={id} value={id}>
+                            {id}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  </div>
+
+                  {businessUnitId && (
+                    <div className="grid gap-2" data-testid="invite-positions">
+                      <Label className="text-xs">
+                        {t('organization.invitations.positionsLabel', { defaultValue: 'Positions' })}
+                      </Label>
+                      <div className="flex flex-wrap gap-2">
+                        {delegable!.assignablePositions.map((name) => {
+                          const selected = positions.includes(name);
+                          return (
+                            <Button
+                              key={name}
+                              type="button"
+                              size="sm"
+                              variant={selected ? 'default' : 'outline'}
+                              data-testid={`invite-position-${name}`}
+                              aria-pressed={selected}
+                              onClick={() =>
+                                setPositions((prev) =>
+                                  prev.includes(name) ? prev.filter((p) => p !== name) : [...prev, name],
+                                )
+                              }
+                            >
+                              {name}
+                            </Button>
+                          );
+                        })}
+                      </div>
+                    </div>
+                  )}
+                </div>
+              )}
               {error && (
                 <p className="text-sm text-destructive" data-testid="invite-error">{error}</p>
               )}
diff --git a/packages/auth/src/AuthContext.ts b/packages/auth/src/AuthContext.ts
index aff25cabb..cd958f571 100644
--- a/packages/auth/src/AuthContext.ts
+++ b/packages/auth/src/AuthContext.ts
@@ -7,7 +7,7 @@
  */
 
 import { createContext } from 'react';
-import type { AuthUser, AuthSession, PreviewModeOptions, AuthOrganization, AuthOrganizationMember, AuthInvitation, AuthPublicConfig, SignInWithProviderOptions } from './types';
+import type { AuthUser, AuthSession, PreviewModeOptions, AuthOrganization, AuthOrganizationMember, AuthInvitation, AuthPublicConfig, SignInWithProviderOptions, DelegableScope } from './types';
 
 export interface AuthContextValue {
   /** Current authenticated user */
@@ -120,8 +120,24 @@ export interface AuthContextValue {
 
   /** List members of an organization */
   getMembers: (orgId: string) => Promise<AuthOrganizationMember[]>;
-  /** Invite a user by email */
-  inviteMember: (data: { organizationId: string; email: string; role: string }) => Promise<AuthInvitation>;
+  /**
+   * Invite a user by email. `businessUnitId` / `positions` carry [framework
+   * ADR-0105 D8] placement intent, authorized server-side against the ISSUER's
+   * adminScope — an out-of-scope pair rejects the whole invitation.
+   */
+  inviteMember: (data: {
+    organizationId: string;
+    email: string;
+    role: string;
+    businessUnitId?: string;
+    positions?: string[];
+  }) => Promise<AuthInvitation>;
+  /**
+   * [framework ADR-0090 D12 / ADR-0105 D8] What the caller may delegate:
+   * business units they may place into and positions they may assign. `null`
+   * when the deployment has no delegated-administration runtime.
+   */
+  describeDelegableScope: () => Promise<DelegableScope | null>;
   /** Remove a member by id */
   removeMember: (data: { organizationId: string; memberIdOrUserId: string }) => Promise<void>;
   /** Update a member's role */
diff --git a/packages/auth/src/AuthProvider.tsx b/packages/auth/src/AuthProvider.tsx
index b4bc4295e..6e8f83bc7 100644
--- a/packages/auth/src/AuthProvider.tsx
+++ b/packages/auth/src/AuthProvider.tsx
@@ -596,8 +596,23 @@ export function AuthProvider({
   );
 
   const inviteMember = useCallback(
-    (data: { organizationId: string; email: string; role: string }): Promise<AuthInvitation> =>
-      client.inviteMember(data),
+    (data: {
+      organizationId: string;
+      email: string;
+      role: string;
+      businessUnitId?: string;
+      positions?: string[];
+    }): Promise<AuthInvitation> => client.inviteMember(data),
+    [client],
+  );
+
+  /**
+   * [framework ADR-0090 D12 / ADR-0105 D8] What the caller may delegate — the
+   * narrowing input for the scoped-invitation placement pickers. `null` when
+   * the deployment doesn't expose it, so consumers hide placement entirely.
+   */
+  const describeDelegableScope = useCallback(
+    () => client.describeDelegableScope(),
     [client],
   );
 
@@ -694,6 +709,7 @@ export function AuthProvider({
       leaveOrganization,
       getMembers,
       inviteMember,
+      describeDelegableScope,
       removeMember,
       updateMemberRole,
       listInvitations,
@@ -710,7 +726,7 @@ export function AuthProvider({
       remediationRequired, enrollTotp, verifyTotp,
       organizations, activeOrganization, activeMember, isOrganizationsLoading, switchOrganization, createOrganization, refreshOrganizations,
       updateOrganization, deleteOrganization, leaveOrganization,
-      getMembers, inviteMember, removeMember, updateMemberRole,
+      getMembers, inviteMember, describeDelegableScope, removeMember, updateMemberRole,
       listInvitations, cancelInvitation, getInvitation, acceptInvitation, rejectInvitation, listUserInvitations,
     ],
   );
diff --git a/packages/auth/src/createAuthClient.ts b/packages/auth/src/createAuthClient.ts
index 63185166f..dc7d744db 100644
--- a/packages/auth/src/createAuthClient.ts
+++ b/packages/auth/src/createAuthClient.ts
@@ -606,6 +606,35 @@ export function createAuthClient(config: AuthClientConfig): AuthClient {
       return (raw && typeof raw === 'object' && 'user' in raw ? raw.user : raw) as AuthUser;
     },
 
+    /**
+     * [framework ADR-0090 D12 / ADR-0105 D8] What the caller may delegate.
+     *
+     * Sits next to the auth base path (`…/auth` → `…/security/…`) rather than
+     * taking a second base URL, so a deployment that relocates its API prefix
+     * moves both together. Never throws: a deployment without the
+     * delegated-administration runtime answers 501, and any failure yields
+     * `null` so the caller HIDES placement instead of offering a form the
+     * server would refuse.
+     */
+    async describeDelegableScope(): Promise<import('./types').DelegableScope | null> {
+      try {
+        const securityBase = basePath.replace(/\/auth$/, '/security');
+        const response = await bearerFetch(`${origin}${securityBase}/my-delegable-scope`, {
+          method: 'GET',
+          headers: { 'Content-Type': 'application/json' },
+        });
+        if (!response.ok) return null;
+        const body = (await response.json()) as any;
+        // The server wraps some payloads as `{ success, data }`; tolerate both.
+        const scope = body && typeof body === 'object' && 'data' in body ? body.data : body;
+        return scope && typeof scope === 'object' && Array.isArray(scope.placeableBusinessUnitIds)
+          ? (scope as import('./types').DelegableScope)
+          : null;
+      } catch {
+        return null;
+      }
+    },
+
     async getConfig(): Promise<AuthPublicConfig> {
       if (!configPromise) {
         configPromise = loadConfigWithRetry().catch((err) => {
@@ -741,11 +770,24 @@ export function createAuthClient(config: AuthClientConfig): AuthClient {
       return (result?.members ?? []) as AuthOrganizationMember[];
     },
 
-    async inviteMember(inviteData: { organizationId: string; email: string; role: string }): Promise<AuthInvitation> {
+    async inviteMember(inviteData: {
+      organizationId: string;
+      email: string;
+      role: string;
+      businessUnitId?: string;
+      positions?: string[];
+    }): Promise<AuthInvitation> {
       const { data, error } = await (betterAuth as any).organization.inviteMember({
         organizationId: inviteData.organizationId,
         email: inviteData.email,
         role: inviteData.role,
+        // [framework ADR-0105 D8] Placement intent rides better-auth's own
+        // `additionalFields` on the invitation. Omitted entirely when absent so
+        // an ordinary invite is byte-identical to before; when present, the
+        // server authorizes it against the ISSUER's adminScope and rejects the
+        // whole invitation if it is out of scope.
+        ...(inviteData.businessUnitId ? { businessUnitId: inviteData.businessUnitId } : {}),
+        ...(inviteData.positions?.length ? { positions: inviteData.positions } : {}),
       });
       if (error) throw new Error(error.message ?? 'Failed to invite member');
       return data as unknown as AuthInvitation;
diff --git a/packages/auth/src/index.ts b/packages/auth/src/index.ts
index 893ed2c6e..7c9b53585 100644
--- a/packages/auth/src/index.ts
+++ b/packages/auth/src/index.ts
@@ -72,6 +72,7 @@ export type {
   AuthPublicConfig,
   SignInWithProviderOptions,
   TenancyPosture,
+  DelegableScope,
 } from './types';
 
 export type { AuthContextValue } from './AuthContext';
diff --git a/packages/auth/src/types.ts b/packages/auth/src/types.ts
index 397535ad5..1d51cf131 100644
--- a/packages/auth/src/types.ts
+++ b/packages/auth/src/types.ts
@@ -117,6 +117,34 @@ export interface AuthSocialProvider {
  */
 export type TenancyPosture = 'single' | 'group' | 'isolated';
 
+/**
+ * [framework ADR-0090 D12 / ADR-0105 D8] What the caller may delegate, as
+ * returned by `GET /api/v1/security/my-delegable-scope`.
+ *
+ * A picker NARROWS with this; the server-side gate still decides. Empty lists
+ * mean "no delegated authority" — render no placement rather than a permissive
+ * form the server would refuse.
+ */
+export interface DelegableScope {
+  /** Unconstrained caller (tenant-level admin); the lists then enumerate everything. */
+  isTenantAdmin: boolean;
+  /** Business units the caller may place people into. */
+  placeableBusinessUnitIds: string[];
+  /** Positions the caller may assign — every set they distribute is allowlisted. */
+  assignablePositions: string[];
+  /** The `adminScope`s those derive from, for attribution. */
+  scopes: Array<{
+    setName: string;
+    businessUnit: string;
+    includeSubtree: boolean;
+    manageAssignments: boolean;
+    manageBindings: boolean;
+    authorEnvironmentSets: boolean;
+    assignablePermissionSets: string[];
+    businessUnitIds: string[];
+  }>;
+}
+
 /** Public auth configuration returned by the server */
 export interface AuthPublicConfig {
   emailPassword?: {
@@ -248,6 +276,15 @@ export interface AuthClient {
 
   /** Fetch the public auth configuration from the server (providers, features) */
   getConfig: () => Promise<AuthPublicConfig>;
+  /**
+   * [framework ADR-0090 D12 / ADR-0105 D8] What the CALLER may delegate —
+   * `GET /api/v1/security/my-delegable-scope`. Used to narrow the
+   * scoped-invitation placement pickers to the units and positions the issuer
+   * can actually hand out. `null` when the deployment doesn't expose it (no
+   * delegated-administration runtime ⇒ 501, or the request failed) — consumers
+   * then hide placement rather than offering something that would be refused.
+   */
+  describeDelegableScope: () => Promise<DelegableScope | null>;
   /** Initiate sign-in with a third-party provider (Google, GitHub, OIDC, etc.) */
   signInWithProvider: (providerId: string, options?: SignInWithProviderOptions) => Promise<void>;
 
@@ -266,7 +303,19 @@ export interface AuthClient {
   /** Get members of an organization */
   getMembers: (orgId: string) => Promise<AuthOrganizationMember[]>;
   /** Invite a member to an organization */
-  inviteMember: (data: { organizationId: string; email: string; role: string }) => Promise<AuthInvitation>;
+  inviteMember: (data: {
+    organizationId: string;
+    email: string;
+    role: string;
+    /**
+     * [framework ADR-0105 D8] Placement intent — the business unit the invitee
+     * lands in and the positions they are assigned on acceptance. Authorized
+     * SERVER-side against the ISSUER's `adminScope`: an out-of-scope pair
+     * rejects the whole invitation, so this is a request, never an authority.
+     */
+    businessUnitId?: string;
+    positions?: string[];
+  }) => Promise<AuthInvitation>;
   /** Remove a member from an organization */
   removeMember: (data: { organizationId: string; memberIdOrUserId: string }) => Promise<void>;
   /** Update a member's role */
diff --git a/packages/auth/src/useAuth.ts b/packages/auth/src/useAuth.ts
index e57642e76..150e4876c 100644
--- a/packages/auth/src/useAuth.ts
+++ b/packages/auth/src/useAuth.ts
@@ -56,6 +56,7 @@ export function useAuth(): AuthContextValue {
       setInitialPassword: async () => { throw new Error('useAuth must be used within an AuthProvider'); },
       hasLocalPassword: async () => false,
       getAuthConfig: async () => ({}),
+      describeDelegableScope: async () => null,
       signInWithProvider: async () => { throw new Error('useAuth must be used within an AuthProvider'); },
       organizations: [],
       activeOrganization: null,