Feature: Organization management — invite members and rename

[heiwen]

Overview

Users need the ability to manage their organization directly, independent of agent membership:

1. Invite members to the organization
2. Remove members from the organization
3. Rename the organization

Use cases

• An org admin wants to add a new user to the organization before assigning them to any agent
• An org admin wants to remove a user from the organization
• An org admin wants to update the organization name after initial setup

Proposed changes

Invite member to organization

• Add an organization settings page (or section) with a member invite form
• Calls organization.inviteMember with the target email and role
• Distinct from agent-level member management

Remove member from organization

• Show a list of current org members with a remove action
• Calls organization.removeMember with the member ID or email
• Should not be available for the last owner

Rename organization

• Add an editable organization name field in organization settings
• Calls organization.update (or equivalent) with the new name

Out of scope

• Per-agent member management (tracked separately)

[heiwen]

@claude how would you implement this?

[hebo-agent]

Claude finished @heiwen's task in 2m 10s —— View job

---

Implementation plan for organization management

• Explore codebase architecture and existing patterns
• Analyze existing organization-related code
• Provide implementation plan

---

Here's how I'd implement this, building on the existing patterns in the codebase:

Architecture overview

The codebase already has all the backend plumbing for org member management — authClient.organization.inviteMember(), removeMember(), cancelInvitation(), and getFullOrganization() are all wired up in apps/console/app/lib/auth/better-auth.ts. The agent settings page (_shell.agent.$agentSlug.settings) currently reuses these methods, but they're scoped to agent-level UI. The main work is creating a dedicated org settings page and adding an updateOrganization method for renaming.

1. Add updateOrganization to the auth service

apps/console/app/lib/auth/types.ts — extend AuthService:

updateOrganization(data: { name?: string }): Promise<void>;

apps/console/app/lib/auth/better-auth.ts — implement via Better Auth client:

async updateOrganization(data: { name?: string }) {
  const { error } = await authClient.organization.update({ data });
  if (error) throw error;
}

Better Auth's organization plugin already exposes an organization.update endpoint — no backend changes needed. The auth service hook in apps/auth/src/better-auth.ts:44 already has an update hook registered (syncActiveOrganizationHook), so session state stays in sync.

apps/console/app/lib/auth/dummy-auth.ts — add a mock implementation that updates the in-memory collection.

2. Create the org settings route structure

Following the resource routes pattern already used in agent settings:

routes/
  _shell.org.settings/route.tsx            ← clientLoader + page layout
  _shell.org.settings.members/route.tsx    ← clientAction only (invite/remove/revoke)
  _shell.org.settings.general/route.tsx    ← clientAction only (rename)

Why this structure? It mirrors the existing _shell.agent.$agentSlug.settings pattern exactly — a parent route with a loader and multiple resource-route children for actions. Each section uses useFetcher so submissions don't cause full page navigations.

3. Org settings loader (_shell.org.settings/route.tsx)

export async function clientLoader() {
  const { members, invitations } = await authService.getOrganization();
  const user = shellStore.user!;
  const currentMember = members.find((m) => m.userId === user.userId);
  const isOwner = currentMember?.role === "owner";
  const canManage = isOwner || currentMember?.role === "admin";
  const org = shellStore.organizations.find((o) => o.id === user.organizationId);
  return { org, members, invitations, isOwner, canManage };
}

4. Org settings page component

Three sections, each in its own file:

a) General section (general.tsx) — Rename org

• Editable org name field using Conform + Zod (z.object({ name: z.string().min(1).max(100) }))
• useFetcher posting to the general resource route with intent: "rename"
• Only enabled for owners/admins (canManage)

b) Members section (members.tsx) — Invite & remove

• Reuse the existing MembersSettings component from _shell.agent.$agentSlug.settings/members.tsx (or extract it to a shared component). The UI is identical: members table, pending invitations, invite form
• useFetcher posting to the members resource route
• Same three intents: invite, remove, revoke

c) Danger zone (danger-zone.tsx) — optional

• Could include "Delete organization" or "Leave organization" in a future iteration

5. Resource route actions

_shell.org.settings.members/route.tsx — nearly identical to the existing agent members action:

export async function clientAction({ request }: ClientActionFunctionArgs) {
  const formData = await request.formData();
  const intent = formData.get("intent") as string;

  if (intent === "invite") {
    const submission = parseWithZod(formData, { schema: inviteSchema });
    if (submission.status !== "success") return { intent, submission: submission.reply() };
    await authService.inviteMember(submission.value.email, submission.value.role);
    return { intent, submission: submission.reply({ resetForm: true }) };
  }
  if (intent === "remove") {
    await authService.removeMember(formData.get("email") as string);
    return null;
  }
  if (intent === "revoke") {
    await authService.cancelInvitation(formData.get("invitationId") as string);
    return null;
  }
}

_shell.org.settings.general/route.tsx:

export async function clientAction({ request }: ClientActionFunctionArgs) {
  const formData = await request.formData();
  const submission = parseWithZod(formData, { schema: renameSchema });
  if (submission.status !== "success") return { intent: "rename", submission: submission.reply() };
  await authService.updateOrganization({ name: submission.value.name });
  return { intent: "rename", submission: submission.reply({ resetForm: true }) };
}

6. Navigation

Add a link to org settings from the sidebar user menu (apps/console/app/routes/_shell/sidebar-user.tsx). This is where the org switcher already lives — adding a "Settings" item in the dropdown for the active org is the natural place:

<DropdownMenuItem asChild>
  <Link to="/org/settings">Organization Settings</Link>
</DropdownMenuItem>

7. Guard: prevent removing the last owner

The removeMember action should check that at least one owner remains. This can be done client-side before calling authService.removeMember():

const owners = members.filter((m) => m.role === "owner");
if (owners.length <= 1 && owners[0]?.userId === targetUserId) {
  return { intent, submission: submission.reply({ formErrors: ["Cannot remove the last owner"] }) };
}

Better Auth likely enforces this server-side too, but a client-side check gives better UX.

8. Update shell store after rename

After a successful rename, update shellStore.organizations so the sidebar reflects the new name without a full reload. The fetcher's onSuccess or a revalidation of the parent loader handles this.

Summary of changes

File	Change
apps/console/app/lib/auth/types.ts	Add updateOrganization method
apps/console/app/lib/auth/better-auth.ts	Implement updateOrganization
apps/console/app/lib/auth/dummy-auth.ts	Mock updateOrganization
apps/console/app/routes/_shell.org.settings/route.tsx	New — loader + page
apps/console/app/routes/_shell.org.settings/general.tsx	New — rename form
apps/console/app/routes/_shell.org.settings/members.tsx	New — members UI (reuse pattern)
apps/console/app/routes/_shell.org.settings.general/route.tsx	New — rename action
apps/console/app/routes/_shell.org.settings.members/route.tsx	New — invite/remove/revoke actions
apps/console/app/routes/_shell/sidebar-user.tsx	Add org settings link
apps/console/app/mocks/	Update MSW handlers if needed

The key insight is that ~80% of the implementation already exists in the agent settings members flow — the main work is lifting it to the org level and adding the rename capability.

Want me to go ahead and implement this?