Clarify AWS Organization creation and Quickstart requirements

docs/intro/intro.mdx

@@ -9,6 +9,7 @@ import Intro from '@site/src/components/Intro';
 import KeyPoints from '@site/src/components/KeyPoints';
 import ActionCard from '@site/src/components/ActionCard';
 import PrimaryCTA from '@site/src/components/PrimaryCTA';
+import SecondaryCTA from '@site/src/components/SecondaryCTA';
 import DocCardList from '@theme/DocCardList';
 import Steps from '@site/src/components/Steps';
 import Step from '@site/src/components/Step';
@@ -28,7 +29,18 @@ graph LR
     E --> E
 ```
 
-Before you jump into the Cloud Posse reference architecture, let’s review what makes it tick. Cloud Posse has helped companies—from scrappy startups to massive enterprises—win big with Terraform. But here’s the key: we do things differently. Everything is based on open source that your team owns and operates. We’re not another enterprise platform with hidden lock-in. If your team depends on our work, we offer [support](/support) to help you move faster and build with confidence.
+<ActionCard title="Get Started the Right Way">
+  All documentation on this site describes our **AWS Reference Architecture**. We provide all tools for free, but **the complete configuration that ties everything together is what we sell** through Quickstart (DIY) and Jumpstart (done-for-you).
+
+  **Looking for the configurations?** Start by choosing your path to understand how to get the configurations you'll need.
+
+  <div>
+    <PrimaryCTA to="/intro/path">Choose Your Path</PrimaryCTA>
+    <SecondaryCTA to="https://cloudposse.com/pricing">View Pricing</SecondaryCTA>
+  </div>
+</ActionCard>
+
+Before you jump into the Cloud Posse reference architecture, let's review what makes it tick. Cloud Posse has helped companies—from scrappy startups to massive enterprises—win big with Terraform. But here’s the key: we do things differently. Everything is based on open source that your team owns and operates. We’re not another enterprise platform with hidden lock-in. If your team depends on our work, we offer [support](/support) to help you move faster and build with confidence.
 
 Our goal? To create a collaborative ecosystem where everyone, regardless of the company, can work together on infrastructure, so we stop reinventing the wheel.
 
@@ -75,7 +87,7 @@ This documentation site breaks down SweetOps into the following sections to help
   <Step>
     ### <StepNumber/> Community
 
-    The [**Community**](/community) section is for those who want to engage with the SweetOps community and get support.
+    The [**Community**](/community) section is for collaborating on the development of Cloud Posse's open source. Request pull request reviews, ask how others have solved similar problems, and work together to improve our modules, components, and tools. It's where the community collectively builds the ecosystem.
 
     <Steps>
       - Join our Slack community

docs/intro/path.mdx

@@ -14,21 +14,41 @@ import SecondaryCTA from "@site/src/components/SecondaryCTA";
 import Steps from "@site/src/components/Steps";
 
 <Intro>
-  There are two easy ways to get started. You can dive right in with our Quickstart documentation if you're a hands-on learner. Alternatively, if you prefer Cloud Posse to do it for you, try our Jumpstart. Pick what works best for you! Plus, we provide [multiple support options](/support) if you get stuck.
+  Ready to build with our reference architecture? Choose your path: **Quickstart** (you implement with our configs) or **Jumpstart** (we implement for you). Both include the complete reference architecture configurations—the critical piece that ties all our free tools together.
 </Intro>
 
 All of the documentation on this site corresponds to our [AWS Reference Architecture](https://cloudposse.com/services).
 
-We give away all the tools for free—[Terraform modules](https://github.com/cloudposse), [components](https://github.com/cloudposse-terraform-components), [Atmos](https://atmos.tools), and TONS more. But the system that ties it all together? That’s what we sell. Our reference architecture funds the Open Source that powers your business.
+We give away all the tools for free—[Terraform modules](https://github.com/cloudposse), [components](https://github.com/cloudposse-terraform-components), [Atmos](https://atmos.tools), and TONS more. But the system that ties it all together? That's what we sell. Our reference architecture funds the Open Source that powers your business.
+
+:::tip How Commercial Open Source Works
+
+At Cloud Posse, we give away **everything** except one critical piece: **the configuration**.
+
+All our tools are free—[Terraform modules](https://github.com/cloudposse), [components](https://github.com/cloudposse-terraform-components), [Atmos](https://atmos.tools), GitHub Actions, and more.
+
+But the complete system that ties it all together? That's what we sell.
+
+**Why this matters:** The documentation on this site describes our reference architecture, but **following it without the Quickstart or Jumpstart configurations is not a supported path**.
+
+You'll encounter gaps and blockers (like needing Atmos stack configs that don't exist without our configurations).
+
+This commercial model sustains the open source ecosystem your business depends on.
+
+When you invest in Quickstart or Jumpstart, you're funding the continuous development of all the free tools you use.
+
+:::
 
 <Tabs>
   <TabItem value="quickstart" label="Quickstart (DIY)">
 
-    Our Quickstart provides an end-to-end configuration of our AWS reference architecture [customized to your needs](/quickstart/kickoff/#-review-design-decisions) and implemented by you at your own pace.
+    Our Quickstart provides the **complete end-to-end configuration** of our AWS reference architecture, [customized to your needs](/quickstart/kickoff/#-review-design-decisions) and implemented by you at your own pace.
+
+    **What you get:** The Atmos stack configurations (`stacks/catalog/*.yaml`), component wiring, and architectural decisions that tie our free tools together. This is the missing piece you can't get from the docs alone.
 
-    You can start today, by following along with our [Quickstart documentation](/quickstart) to get a sense of what's involved.
+    Browse our [Quickstart documentation](/quickstart) to preview what's involved before purchasing.
 
-    To get started, roll up your sleeves and follow the steps below to start building out your infrastructure!
+    **Ready to build?** Follow these steps:
 
     <Steps>
       - [Buy our "Quickstart"](https://cloudposse.com/pricing) to receive all the configurations.

docs/layers/accounts/accounts.mdx

@@ -27,6 +27,16 @@ This chapter presents how Cloud Posse designs and manages AWS Account architectu
   <figcaption>AI generated voice</figcaption>
 </figure>
 
+:::caution Before You Start
+
+This guide describes the **account management architecture** in our reference architecture. To actually implement it, you'll need the complete Atmos stack configurations that define your AWS Organization structure.
+
+**Looking for the configurations? [Start here](/intro/path)** to get the Quickstart (DIY) or Jumpstart (done-for-you) package, which includes all the `stacks/catalog/*.yaml` files referenced throughout this documentation.
+
+**Already have configs?** Continue reading to understand the architecture.
+
+:::
+
 ## The Problem
 
 The [AWS Well-Architected Framework](https://docs.aws.amazon.com/pdfs/wellarchitected/latest/userguide/wellarchitected-ug.pdf) defines AWS architectural best practices and presents a set of foundational questions to enable you to understand how a specific architecture aligns with cloud best practices.

docs/layers/accounts/deploy-accounts.mdx

@@ -25,6 +25,18 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work
 | Deploy accounts settings  | `atmos workflow deploy/account-settings -f quickstart/foundation/accounts` |
 | Finalize account setup    | Click Ops                                            |
 
+:::info Required: Quickstart Configurations
+
+This deployment guide references Atmos stack configurations that are provided as part of our [Quickstart package](/intro/path). Specifically, you'll need:
+
+- `stacks/catalog/account.yaml` - Defines your AWS Organization structure
+- `stacks/catalog/account-map.yaml` - Maps account names and roles
+- Various mixin files that configure organizational units and accounts
+
+**New to the reference architecture?** The complete stack catalog is what we sell—it's how we sustain our open source. [Learn more about choosing your path](/intro/path).
+
+:::
+
 <Steps>
   <Step>
     ## <StepNumber/> Prepare Account Deployment
@@ -33,6 +45,8 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work
     provisioned**. If you aren't confident about the email configuration, account names, or anything else, now is the time
     to make changes or ask for help.
 
+    **Need help understanding the configuration?** See the expandable example below for a sample `account.yaml` structure and explanation of key fields. For adding new accounts or OUs later, see [How to Add a New Organizational Unit](/layers/accounts/tutorials/how-to-add-a-new-organizational-unit/).
+
     You should double-check the following:
 
     <TaskList>
@@ -41,13 +55,85 @@ This step-by-step process outlines how to deploy AWS accounts using `atmos` work
       all the mixins have been imported)
     - Plan the run with `atmos terraform plan account -s core-gbl-root`
     </TaskList>
+
+    <Note title="New to Atmos?">
+    If you're unfamiliar with Atmos, here's what you need to know:
+
+    - **Stacks** are YAML configuration files that define infrastructure (e.g., `core-gbl-root` is a stack)
+    - **Components** are Terraform modules that get deployed (e.g., `account` is a component)
+    - **Catalogs** (`stacks/catalog/*.yaml`) contain reusable configuration that stacks can import
+    - Commands follow the pattern: `atmos terraform <action> <component> -s <stack>`
+
+    For a deeper introduction, see [How to Use Atmos](/learn/maintenance/tutorials/how-to-use-atmos).
+    </Note>
+
+    <details>
+      <summary><strong>Example: What does account.yaml look like?</strong></summary>
+
+    The `stacks/catalog/account.yaml` file defines your AWS Organization structure. Here's a simplified example:
+
+    ```yaml
+    components:
+      terraform:
+        account:
+          vars:
+            account_email_format: aws+%[email protected]
+            account_iam_user_access_to_billing: "ALLOW"
+            organization_enabled: true
+
+            organizational_units:
+              - name: core
+                accounts:
+                  - name: core-identity
+                    tenant: core
+                    stage: identity
+                    tags:
+                      eks: false
+                  - name: core-security
+                    tenant: core
+                    stage: security
+                    tags:
+                      eks: false
+
+              - name: plat
+                accounts:
+                  - name: plat-dev
+                    tenant: plat
+                    stage: dev
+                    tags:
+                      eks: true
+                  - name: plat-staging
+                    tenant: plat
+                    stage: staging
+                    tags:
+                      eks: true
+                  - name: plat-prod
+                    tenant: plat
+                    stage: prod
+                    tags:
+                      eks: true
+    ```
+
+    **Key fields to customize:**
+    - `account_email_format`: Email pattern for new accounts (AWS requires unique emails per account)
+    - `organizational_units`: List of OUs and the accounts within them
+    - `name`: Account name (becomes the AWS account name)
+    - `tenant` and `stage`: Used for naming conventions
+    - `tags`: Metadata for organizational purposes
+
+    See the [aws-account component](https://github.com/cloudposse-terraform-components/aws-account) for all available configuration options.
+    </details>
   </Step>
 
   <Step>
     ## <StepNumber/> Deploy the AWS Organization
 
     <AtmosWorkflow workflow="deploy/organization" fileName="quickstart/foundation/accounts" />
 
+    <Note title="Organization Creation Methods">
+    The workflow above creates the AWS Organization automatically using Terraform. Alternatively, if you created the Organization manually in the AWS Console beforehand (to expedite quota increase requests), Terraform will detect the existing Organization and can import it to manage it as code going forward.
+    </Note>
+
   </Step>
 
   <Step>

docs/layers/accounts/prepare-aws-organization.mdx

@@ -6,9 +6,20 @@ sidebar_position: 2
 import Intro from '@site/src/components/Intro';
 import KeyPoints from '@site/src/components/KeyPoints';
 import Steps from '@site/src/components/Steps';
+import Note from '@site/src/components/Note';
 
 The Cold Start involves more manual steps than other layers. Read through the following steps and see [the detailed documentation](/layers/accounts/tutorials/manual-configuration/) for edge cases.
 
+<Note title="First Time Using Atmos?">
+This guide assumes familiarity with [Atmos](https://atmos.tools), our infrastructure orchestration tool. If you're new to Atmos:
+
+1. Review [How to Use Atmos](/learn/maintenance/tutorials/how-to-use-atmos) for basic commands
+2. Understand that Atmos uses YAML configuration files (called "stacks") to define infrastructure
+3. You don't need to be an Atmos expert—you can learn as you go by following the deployment steps
+
+The [Deploy Accounts guide](/layers/accounts/deploy-accounts/) includes configuration examples to help you understand what needs to be configured.
+</Note>
+
 In short, the steps are...
 
 | Steps                     | Actions                             |
@@ -31,6 +42,20 @@ Follow the [prerequisites steps in the How-to Get Started guide](/layers/project
 
 Start your Geodesic shell before continuing.
 
+:::caution Before You Begin
+
+**Before following this guide**, ensure you have:
+
+✅ **Purchased Quickstart or Jumpstart** - This guide references stack configurations (`stacks/catalog/account.yaml`) that are only provided with our paid packages
+
+✅ **Completed the kickoff call** - Your configurations will be customized to your design decisions
+
+✅ **Set up your infrastructure repository** - See [Create Repository](/layers/project/create-repository)
+
+**Looking for the configurations? [Start here](/intro/path)** - You'll get stuck at the "Check the configuration of the 'account' in the stack catalog" step because that file won't exist without them.
+
+:::
+
 
 ## Before Running Terraform (ClickOps)
 
@@ -58,10 +83,23 @@ From the root account:
 1. ### Enable Regions (Optional)
    The 17 original AWS regions are enabled by default. If you are using a region that is not enabled by default (such as Middle East/Bahrain), you need to take extra steps. For details, see [the detailed documentation](/layers/accounts/tutorials/manual-configuration/#optional-enable-regions)
 1. ### Prepare for Account Quota Increase
-   In order to deploy all accounts, you need to request an increase of the Account Quota from AWS support. This requires an AWS Organization to be created first, which we will create with Terraform in the [Deploy Accounts guide](/layers/accounts/deploy-accounts/#-prepare-account-deployment). This request can take a few days to process, so it's important to get it started early so that it doesn't become a blocker.
+   In order to deploy all accounts, you need to request an increase of the Account Quota from AWS support. This requires an AWS Organization to be created first, which we will create with Terraform in the [Deploy Accounts guide](/layers/accounts/deploy-accounts/#-prepare-account-deployment). **You can optionally create the Organization manually in the AWS Console first and then import it into Terraform, which allows you to submit the quota increase request earlier (see note below).** This request can take a few days to process, so it's important to get it started early so that it doesn't become a blocker.
 
    At this time we don't need to request the increase, but we should be prepared to do so as soon as the AWS Organization is created.
 
+   :::tip Manual Creation Option
+
+   Some teams prefer to create the Organization manually in the AWS Console first, then import it into Terraform afterward so it's fully managed as code. This approach allows you to submit the service quota request to increase the account limit right away, without needing to set up Terraform state and everything else first.
+
+   To do this:
+   1. Create the Organization manually in the AWS Console
+   2. Submit the quota increase request immediately (can take several days)
+   3. Set up Terraform/Atmos as described in the guides
+   4. Import the existing Organization into Terraform when deploying the `account` component
+
+   This helps keep things moving since quota requests in the reference architecture often exceed default limits and can take time to process.
+   :::
+
 </Steps>
 
 For more details, see

docs/layers/accounts/tutorials/manual-configuration.mdx

@@ -321,10 +321,11 @@ email address to access, update, or delete the account.
 Your AWS Organization is managed by the `account` component, along with accounts and organizational units.
 
 However, because the AWS defaults for an Organization and its accounts are not exactly what we want, and there is no way
-to change them via Terraform, we have to first provision the AWS Organization, then take some steps on the AWS console,
-and then we can provision the rest.
+to change them via Terraform, we have to first provision the AWS Organization **with Terraform**, then take some manual configuration steps in the AWS console (such as requesting quota increases and enabling AWS RAM), and then we can provision the member accounts.
 
-### Use AWS Console to create and set up the Organization
+### Configure Organization Settings via AWS Console
+
+The AWS Organization itself is created automatically by Terraform (see [Deploy Accounts guide](/layers/accounts/deploy-accounts/)). However, some post-creation configuration tasks must be done manually through the AWS console.
 
 Unfortunately, there are some tasks that need to be done via the console. Log into the AWS Console with the root (not
 SuperAdmin) credentials you have saved in 1Password.

docusaurus.config.js

@@ -246,7 +246,7 @@ async function createConfig() {
         announcementBar: {
           id: 'quickstart',
           content:
-            'Missing the <strong>Quickstart</strong> configurations? <a href="/intro/path/">Start here!</a>',
+            'Looking for the configurations? <a href="/intro/path/">Start here</a>',
           backgroundColor: 'var(--announcement-bar-background)',
           textColor: 'var(--announcement-bar-text-color)',
           isCloseable: true,

src/components/ActionCard/index.css

@@ -6,6 +6,7 @@
   border-radius: 1.3em;
   box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2);
   margin-top: 4em;
+  margin-bottom: 2em;
 }
 
 .action-card h2 {

src/css/admonitions.css

@@ -45,3 +45,7 @@ html[data-theme='dark'] .admonitionContent_node_modules-\@docusaurus-theme-class
   margin-right: 0.5em;
 }
 
+.theme-admonition > div p {
+  margin-right: 0.5em;
+}
+

src/css/custom.css

@@ -277,6 +277,24 @@ img.center {
   --ifm-h1-font-size: 2.5rem;
 }
 
+/* Restore list styles for markdown content (Tailwind-compatible) */
+@layer base {
+  .markdown ul,
+  article ul {
+    @apply list-disc pl-6 my-4;
+  }
+
+  .markdown ol,
+  article ol {
+    @apply list-decimal pl-6 my-4;
+  }
+
+  .markdown li,
+  article li {
+    @apply my-1;
+  }
+}
+
 .margin-top--md,
 .margin-vert--md {
   margin-top: 1rem !important;

src/theme/DocCard/styles.module.css

@@ -14,9 +14,10 @@
   margin-right: 0.5rem;
   line-height: 1.5rem;
   vertical-align: middle;
+  display: inline-flex;
+  align-items: center;
 }
 
-
 .cardContainer:hover {
   border-color: var(--ifm-color-primary);
   box-shadow: 0 3px 6px 0 rgb(0 0 0 / 20%);
@@ -28,6 +29,9 @@
 
 .cardTitle {
   font-size: 1.2rem;
+  display: flex;
+  align-items: center;
+  flex-wrap: nowrap;
 }
 
 .cardDescription {