Initial draft for revising getting started

src/content/docs/aws/getting-started/ai-workflows.mdx

@@ -0,0 +1,73 @@
+---
+title: AI & Agent Workflows
+description: Use LocalStack with AI coding assistants, MCP servers, and agent-driven infrastructure automation.
+template: doc
+sidebar:
+  order: 6
+---
+
+## Overview
+
+LocalStack is a natural fit for AI-assisted development workflows.
+Whether you're using an AI coding assistant to generate infrastructure code, running an agent that deploys AWS resources, or validating AI-generated Terraform before applying it to real AWS — LocalStack gives you a safe, fast, cost-free environment to do it in.
+
+## Connect an AI coding assistant via MCP
+
+The [LocalStack MCP Server](https://github.com/localstack/localstack-mcp-server) exposes LocalStack's API as an MCP (Model Context Protocol) tool server.
+This lets AI assistants like Claude, Cursor, Windsurf, or any MCP-compatible tool inspect and interact with your running LocalStack instance directly.
+
+With the MCP server connected, your AI assistant can:
+
+- List running AWS services and deployed resources
+- Create, update, and delete resources in your local environment
+- Query resource state to understand what's already deployed
+- Help you debug issues by inspecting live infrastructure
+
+**Quick setup:**
+
+```bash
+# Install the LocalStack MCP server
+pip install localstack-mcp-server
+```
+
+Then add it to your AI tool's MCP configuration.
+See the [localstack-mcp-server README](https://github.com/localstack/localstack-mcp-server) for tool-specific setup instructions for Claude, Cursor, and others.
+
+:::note
+The MCP server connects to a running LocalStack instance — make sure LocalStack is started first with `lstk start` or `localstack start`.
+:::
+
+## Deploy with agent-driven automation using Skills
+
+[LocalStack Skills](https://github.com/localstack/skills) are pre-built agent skill definitions for deploying common AWS architectures locally.
+Instead of stepping through manual CLI commands, you describe what you want and an agent handles the deployment.
+
+Skills are useful when:
+
+- You want to scaffold a new local environment quickly without writing all the infrastructure code yourself
+- You're using an agent-first workflow and want LocalStack to be a first-class deployment target
+- You want to iterate rapidly on architecture without touching real AWS
+
+Browse the [skills repository](https://github.com/localstack/skills) for available skills and setup instructions.
+
+## Validate AI-generated IaC before applying to AWS
+
+A common pattern when using AI to generate Terraform, CDK, or CloudFormation is to deploy it to LocalStack first.
+This catches configuration errors, missing permissions, and service interaction bugs before you spend time (and money) deploying to real AWS.
+
+The workflow is:
+
+1. Generate infrastructure code with your AI tool
+2. Deploy to LocalStack with `tflocal apply` (Terraform), `cdklocal deploy` (CDK), or the AWS CLI
+3. Run your integration tests against the local environment
+4. When everything passes, deploy to real AWS with confidence
+
+See [Tooling](/aws/tooling/) for the full list of LocalStack-aware wrappers for common IaC tools.
+
+## Summary
+
+| Use case | Tool |
+|---|---|
+| AI assistant that can inspect & manage local resources | [LocalStack MCP Server](https://github.com/localstack/localstack-mcp-server) |
+| Agent-driven infrastructure deployment | [LocalStack Skills](https://github.com/localstack/skills) |
+| Validate AI-generated IaC safely | LocalStack + `tflocal` / `cdklocal` / `awslocal` |

src/content/docs/aws/getting-started/auth-token.mdx

@@ -3,7 +3,7 @@ title: Auth Token
 description: Configure your Auth Token to access and activate LocalStack.
 template: doc
 sidebar:
-  order: 3
+  order: 4
 ---
 
 import { Code, Tabs, TabItem } from '@astrojs/starlight/components';

src/content/docs/aws/getting-started/ci-cd.mdx

@@ -0,0 +1,185 @@
+---
+title: CI/CD Setup
+description: Run LocalStack in CI pipelines — auth tokens, Docker Compose, and GitHub Actions examples.
+template: doc
+sidebar:
+  order: 5
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+## Overview
+
+LocalStack works great in CI environments.
+The setup differs from local development in a few important ways:
+
+- **Use a CI Auth Token**, not your personal Developer token
+- **Manage the container directly** via Docker Compose or `docker run` — `lstk` and the LocalStack Desktop are local-only tools
+- **LocalStack is ephemeral by default** — each CI run starts fresh, which is usually exactly what you want for reproducible tests
+
+## Step 1 — Get a CI Auth Token
+
+CI pipelines should use a dedicated CI Auth Token, not a Developer token tied to a specific user.
+
+1. Go to the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application
+2. Create a new **CI Auth Token**
+3. Add it as a secret in your CI provider (e.g., `LOCALSTACK_AUTH_TOKEN`)
+
+:::danger[Keep your token secret]
+Never commit an auth token to source control.
+Always inject it via your CI provider's secrets or environment variable mechanism.
+If a token is compromised, rotate it immediately on the Auth Tokens page — old tokens are invalidated instantly.
+:::
+
+See the [Auth Token documentation](/aws/getting-started/auth-token/) for full details on token types and configuration.
+
+## Step 2 — Start LocalStack in CI
+
+<Tabs>
+  <TabItem label="GitHub Actions">
+    The recommended approach is to start LocalStack as a service container or as a step using the official GitHub Action:
+
+    ```yaml
+    # .github/workflows/integration-tests.yml
+    name: Integration Tests
+
+    on: [push, pull_request]
+
+    jobs:
+      test:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+
+          - name: Start LocalStack
+            uses: LocalStack/setup-localstack@v0.2
+            with:
+              image-tag: latest
+            env:
+              LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }}
+
+          - name: Run tests
+            run: |
+              # Your test commands here, e.g.:
+              pip install awscli-local
+              awslocal s3 mb s3://my-test-bucket
+              pytest tests/integration/
+    ```
+
+    The `setup-localstack` action handles pulling the image, starting the container, and waiting for LocalStack to be ready.
+  </TabItem>
+  <TabItem label="Docker Compose">
+    Add LocalStack as a service in your `docker-compose.yml`:
+
+    ```yaml
+    services:
+      localstack:
+        container_name: localstack-main
+        image: localstack/localstack-pro
+        ports:
+          - "127.0.0.1:4566:4566"
+          - "127.0.0.1:4510-4559:4510-4559"
+          - "127.0.0.1:443:443"
+        environment:
+          - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
+          - DEBUG=${DEBUG:-0}
+        volumes:
+          - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
+          - "/var/run/docker.sock:/var/run/docker.sock"
+    ```
+
+    Start it and wait for readiness:
+
+    ```bash
+    docker compose up -d localstack
+    # Wait for LocalStack to be ready
+    until curl -s http://localhost:4566/_localstack/health | grep -q '"running"'; do sleep 1; done
+    ```
+
+    :::note
+    Mounting `/var/run/docker.sock` is required for Lambda emulation, which uses Docker to run function containers.
+    :::
+  </TabItem>
+  <TabItem label="Docker">
+    Start LocalStack directly with `docker run`:
+
+    ```bash
+    docker run \
+      --rm -d \
+      --name localstack-main \
+      -p 127.0.0.1:4566:4566 \
+      -p 127.0.0.1:4510-4559:4510-4559 \
+      -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
+      -v /var/run/docker.sock:/var/run/docker.sock \
+      localstack/localstack-pro
+
+    # Wait for readiness
+    until curl -s http://localhost:4566/_localstack/health | grep -q '"running"'; do sleep 1; done
+    ```
+  </TabItem>
+  <TabItem label="CircleCI">
+    Add LocalStack as a service in your CircleCI config:
+
+    ```yaml
+    version: 2.1
+
+    jobs:
+      integration-tests:
+        docker:
+          - image: cimg/python:3.12
+          - image: localstack/localstack-pro
+            environment:
+              LOCALSTACK_AUTH_TOKEN: $LOCALSTACK_AUTH_TOKEN
+        steps:
+          - checkout
+          - run:
+              name: Wait for LocalStack
+              command: |
+                until curl -s http://localhost:4566/_localstack/health | grep -q '"running"'; do sleep 1; done
+          - run:
+              name: Run tests
+              command: pytest tests/integration/
+    ```
+
+    Set `LOCALSTACK_AUTH_TOKEN` in your CircleCI project's environment variables.
+  </TabItem>
+</Tabs>
+
+## Verify activation
+
+After LocalStack starts, confirm the license is active:
+
+```bash
+curl -s http://localhost:4566/_localstack/info | jq '.is_license_activated'
+# Should return: true
+```
+
+## Key differences from local development
+
+| | Local development | CI/CD |
+|---|---|---|
+| **CLI** | `lstk` or LocalStack CLI | Docker Compose / `docker run` |
+| **Auth** | Browser login or stored token | `LOCALSTACK_AUTH_TOKEN` env var |
+| **Token type** | Developer token | CI token |
+| **State** | Optional persistence | Ephemeral (fresh per run) |
+| **Startup** | Interactive TUI | `--non-interactive` / `-d` flag |
+
+## Persisting state across runs
+
+By default, LocalStack starts fresh on every run — all resources are gone when the container stops.
+This is ideal for most CI use cases (clean, reproducible tests).
+
+If you need to share state across runs (e.g., seed data, pre-built infrastructure), look at [Cloud Pods](/aws/capabilities/state-management/cloud-pods/), which let you snapshot and restore LocalStack state.
+
+## More CI integrations
+
+LocalStack has dedicated integration guides for many CI providers:
+
+- [GitHub Actions](/aws/integrations/continuous-integration/github-actions/)
+- [GitLab CI](/aws/integrations/continuous-integration/gitlab-ci/)
+- [CircleCI](/aws/integrations/continuous-integration/circleci/)
+- [AWS CodeBuild](/aws/integrations/continuous-integration/codebuild/)
+- [Travis CI](/aws/integrations/continuous-integration/travis-ci/)
+- [Bitbucket Pipelines](/aws/integrations/continuous-integration/bitbucket/)
+
+See the full [CI/CD integrations](/aws/integrations/continuous-integration/) section for details.

src/content/docs/aws/getting-started/faq.mdx

@@ -3,7 +3,7 @@ title: FAQ
 description: Frequently asked questions about LocalStack for AWS.
 template: doc
 sidebar:
-  order: 5
+  order: 7
 ---
 
 import { Tabs, TabItem } from '@astrojs/starlight/components';

src/content/docs/aws/getting-started/help-support.md

@@ -3,7 +3,7 @@ title: Help & Support
 description: Get help and support with LocalStack.
 template: doc
 sidebar:
-  order: 6
+  order: 8
 ---
 
 ## Introduction

src/content/docs/aws/getting-started/index.mdx

@@ -0,0 +1,48 @@
+---
+title: Overview
+description: This section describes how to get started with LocalStack for AWS using a variety of options, and provides details on how LocalStack can be configured to fit the needs of a local cloud sandbox for development, testing, and experimentation.
+template: doc
+editUrl: false
+sidebar:
+  order: 1
+---
+
+import { SectionCards } from '../../../../components/SectionCards.tsx';
+
+[LocalStack for AWS](https://localstack.cloud) is a cloud service emulator that runs in a single container on your laptop or in your CI environment.
+It gives you a fully functional AWS environment — Lambda, DynamoDB, S3, SQS, and [80+ more services](/aws/services/) — without touching a real AWS account and without incurring cloud costs.
+
+Here's why developers and teams use it:
+
+- **Faster development loops** — Test changes against local AWS services instantly, without waiting on real deployments or worrying about cloud costs.
+- **Integration testing in CI** — Run real integration tests against local AWS infrastructure in every pull request, catching bugs before they reach production.
+- **Validate IaC before applying** — Deploy your Terraform, CDK, or CloudFormation to LocalStack first. Confirm it works the way you expect before applying to a real AWS environment.
+- **Safe experimentation** — Explore new AWS services and architectures freely, with no risk to production systems.
+
+LocalStack for AWS also includes advanced capabilities for teams: [Cloud Pods](/aws/capabilities/state-management/cloud-pods/) for sharing and restoring state, [IAM policy enforcement](/aws/capabilities/security-testing/iam-policy-enforcement/), [Chaos Engineering](/aws/capabilities/chaos-engineering/), and more.
+
+## Choose your path
+
+<SectionCards
+  sections={[
+    {
+      title: 'Local Development',
+      description:
+        'Set up LocalStack on your laptop and get a serverless app running in under 10 minutes. Deploy Lambda functions, DynamoDB tables, and more — no AWS account needed.',
+      href: '/aws/getting-started/quickstart/',
+    },
+    {
+      title: 'CI/CD Pipelines',
+      description:
+        'Run LocalStack in GitHub Actions, CircleCI, or any container-based CI. Catch infrastructure bugs before they reach production with real integration tests on every pull request.',
+      href: '/aws/getting-started/ci-cd/',
+    },
+    {
+      title: 'AI & Agent Workflows',
+      description:
+        'Connect LocalStack to your AI coding assistant via the MCP server, or deploy infrastructure automatically using LocalStack Skills.',
+      href: '/aws/getting-started/ai-workflows/',
+    },
+  ]}
+  client:load
+/>