docs: refresh organization setup pages and clarify name versus namespace (#26239)

Deep validation, added important conceptual information, refresh tier 2
on setup docs for organizations

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: akristen

content/manuals/accounts/organization/_index.md

@@ -35,26 +35,15 @@ aliases:
   - /accounts/organization/overview/
 ---
 
-Organization and company owners can manage members, control access, and enforce
-security across their Docker environments. You perform these tasks in Docker
-Home, which provides centralized observability, access management, and security
-controls.
-
-A Docker organization is a collection of teams and repositories under
-centralized management. Organization administrators group members and
-assign repository access at scale.
-
-As an organization or company owner, you can:
-
-- Create and manage companies and organizations
-- Assign roles and permissions to members
-- Group members into teams to manage access by project or role
-- Set company-wide policies, including SCIM provisioning and security
-  enforcement
+A Docker organization is a collection of teams and repositories that you
+manage in [Docker Home](https://app.docker.com/). Organization and company
+owners manage members, assign access, and enforce security.
 
 For how individual, organization, and company accounts compare, see
 [Accounts](/manuals/accounts/_index.md). For individual accounts, see
 [Docker individual accounts](/manuals/accounts/individual/_index.md).
+To create, convert, or onboard an organization, see
+[Set up a Docker organization](/manuals/accounts/organization/setup/_index.md).
 
 ## Organization structure
 

content/manuals/accounts/organization/setup/_index.md

@@ -1,22 +1,30 @@
 ---
-title: Set up your organization
+title: Set up a Docker organization
 linkTitle: Setup
 weight: 10
-description: Learn how to set up your Docker organization, including creating an organization, onboarding, and converting an account.
-keywords: set up organization, create organization, onboard, convert account, docker home
+description: >
+  Create, convert, or onboard a Docker organization under one namespace and
+  subscription.
+keywords:
+  - Docker organization setup
+  - create organization
+  - onboard organization
+  - convert Docker account
+  - organization namespace
+  - Docker Home
 grid:
   - title: Create your organization
-    description: Create an organization to group teams and members and assign access.
+    description: Choose a new namespace and subscription.
     icon: building-storefront
     link: /accounts/organization/setup/orgs/
+  - title: Convert your account
+    description: Keep an existing Docker ID as the organization namespace.
+    icon: arrows-right-left
+    link: /accounts/organization/setup/convert-account/
   - title: Onboard your organization
-    description: Onboard and secure your Docker Team or Business organization.
+    description: Invite members and configure sign-in.
     icon: magnifying-glass-plus
     link: /accounts/organization/setup/onboard/
-  - title: Convert account
-    description: Convert an existing Docker user account into an organization.
-    icon: arrows-right-left
-    link: /accounts/organization/setup/convert-account/
   - title: Manage your organization
     description: Add members, teams, licenses, and seats after setup.
     icon: user-group
@@ -29,26 +37,39 @@ aliases:
   - /admin/organization/setup/
 ---
 
-Before you manage members and access, set up your Docker organization. You can
-create an organization, onboard and secure it, or convert an existing user
-account into an organization.
+An organization groups members and teams under one namespace and one
+subscription. Anyone with a [Docker ID](/manuals/accounts/_index.md) can
+create an organization or convert an individual account into one.
 
-## Setting up your organization
+You start by creating a new organization or converting an individual
+account. After creating or converting, you can onboard your organization.
 
-You set up your organization from [Docker Home](https://app.docker.com) and
-must be assigned the
-[organization owner role](/manuals/security/roles-and-permissions/_index.md).
-Setting up an organization happens in broad phases:
+## Names versus namespaces
 
-1. You can create a new organization, or convert an existing user account
-   into one. Choose the option that fits how you already use Docker. You
-   don't need both.
-1. After creating your organization, you must onboard it by inviting members,
-   securing authentication, and enforcing sign-in. These steps build on each
-   other, so follow them in order.
+When you create an organization, you set two values:
 
-## Next steps
+- Organization namespace is the permanent, unique identifier for your
+  organization. It becomes the first part of every image name you push, as
+  in `namespace/image:tag`. You can't change it after you create the
+  organization.
+  - Docker IDs and organization namespaces must be unique.
+  - If a Docker ID is `acme`, no organization can use `acme` as its
+    namespace.
+- Organization name is the display name shown on your organization's
+  Docker profile. You can change it at any time. See
+  [Change organization information](/manuals/accounts/organization/manage/general-settings.md).
 
-Explore the following sections to set up your organization.
+## Choose how to set up
+
+The difference between creating and converting is what happens to your
+existing repositories.
+
+- Create an organization: Choose a new namespace. Your existing
+  repositories stay under your personal Docker ID.
+- Convert your account: Your Docker ID becomes the organization’s
+  namespace. Your repositories and image names stay the same, so anyone
+  pulling your images can keep using their existing image references.
+
+## Next steps
 
 {{< grid >}}

content/manuals/accounts/organization/setup/convert-account.md

@@ -1,85 +1,132 @@
 ---
-description: Convert your Docker Hub user account into an organization
+title: Convert a Docker account to an organization
 linkTitle: Convert account
-title: Convert an account into an organization
-keywords: docker hub, hub, organization, convert account, migrate account
-weight: 40
+weight: 20
+description: >-
+  Convert an individual Docker account into an organization. Keep the same
+  Docker ID and repository namespace, then assign a new owner for shared
+  access.
+keywords:
+  - convert Docker account
+  - convert account to organization
+  - individual account to organization
+  - organization owner
+  - Docker organization
+  - organization namespace
 aliases:
   - /admin/organization/setup/convert-account/
   - /docker-hub/convert-account/
   - /admin/organization/convert-account/
+toc_max: 3
 ---
 
 {{< summary-bar feature_name="Admin orgs" >}}
 
-Learn how to convert an existing user account into an organization. This is
-useful if you need multiple users to access your account and the repositories
-it’s connected to. Converting it to an organization gives you better control
-over permissions for these users through
-[teams](/manuals/accounts/organization/manage/manage-a-team.md) and
-[roles](/manuals/security/roles-and-permissions/_index.md).
-
-When you convert a user account to an organization, the account is migrated to
-a Docker Team subscription by default.
+When you convert, your
+[Docker ID](/manuals/accounts/_index.md) becomes an organization instead of
+an individual account. The Docker ID stays the same, so repository
+namespaces and names stay the same. Convert an existing individual account
+into an organization when more than one person needs access to that
+account and its repositories. To choose a new namespace and keep your
+Docker ID as an individual account, see
+[Create a Docker organization](/manuals/accounts/organization/setup/orgs.md).
+
+## Conversion
+
+Converting an account into an organization does the following:
+
+- The account gets a
+  [Docker Team](/manuals/subscription-billing/plans/docker.md)
+  subscription. If the individual account was on a paid plan, it keeps
+  the same billing cycle.
+- Docker signs you out. Your email address is no longer on any Docker
+  account. You can [sign up](https://hub.docker.com/signup) with it again
+  or update an existing account to use it.
+- Repository collaborators are removed.
+  [Invite them to your organization](/manuals/accounts/organization/manage/members.md),
+  then add them to a
+  [team](/manuals/accounts/organization/manage/manage-a-team.md)
+  that has access to the repositories.
+- Existing automated builds appear as if the new owner set them up.
 
 ## Prerequisites
 
-Before you convert a user account to an organization, ensure that you meet the following requirements:
+Before you convert an individual account to an organization:
 
-- The user account that you want to convert must not be a member of a company or any teams or organizations. You must remove the account from all teams, organizations, or the company.
+- The individual account must have a verified email address.
+- You need a separate Docker ID to [assign as organization owner](#choose-an-organization-owner).
+- The individual account must not belong to an organization, a team, or a
+  company. If it does, you must
+  [leave the organization](#leave-an-existing-organization) before you convert.
 
-  To do this:
-  1. Navigate to **My Hub** and then select the organization you need to leave.
-  1. Find your username in the **Members** tab.
-  1. Select the **More options** menu and then select **Leave organization**.
+> [!TIP]
+>
+> After you convert an account, personal access tokens from that account
+> stop working. Sign in as the new owner and create an
+> [organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md)
+> for the converted organization.
 
-  If the user account is the sole owner of any organization or company, assign another user the owner role and then remove yourself from the organization or company.
+### Choose an organization owner
 
-- You must have a separate Docker ID ready to assign as the owner of the organization during conversion.
+To convert, you must name an owner. That owner has full administrative access
+to configure and manage the organization. You can add more owners after
+conversion. Each owner signs in to a separate individual account, then
+selects the organization in Docker Home.
 
-  If you want to convert your user account into an organization account and you don't have any other user accounts, you need to create a new user account to assign it as the owner of the new organization. With the owner role assigned, this user account has full administrative access to configure and manage the organization. You can assign more users the owner role after the conversion.
+To name someone else as the owner, enter that person's Docker ID during
+conversion. If you still need access after conversion, you must sign up
+again so the new owner can invite you to the organization.
 
-## What happens when you convert your account
+If you want to remain the sole owner without assigning another owner, you
+must create a second individual account with a different email address.
+Use your new account's Docker ID.
 
-The following happens when you convert your account into
-an organization:
+- For example, if the account you are converting uses `alex@example.com`,
+  create the owner account with `alex.admin@example.com`.
+- After conversion, `alex@example.com` is no longer on any Docker account.
 
-- This process removes the email address for the account. Notifications are
-  instead sent to organization owners. You'll be able to reuse the
-  removed email address for another account after converting.
-- The current subscription will automatically cancel and your new subscription
-  will start.
-- Repository namespaces and names won't change, but converting your account
-  removes any repository collaborators. Once you convert the account, you'll need
-  to add repository collaborators as team members.
-- Existing automated builds appear as if they were set up by the first owner
-  added to the organization.
-- The user account that you add as the first owner will have full
-  administrative access to configure and manage the organization.
+You can update the `alex.admin@example.com` email back to
+`alex@example.com` after conversion. See
+[Update email address](/manuals/accounts/individual/manage-account.md#update-email-address).
 
-## Convert an account into an organization
+### Leave an existing organization
 
-> [!IMPORTANT]
->
-> Converting an account into an organization is permanent. Back up any data
-> or settings you want to retain.
+Use this procedure when the individual account is already a member of an
+organization, a team, or a company. The account can be converted after it
+has left each of them. If it has no memberships, skip this section and
+[convert the account](#convert-to-an-organization).
 
-1. Sign in to [Docker Home](https://app.docker.com/).
-1. Select your avatar in the top-right corner to open the drop-down.
-1. From **Account settings**, select **Convert**.
-1. Review the warning displayed about converting a user account. This action
-   cannot be undone and has considerable implications for your assets and the
-   account.
-1. Enter a **Username of new owner** to set an organization owner. The new
-   Docker ID you specify becomes the organization’s owner. You cannot use the
-   same Docker ID as the account you are trying to convert. The Docker ID is
-   case-sensitive.
-1. Select **Confirm**. The new owner receives a notification email. Use that
-   owner account to sign in and manage the new organization.
+If the account is the only owner of an organization or company, assign
+the owner role to another member first. Leave after that member can
+administer the organization or company.
 
-> [!TIP]
->
-> After you convert an account, existing personal access tokens from that
-> account no longer work. Sign in as the new owner and create an
-> [organization access token (OAT)](/manuals/security/access-tokens/organization-access-tokens.md)
-> for the converted organization.
+To leave an organization and its teams:
+
+1. Sign in to [Docker Home](https://app.docker.com/) and select the
+   organization.
+1. Select **Members** and find your username.
+1. Select the **Actions** menu, then **Leave organization**.
+
+## Convert to an organization
+
+Converting an account into an organization is permanent. Back up any data
+or settings you want to keep.
+
+1. Sign in to [Docker Home](https://app.docker.com/).
+1. Select your avatar in the top-right corner.
+1. Select **Account settings**, then **Convert**.
+1. Review the warning. You can't undo this action.
+1. Enter the **Username of new owner**.
+   Enter a Docker ID, not an email address. Use 4 to 30 letters and
+   digits. The Docker ID must belong to a different account from the one
+   you are converting. That account must be active and have a verified
+   email address.
+1. Select **Confirm**. For an account on a Pro plan, the button is
+   **Confirm and purchase**.
+   The new owner receives a notification email. Sign in with that account
+   to manage the organization.
+
+## Next steps
+
+- [Onboard your organization](/manuals/accounts/organization/setup/onboard.md)
+- [Create an organization access token](/manuals/security/access-tokens/organization-access-tokens.md)