Initial draft for revising getting started

src/components/SecondaryPathCard.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+
+interface SecondaryPathCardProps {
+  title: string;
+  href: string;
+  children: React.ReactNode;
+}
+
+export const SecondaryPathCard: React.FC<SecondaryPathCardProps> = ({ title, href, children }) => {
+  return (
+    <div className="path-secondary-card">
+      <a href={href} className="service-box">
+        <div className="service-box-content">
+          <h3 className="service-box-title path-secondary-card__title">{title}</h3>
+          <div className="service-box-description path-secondary-card__body">{children}</div>
+        </div>
+      </a>
+    </div>
+  );
+};

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

@@ -0,0 +1,95 @@
+---
+title: AI & Agent Workflows
+description: Use LocalStack with AI coding assistants, MCP servers, and agent-driven infrastructure automation.
+template: doc
+sidebar:
+  order: 5
+---
+
+## Overview
+
+AI-assisted development workflows need a fast and secure environment to develop and test in.
+Whether you're using an AI coding assistant to generate infrastructure code, running an agent that deploys AWS resources, or validating AI-generated IaC before applying it to real AWS — LocalStack gives you a safe, fast, cost-free environment to run these workflows in.
+
+## Connect an AI coding assistant via MCP
+
+The [LocalStack MCP Server](https://github.com/localstack/localstack-mcp-server) is a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that connects compatible clients (Claude, Cursor, Windsurf, and others) to your LocalStack environment.
+It gives agents tools to run the full local cloud lifecycle—not only generating infrastructure code, but starting the container, deploying and tearing down IaC, analyzing logs, and more.
+See [Introducing the LocalStack MCP Server](https://blog.localstack.cloud/introducing-localstack-mcp-server/) for the original announcement and walkthrough.
+
+With the MCP server configured, your assistant can use tools such as:
+
+- **Lifecycle** — Start, stop, restart, or check status of the LocalStack container
+- **Deploy** — Deploy or destroy CDK, Terraform, SAM, or CloudFormation projects on LocalStack
+- **Operations** — Analyze logs, run AWS CLI commands via `awslocal`, manage [Cloud Pods](/aws/capabilities/state-management/cloud-pods/), and (where supported) IAM policy analysis, chaos injection, and docs search
+
+...and many more.
+
+### MCP Server Prerequisites
+
+Before you begin, make sure these are installed and in your system's `PATH`:
+
+- [Node.js](https://nodejs.org/en/) (v20.x or later) to run the `npx` command.
+- [LocalStack CLI](https://docs.localstack.cloud/user-guide/cli/) and [Docker](https://docs.docker.com/get-docker/) to manage the LocalStack container itself.
+- [`cdklocal`](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) or [`tflocal`](https://docs.localstack.cloud/user-guide/integrations/terraform/) to use the `localstack-deployer` tool. (optional)
+- A [LocalStack Auth Token](https://docs.localstack.cloud/getting-started/auth-token/) to enable licensed features. (optional)
+
+### MCP Server Configuration
+
+Add a server entry like this to your client's MCP configuration—for **Cursor**, this would typically be `~/.cursor/mcp.json`.
+For **Claude Code**, register the server with `claude mcp add` (it is saved to your project-level MCP configuration).
+
+```json
+{
+  "mcpServers": {
+    "localstack-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@localstack/localstack-mcp-server"],
+      "env": {
+        "LOCALSTACK_AUTH_TOKEN": "<YOUR_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+Full prerequisites, Cursor/VS Code/Claude Code variants, custom endpoints (`LOCALSTACK_HOSTNAME`, `LOCALSTACK_PORT`), troubleshooting, and the complete tool reference are on [LocalStack MCP Server](/aws/tooling/mcp-server/).
+
+:::note
+You do not need to start LocalStack manually before using MCP: an agent can start the container using the **localstack-management** tool once this configuration is in place.
+If LocalStack already runs elsewhere, point the MCP server at it via the `env` block as described in [Connecting to a custom LocalStack endpoint](/aws/tooling/mcp-server/#connecting-to-a-custom-localstack-endpoint).
+:::
+
+## 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. It contains skills for LocalStack lifecycle management, IaC deployment, state management and more. Skills can be used in combination with the MCP server to create a fully autonomous agent-driven workflow.
+
+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](/aws/tooling/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,17 +3,23 @@ title: Auth Token
 description: Configure your Auth Token to access and activate LocalStack.
 template: doc
 sidebar:
-  order: 3
+  order: 6
 ---
 
 import { Code, Tabs, TabItem } from '@astrojs/starlight/components';
 
 ## Introduction
 
-The Auth Token is required to activate the LocalStack for AWS core cloud emulator. It identifies and authenticates users outside the LocalStack Web Application.
-It primarily accesses your workspace and advanced services & features.
+The Auth Token activates LocalStack for AWS. It ties the running instance to your workspace and license and is required whenever you use LocalStack for AWS.
 
-Auth tokens come in two types: a **Developer Auth Token** and a **CI Auth Token**:
+**Whether you need to configure a token by hand** depends on how you run LocalStack:
+
+- **[`lstk`](/aws/tooling/lstk)** (early release) — For most local development, the Auth Token is present but easy to overlook. On first run or after `lstk login`, the CLI completes a browser login flow, stores your **Developer Auth Token** in the system keyring (or a config-directory fallback when no keyring is available), and injects it into the container whenever you start LocalStack. You are still using an Auth Token for activation; `lstk` obtains and reuses it after login instead of asking you to set `LOCALSTACK_AUTH_TOKEN` yourself.
+- **LocalStack CLI (`localstack`)** — You configure the token yourself: set `LOCALSTACK_AUTH_TOKEN` or run `localstack auth set-token` (see [Configuring your Auth Token](#configuring-your-auth-token)). [`lstk`](/aws/tooling/lstk) is currently in early release and missing some core features, so the `localstack` CLI is still the right tool for Cloud Pods, Extensions, Ephemeral Instances, and other advanced features, so many workflows keep using it and therefore set an Auth Token explicitly. For personal development, use your **Developer Auth Token** from the web app.
+- **Docker or Docker Compose** — You pass `LOCALSTACK_AUTH_TOKEN` into the container (see [Configuring your Auth Token](#configuring-your-auth-token)). Use your **Developer Auth Token** for local runs unless you are in CI.
+- **CI pipelines and other automated, non-interactive environments** — You must set `LOCALSTACK_AUTH_TOKEN` to a **CI Auth Token**. Developer Auth Tokens should not be used in CI. See [CI Environments](#ci-environments).
+
+Auth tokens come in two types: a **Developer Auth Token** and a **CI Auth Token**.
 
 - The **Developer Auth Token** is linked to a specific user within a specific workspace.
   Every user has their own Auth Token.
@@ -205,25 +211,6 @@ Another way to confirm this is by checking the logs of the LocalStack container
 
 Otherwise, check our [troubleshooting](#troubleshooting) section.
 
-## FAQ
-
-### How do I activate older versions of LocalStack (Before v3.0)?
-
-Prior to the introduction of Auth Tokens, LocalStack used **API keys** managed through the `LOCALSTACK_API_KEY` environment variable for activation.
-
-For backwards compatibility, we've updated our back-end to accept new Auth Tokens within the `LOCALSTACK_API_KEY` variable.
-You can use the new Auth Token in the same way you previously used the API key.
-
-### When will the legacy API keys be phased out?
-
-In early 2025, we will begin phasing out legacy API keys entirely.
-After the sunsetting period, legacy API and legacy CI keys will no longer activate or work with LocalStack.
-
-During the sunsetting period, the legacy service will experience scheduled downtimes.
-These are planned to encourage users to transition to new Auth Tokens while minimizing impact for those who have not yet updated.
-
-The downtime schedule will be communicated well in advance, allowing users ample time to switch to the new Auth Tokens.
-
 ## Troubleshooting
 
 While using Auth Tokens, LocalStack demands a successful license activation for startup.

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

@@ -0,0 +1,195 @@
+---
+title: CI/CD
+description: Run LocalStack in CI pipelines — auth tokens, Docker Compose, GitHub Actions examples, and persisting state with Cloud Pods or state export.
+template: doc
+sidebar:
+  order: 4
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+## Overview
+
+LocalStack works great in CI environments, allowing your integration tests to run incredibly fast and with no cloud costs.
+The setup differs slighty from local development in a few important ways:
+
+- **Use a CI Auth Token**, not your personal Developer token
+- **Start LocalStack without a browser** — Docker Compose, `docker run`, or CI helpers such as [`setup-localstack`](https://github.com/localstack/setup-localstack) are common; [`lstk`](/aws/tooling/lstk/) also works in CI when you set `LOCALSTACK_AUTH_TOKEN` and use [`--non-interactive`](/aws/tooling/lstk/#interactive-and-non-interactive-mode) (or rely on automatic non-interactive detection). LocalStack Desktop remains a local-only GUI.
+- **Runs are often isolated per job** — many pipelines start from an empty LocalStack instance for reproducible tests
+- **Persistence in CI is supported** — [Cloud Pods](/aws/capabilities/state-management/cloud-pods/), snapshot-based [persistence](/aws/capabilities/state-management/persistence/) with a mounted volume, or `localstack state export` / `localstack state import` with artifacts or cache.
+
+## 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.2
+            with:
+              image-tag: latest
+              install-awslocal: "true"
+            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`, or `lstk --non-interactive`                          |
+| **Auth**       | Browser login or stored token    | `LOCALSTACK_AUTH_TOKEN` env var                                                     |
+| **Token type** | Developer token                  | CI token                                                                            |
+| **State**      | Optional persistence             | Optional persistence (same mechanisms; typical pattern is a fresh instance per job) |
+| **Startup**    | Interactive TUI (default `lstk`) | Non-interactive (`docker compose`, `docker run -d`, `lstk --non-interactive`)       |
+
+## Persisting state across runs
+
+If you tear down the container at the end of a job, nothing is left on disk unless you save it — which is why many teams use a clean instance every time.
+When you **do** need to reuse infrastructure or data between pipeline runs or steps, CI is fully supported:
+
+- **[Cloud Pods](/aws/capabilities/state-management/cloud-pods/)** — save and load snapshots; the [`setup-localstack`](https://github.com/localstack/setup-localstack) action can load and save pods via `state-backend: cloud-pods` (see [GitHub Actions](/aws/integrations/continuous-integration/github-actions/) — _Store Localstack state_).
+- **Snapshot-based [persistence](/aws/capabilities/state-management/persistence/)** — enable `PERSISTENCE=1` and mount a volume so state survives container restarts on the same runner or workspace.
+- **State export/import** — run `localstack state export` and `localstack state import` and pass the file through your CI provider’s **artifacts**, **cache**, or attached storage (for example, see [GitLab CI](/aws/integrations/continuous-integration/gitlab-ci/) — _Store Localstack state_).
+
+Choose the approach that fits your runner model: for example, multi-job GitLab pipelines often need explicit state handoff because services do not carry between jobs.
+
+## 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';