Lg org setup team mig

[lavanya-gunreddi]

Draft for organization setup and team migration

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
runpod-docs	🟢 Ready	View Preview	Sep 18, 2026, 12:20 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[rambo-runpod]

COMMENT: 15 high, 8 medium, 12 low

SEVERITY - medium
IMPACT - Migration page omits gates the merge enforces before any write: participants with an active savings plan block the merge, paying accounts need a billing cutover acknowledgement, and secret-name or derived group-name collisions hard-fail (mergeTeamsIntoOrganization.ts:228-326).
SOLUTION - Add these to What to do before migration so owners can clear them ahead of the staff run.

SEVERITY - medium
IMPACT - Migration step 5 promises a completion email, but the only signal in code is an organization.converted outbox event with no mail consumer or template in the repo (model/src/org/organization/outboxEventHelper.ts:64).
SOLUTION - Confirm with the orgs team that an email is sent; otherwise drop step 5.

SEVERITY - medium
IMPACT - The quoted acceptance warning (migrate-from-teams.mdx lines 57-63) cannot be found in the backend or the invite payload (sendOrgInviteNotification.ts:30-34); the invite email body lives in Courier and the console is not in the monorepo, so the exact wording is unverified.
SOLUTION - Verify the text against the console invite page before publishing, or paraphrase instead of quoting.

SEVERITY - medium
IMPACT - Resource tagging says basic members can only view tags, but basic holds TAG:USE and can attach or detach existing tags on resources; billing is the view-only role (roleGrid.ts:284, 306-308).
SOLUTION - Change the roles bullet to: admin and dev create, edit and delete tags; basic can apply existing tags; billing can only view.

SEVERITY - medium
IMPACT - Overview calls Organizations an internal alpha via sales; per the loop brief the beta launched mid-August, and code shows orgs are staff-provisioned (organizationCreate.ts:15-17) and gated per user by the orgs feature flag, with tagging behind its own rollout flag (assertGeneralTaggingEnabled.ts).
SOLUTION - Update the status note to beta, say Runpod provisions the org and enables it for your account, and mark tagging as rolling out.

SEVERITY - medium
IMPACT - Console UI paths across all pages (Settings → Access, Groups, Members, Tags buttons, and the claim that console.runpod.io/team disappears) cannot be verified: the console is not in the monorepo and the team GraphQL surface is still live (model/src/team/createTeam.ts).
SOLUTION - Verify each path against the current console, and soften the team-page claim to what is confirmed.

SEVERITY - medium
IMPACT - Features that exist today are undocumented: custom roles, open vs closed sharing modes, invite expiry and pending cap, verified-email requirement, at most one admin-protected removal, and SharedApiKey revocation on removal only appears in the migration page.
SOLUTION - Add a sharing-modes section to overview or roles, a custom-roles section to roles, and invite limits to access.

SEVERITY - medium
IMPACT - Placement conflicts with sibling PR #748, which puts an Organizations group under accounts-billing/organizations/ with different filenames (roles-and-permissions, SSH-key-management) and a different tag model; neither exists on origin/main, so whichever merges second creates duplicate pages or a nav conflict.
SOLUTION - Consolidate into one PR under accounts-billing/organizations/ and close the other. Recommendation and reasoning: every account topic on main lives under accounts-billing/ and this PR already links into that directory for cost centers, so nesting keeps the URL space consistent; keep this PR's page set as the skeleton, pull #748's SSH page in after fixing its capitalized filename, and reconcile the tag and roles content against the code findings above rather than against either draft.

Unaddressed (0)

none: this is review 1

Non-blocking (12)

SEVERITY - low
IMPACT - Resource tagging says Pods, endpoints, volumes, etc.; taggable types are exactly Pod, endpoint, network volume, and Instant Cluster (TagResourceType at prisma/schema.prisma:3828), not templates or secrets.
SOLUTION - List the four supported resource types explicitly.

SEVERITY - low
IMPACT - Migration step 1 says staff run a script; it is a CSR-admin GraphQL mutation (adminMergeTeamsIntoOrganization), and it can merge several teams into one org or extend an existing org.
SOLUTION - Say Runpod staff run the migration and mention multi-team merges.

SEVERITY - low
IMPACT - Migration step 3 lists a subset of transferred resources; the fold also moves Flash apps, reservations, VXLANs, deployment role delegations and S3 credentials (model/src/org/fold.ts).
SOLUTION - Add the missing resource types or say all org-aware resources.

SEVERITY - low
IMPACT - Overview mentions a suspended member state; there is no suspend status on OrganizationMembership, only removal, and removal also revokes the member's org S3 credentials.
SOLUTION - Drop suspended and note credential revocation on removal.

SEVERITY - low
IMPACT - roles.mdx lines 6-29 use a single space on blank lines instead of empty lines, which trips whitespace linting and diffs.
SOLUTION - Replace the space-only lines with empty lines.

SEVERITY - low
IMPACT - roles.mdx line 39 has no blank line before it, so the sentence renders inside numbered step 3.
SOLUTION - Insert a blank line before Role changes take effect immediately.

SEVERITY - low
IMPACT - billing.mdx lines 15-17 bullets lack terminal periods, which the style guide requires.
SOLUTION - End each bullet with a period.

SEVERITY - low
IMPACT - docs.json new pages array is indented two spaces short of its siblings and the closing bracket is misaligned.
SOLUTION - Match the fourteen-space indentation used by the Accounts and billing group.

SEVERITY - low
IMPACT - roles.mdx line 24 writes serverless endpoints in lowercase; the style guide capitalizes Serverless as a product name.
SOLUTION - Change to Serverless endpoints here and in any other occurrences.

SEVERITY - low
IMPACT - overview.mdx Get started cards omit the horizontal attribute the style guide prescribes for next-steps card groups, unlike pods and serverless overviews.
SOLUTION - Add horizontal to each Card.

SEVERITY - low
IMPACT - The org shorthand appears throughout (org admins, intra-org, org-owned) while existing account pages spell out the noun; the style guide does not list org as an approved term.
SOLUTION - Use Organization or organization consistently, or define the shorthand once in the overview.

SEVERITY - low
IMPACT - PR title Lg org setup team mig and body Draft do not describe the change for future history readers.
SOLUTION - Retitle to something like Add Organizations docs and describe the pages added.

Review metadata

review 1 · fable · 8f7bf0d

RAN - jq . docs.json valid | 7/7 new page paths exist | npx mint broken-links 5 broken in 2 files, all pre-existing on main, 0 in PR pages | node scripts/validate-tooltips.js pass | relative link and anchor check 7/7 resolve | git merge-tree origin/main HEAD clean | claims checked against RunPod monorepo at 3f635fb9 (2026-09-15)
NOT RUN - vale (not installed in this environment) | mintlify dev render | console UI path verification (frontend not in monorepo)
RELIED ON - loop brief for mid-August beta launch date | Linear DOCS-447 text as the request of record

[rambo-runpod]

SEVERITY - high
IMPACT - Admins look for three access modes that do not exist; the only join path in code is an email invitation (model/src/org/invite/organizationInviteCreate.ts, organizationInviteAccept.ts); no mode enum gates invites.
SOLUTION - Replace the access-modes section with the real invite flow: staff provisions the org, admins invite by exact email, invites expire after 14 days, 150 pending max, verified email required.

[rambo-runpod]

SEVERITY - high
IMPACT - Readers follow per-provider SAML setup steps for a feature that has no implementation: no SAML/OIDC/SSO model, columns, resolver, or settings anywhere in prisma/schema.prisma, model/src/org*, or node/graphql.
SOLUTION - Remove the Configure SSO section and provider subsections until SSO ships; at most one sentence that SSO is planned, without provider names or console steps.

[rambo-runpod]

SEVERITY - high
IMPACT - Admins expect a domain allowlist and a gmail/yahoo/outlook/hey block that do not exist; invite acceptance is bound to the exact invited address (organizationInviteAccept.ts:79), not a domain.
SOLUTION - Delete the Email domain allowlist section, or rewrite it to say acceptance requires the invited address with a verified email.

[rambo-runpod]

SEVERITY - high
IMPACT - Security posture misrepresented: no IP allowlist model, middleware, 403 path, or 60-second propagation exists in the monorepo, so customers may assume network restriction they cannot configure.
SOLUTION - Remove the IP allowlist section entirely until an implementation lands; do not describe CIDR, 403, or propagation timing.

[rambo-runpod]

SEVERITY - high
IMPACT - Claim of exactly four roles is stale: custom roles exist (OrgRole table, orgRoleCreate/Update/Delete in node/graphql/schema/org/role.ts:57-63, 25 per org), so admins reading this will not know they can define roles.
SOLUTION - State that four built-in roles ship plus up to 25 custom roles per org composed from capabilities, and add a short custom-roles section.

[rambo-runpod]

SEVERITY - high
IMPACT - runpod:region and runpod:data-center system tags and the launch backfill do not exist anywhere in the repo; the only reserved key is runpod:cost-center (model/src/tag/constants.ts:4), and region is a first-class filter field, not a tag.
SOLUTION - Rewrite System tags to name only runpod:cost-center as the system-managed tag behind cost centers, and drop the backfill paragraph.

[lavanya-gunreddi]

@Promptless Update with this information for this comment "Runpod automatically manages one reserved tag: runpod:cost-center. This tag
is applied by the system when you assign a resource to a cost center. You cannot
create or modify tags that use the runpod: namespace prefix."

[rambo-runpod]

SEVERITY - high
IMPACT - Groups are described as social only, but in the default closed sharing mode groups are the visibility boundary: non-admin members only see resources of users who share a group with them (node/graphql/index.ts:388-395, model/src/ownership/index.ts:26-34).
SOLUTION - Replace this bullet with an explanation of open vs closed sharing modes and how group membership controls which resources a member can see and use.

[lavanya-gunreddi]

@Promptless add the following information for Rambo's comment comment :- Groups control resource visibility in closed sharing mode. Your organization
can operate in one of two sharing modes. In open sharing mode, all org members
can see each other's Pods and endpoints regardless of group membership. In closed
sharing mode, a member can only see resources that belong to users who share at
least one group with them. A member who belongs to no groups sees no other
member's resources in closed mode.

• A member can belong to zero or many groups simultaneously. Groups are additive:
  joining one group has no effect on membership in others.
• Only org admins can manage group membership. Groups have no leader or group-level admin.

[rambo-runpod]

SEVERITY - high
IMPACT - Team owners are told members are not moved and must be re-invited; the staff merge folds every participant with a mapped role and a group per team (mergeTeamsIntoOrganization.ts:47-50, 104, 591), so following these docs leads to duplicate invites and wrong expectations about members' personal resources.
SOLUTION - Rewrite steps 4 and 6: all members join automatically with roles mapped from their team role, each team becomes a group, and every participant's personal resources fold in during the merge.

[lavanya-gunreddi]

@Promptless work on this comment

[rambo-runpod]

SEVERITY - high
IMPACT - SSH guidance is inverted: for org-scoped deploys PUBLIC_KEY is the union of all current members' keys, frozen at creation (model/src/sshKey/orgKeyUnion.ts:12-45, injected at model/src/utils/index.ts:276-284), so shared access already works and the private-key sharing workaround is unnecessary.
SOLUTION - Document the member-key union behavior and its creation-time freeze, keep the RUNPOD_SSH_PUBLIC_KEY override note, and delete the shared-private-key suggestion.

[lavanya-gunreddi]

@Promptless work on this comment

[rambo-runpod]

SEVERITY - high
IMPACT - Exclusivity is an application check, not a data-layer constraint (model/src/team/joinTeam.ts:82-88); once a membership is deleted the check passes again, and accepting an org invite while on a team is allowed and evicts you from the team rather than being blocked. What is permanent is that folded resources never return.
SOLUTION - Rewrite: joining an org removes you from any team and folds your resources permanently; you can only be in one org or team at a time; resources are never returned on leaving.

[lavanya-gunreddi]

@Promptless work on this comment

[promptless]

Thanks — picking these up now. I'm reviewing the review comments on this PR and will follow up here with the documentation changes or a response shortly.

[promptless]

Research is done on all three review comments. They point to corrections needed on two pages — the organizations overview and the migrate-from-teams guide — covering how org/team exclusivity is enforced, how SSH key access works for org-scoped Pods, and the member-migration steps. Drafting the documentation updates now.

[rambo-runpod]

COMMENT: all 20 prior highs resolved, 1 new high, 8 medium, 8 low

Re-review of 26da3486. The PR head advanced two commits past the SHA in my dispatch (a04cc725 migrate-from-teams, 26da3486 overview); this review covers both. Every high from reviews 1 and 2 is now resolved: access modes, SSO, email-domain allowlist, IP allowlist (access.mdx rewritten to the real invite flow); four-roles/custom roles, billing role scope, MVP RBAC section, admin SSO powers (roles.mdx); postpaid-only billing and Billing Explorer access (billing.mdx, overview.mdx); 64-character tag limit and system tags (resource-tagging.mdx); groups/sharing modes; migration steps 4-6, the PUBLIC_KEY override variable, the cross-team precondition, the post-migration SSO checklist; and the overview exclusivity and Access key concepts. Checked cell by cell against model/src/authz/roleGrid.ts, model/src/org/invite/, model/src/org/role/, model/src/tag/constants.ts, prisma/schema.prisma and node/graphql/schema/costCenter.ts at monorepo 6b778e62.

One new high: the rewritten access page understates what accepting an invite does to a team the invitee owns. Inline on organizations/access.mdx:28.

SEVERITY - medium
IMPACT - billing.mdx:27 credits only the billing role with cost centers; every cost-center mutation gates on BILLING:UPDATE (costCenter.ts:90-126), which admin holds too, and roles.mdx:13 says admin can.
SOLUTION - Say admin and billing manage cost centers, matching the roles table on the sibling page.

SEVERITY - medium
IMPACT - access.mdx:32 says only admins can remove members; any member can remove themselves (organizationMembershipDelete.ts:108-113), and no one can remove the last admin (assertNotLastAdmin).
SOLUTION - Add that a member can leave on their own and that the last remaining admin cannot be removed.

SEVERITY - medium
IMPACT - An invitee holding an active savings plan is rejected at accept with a hard error (organizationInviteAccept.ts:91-98); the access page lists no such precondition, so the invitee sees an opaque failure.
SOLUTION - Add an accept precondition: the invitee must have no active savings plan, since plans cannot transfer to an Organization.

SEVERITY - medium
IMPACT - groups.mdx:16 scopes open-mode visibility to Pods and endpoints; the open-mode read filter is { organizationId } for every org-aware resource, volumes, clusters, templates and secrets included (model/src/ownership/index.ts).
SOLUTION - Say all org-owned resources instead of naming only Pods and endpoints. Carried from review 2.

SEVERITY - medium
IMPACT - Sharing mode is a mutable admin-controlled setting (sharingMode on organizationUpdate, node/graphql/schema/org/organization.ts:53), but no page says who can change it or where, so readers treat closed as fixed.
SOLUTION - Add to groups.mdx who can switch sharing mode and the console path, alongside the closed default.

SEVERITY - medium
IMPACT - Resource tagging sits behind its own per-user rollout allowlist separate from the orgs flag (model/src/tag/assertGeneralTaggingEnabled.ts), yet the page reads as generally available to every org.
SOLUTION - Note on resource-tagging.mdx that tagging is rolling out per account, the way overview.mdx flags the beta. Carried from review 1.

SEVERITY - medium
IMPACT - Console paths across all six pages, Settings to Members, Groups, Roles, Billing to Billing Explorer, the Tags button, and the claim that console.runpod.io/team stops working, are unverifiable from the monorepo.
SOLUTION - Have someone walk each path in the current console before publishing. Carried from review 1.

SEVERITY - medium
IMPACT - accounts-billing/manage-accounts.mdx on main still presents Team accounts as the collaboration model with self-serve conversion and no mention of Organizations; this PR adds the Organizations group but leaves that page untouched.
SOLUTION - Add a pointer from manage-accounts.mdx to the Organizations overview so the two account models are not described independently.

SEVERITY - medium
IMPACT - Judgment call: PR #748 is still open and still places the same content at accounts-billing/organizations/ with different filenames (roles-and-permissions, SSH-key-management); neither path exists on main, so the second merge duplicates pages.
SOLUTION - Consolidate into one PR and close the other. Recommendation and reasoning: keep this PR's content, which is now code-verified across every page, and move it under accounts-billing/organizations/ so it sits with the other account topics it already links into; pull #748's SSH page across after renaming it to lowercase-kebab, and drop #748's roles and tag content, which was not checked against roleGrid.ts. Carried from review 1, restated once.

Unaddressed (0)

none: all 15 high threads from review 1 and all 5 from review 2 are resolved at 26da3486. The body-only mediums and lows carried from both reviews are restated above and in Non-blocking rather than left as dangling references.

Non-blocking (8)

SEVERITY - low
IMPACT - docs.json:292-300 indents the Organizations pages array two spaces short of the sibling Accounts and billing group and misaligns its closing bracket.
SOLUTION - Match the fourteen-space indentation of the neighbouring group. Carried from review 1.

SEVERITY - low
IMPACT - groups.mdx:16 is still a single 90-word paragraph covering open mode, closed mode, the default and the admin carve-out, unlike the bullets above it.
SOLUTION - Split into three bullets. Carried from review 2.

SEVERITY - low
IMPACT - migrate-from-teams.mdx:19 and :26 state the personal-resources-are-never-reclaimed fact twice within eight lines, and the Warning at :10 states it a third time.
SOLUTION - Keep the Warning and step 5, and cut the prep section to the action of telling members. Carried from review 2.

SEVERITY - low
IMPACT - pods/configuration/use-ssh.mdx:73, linked from migrate-from-teams.mdx:51, still documents an SSH_PUBLIC_KEY override that appears nowhere in the monorepo, contradicting the corrected PUBLIC_KEY text one click away.
SOLUTION - Fix the variable on the Pods SSH page in this PR or a follow-up. Carried from review 2, still unchanged.

SEVERITY - low
IMPACT - access.mdx:11 and roles.mdx:40 say only admins invite and create roles; both gate on ORG:CREATE, which a custom role can carry, so the built-in-role phrasing is narrower than the check.
SOLUTION - Phrase these as members holding the member-management capability, which the admin role grants by default.

SEVERITY - low
IMPACT - The custom-roles section omits three limits a reader hits immediately: names are capped at 191 characters, built-in role names are reserved, and an author can only grant capabilities they already hold (capabilityCeiling.ts).
SOLUTION - Add the grant-ceiling rule and the reserved-name rule to the custom-roles steps.

SEVERITY - low
IMPACT - migrate-from-teams.mdx:40-42 exposes the internal type name SharedApiKey as a user-facing heading and term; no console surface or other doc page uses it.
SOLUTION - Use the customer-facing name for S3-compatible storage credentials throughout the section.

SEVERITY - low
IMPACT - The pages capitalize Team, Teams and Organization mid-sentence throughout, while accounts-billing/manage-accounts.mdx on main writes team lowercase in prose and the repo CLAUDE.md lists neither as a proper noun.
SOLUTION - Lowercase organization and team in prose, reserving capitals for product-name usage, or add both to the terminology list.

Review metadata

review 3 · opus · 26da348

RAN - jq . docs.json valid | 7/7 nav page paths exist | npx mint broken-links clean, 0 broken | node scripts/validate-tooltips.js pass | all six pages read in full | every claim re-checked against RunPod monorepo at 6b778e62 (2026-09-16) | gh pr view 748 still open, still conflicting
NOT RUN - vale (not installed) | mintlify dev render | console UI path verification (frontend not in monorepo) | Linear ticket coverage check (ticket text not supplied in this dispatch)
RELIED ON - review 1 and 2 thread ids for dedupe | docs/plans/ design notes for sharing-mode and roles intent

[rambo-runpod]

SEVERITY - high
IMPACT - A team owner who accepts an org invite has their team deleted and every co-member kicked out, not just themselves removed: foldInviteeOnAccept.ts:60-77 folds the joiner's resources (which for a team owner are the team's resources, since team rows carry the owner's userId), then team.deleteMany on every team they own, cascading all memberships, then teamMembership.deleteMany for teams they merely belong to. Both this line and overview.mdx:24 and :31 say only that joining removes you from your team, so a team owner clicking an invite link silently destroys the team for everyone and folds the team's Pods, endpoints, volumes and secrets into the Organization irreversibly.
SOLUTION - Add that if you own a team, accepting deletes that team and removes all its members, and that the team's resources fold into the Organization permanently; mirror the sentence in the overview Membership concept.

[lavanya-gunreddi]

@Promptless In all files under organizations/, lowercase "organization" and "team" when used as common nouns in prose (e.g. "the organization", "org members", "team roles"). Keep them capitalized only when they are part of a proper product name or at the start of a sentence. Do not change code, frontmatter, headings, or link text.

[promptless]

On it — I'll lowercase "organization" and "team" when they're used as common nouns in prose across the files under organizations/, while keeping them capitalized in product names and at the start of sentences, and leaving code, frontmatter, headings, and link text untouched. I'll follow up here once the changes are ready.

[promptless]

Update: I've scoped the change to 7 files under organizations/ (access, billing, groups, migrate-from-teams, overview, resource-tagging, roles) that contain candidate prose instances. Applying the casing edits now, keeping product names, sentence-start usage, code, frontmatter, headings, and link text untouched.

[promptless]

Done — I lowercased "organization" and "team" wherever they're used as common nouns in the prose across all seven pages under organizations/ (55 replacements: access 4, billing 4, groups 6, migrate-from-teams 14, overview 18, resource-tagging 1, roles 8), and pushed them to this PR's branch.

I kept them capitalized where they're part of a product name (for example "Organizations", "Unlike Teams", "Migration from Teams to Organizations", the comparison-table column headers, and the "Team (has an owner)" label), at the start of a sentence, and in headings, frontmatter, and link text.

One judgment call worth flagging: on the overview page I lowercased "team account" in the "Migrate from Teams" card's descriptive body text, but kept "Team account" capitalized in the beta note where it refers to the legacy account model. Let me know if you'd prefer those treated the same way.