From c7819499436d8535777145dbef73f926c1f7b031 Mon Sep 17 00:00:00 2001
From: Brian Rinaldi <brian.rinaldi@gmail.com>
Date: Tue, 1 Sep 2026 16:40:31 -0400
Subject: [PATCH] Migrate skills from legacy localstack CLI to lstk

Replace the localstack CLI + awslocal/tflocal/cdklocal wrapper combination
with the lstk CLI across all six skills and the README.

Behavioral change reviewers must not miss:

  lstk only forwards host env vars prefixed with LOCALSTACK_. Every bare
  `DEBUG=1 localstack start -d` in the old skills would silently do nothing
  under lstk. All are now `LOCALSTACK_DEBUG=1 lstk start`. Note the inverse
  trap: keys inside a config.toml [env.*] profile take NO prefix. Also,
  `lstk start` already backgrounds -- there is no -d flag.

Command mappings applied:

  localstack start/stop/status/logs   -> lstk start/stop/status/logs
  PERSISTENCE=1                       -> lstk start --persist
  awslocal <cmd>                      -> lstk aws <cmd>
  tflocal                             -> lstk terraform (--region/--account
                                         go before the subcommand)
  cdklocal                            -> lstk cdk (requires CDK >= 2.177.0)
  (new)                               -> lstk sam (requires SAM >= 1.95.0)
  localstack state export/import      -> lstk save / lstk load
  localstack pod save/load            -> lstk save pod: / lstk load pod:

Gaps where lstk is NOT usable, each documented in-skill and in a new
README "Optional extra CLIs" table:

  - Extensions: no `lstk extensions` command suite exists. This is worse
    than it first appears. `lstk volume path` resolves to
    ~/Library/Caches/lstk/volume/localstack-aws, a DIFFERENT directory from
    the legacy ~/Library/Caches/localstack that extensions install into, so
    an emulator started by lstk will not load installed extensions at all.
    The extensions skill therefore stays on the legacy CLI end to end, and
    warns that the two CLIs conflict on port 4566.
  - Pulumi: no lstk proxy command. pulumilocal is still required.
  - SAM: `lstk sam` does not support image/container-based Lambda (ECR)
    deploys or nested CloudFormation stacks. samlocal is still required.
  - IAM policy generation: `localstack aws iam stream` / `summary` have no
    lstk equivalent. The IAM skill keeps them as the recommended path and
    falls back to `lstk logs -v` grepping only when the legacy CLI is absent.

Two further points of potential confusion for reviewers:

  - lstk always pulls localstack/localstack-pro and requires a license. The
    old state-management skill advertised "Pro required: No" for local
    snapshots; that column is now wrong and has been removed, with a note
    that the license applies regardless of snapshot backend.
  - `lstk logs` filters output by default, unlike `localstack logs`. Every
    place a skill greps for a specific line now uses `lstk logs -v`.

Legacy `localstack` references that remain in the tree are intentional:
the extensions skill, the IAM stream/summary workflow, and migration notes.

Command surface was verified against the locally installed lstk binary's
--help output, not the published docs alone.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                             |  37 ++++-
 skills/iac-deployment/SKILL.md        | 119 ++++++++++-----
 skills/iam-policy-analyzer/SKILL.md   |  74 +++++++---
 skills/localstack-extensions/SKILL.md |  40 +++--
 skills/localstack-lifecycle/SKILL.md  | 186 +++++++++++++++++++-----
 skills/logs-analysis/SKILL.md         |  96 ++++++++----
 skills/state-management/SKILL.md      | 201 ++++++++++++++++++--------
 7 files changed, 553 insertions(+), 200 deletions(-)

diff --git a/README.md b/README.md
index 15b4257..4761810 100644
--- a/README.md
+++ b/README.md
@@ -10,12 +10,12 @@ This repository contains a collection of AI skills designed to help developers w
 
 | Skill | Description |
 |-------|-------------|
-| [localstack-lifecycle](skills/localstack-lifecycle/) | Manage LocalStack container lifecycle (start, stop, status, restart) |
-| [iac-deployment](skills/iac-deployment/) | Deploy infrastructure using Terraform, CDK, CloudFormation, and Pulumi |
-| [state-management](skills/state-management/) | Save, load, and manage LocalStack state with Cloud Pods |
+| [localstack-lifecycle](skills/localstack-lifecycle/) | Manage the emulator lifecycle with `lstk` (start, stop, status, restart, reset) |
+| [iac-deployment](skills/iac-deployment/) | Deploy infrastructure using Terraform, CDK, CloudFormation, SAM, and Pulumi |
+| [state-management](skills/state-management/) | Save, load, and manage LocalStack state with snapshots and Cloud Pods |
 | [logs-analysis](skills/logs-analysis/) | Analyze LocalStack logs, identify errors, and debug issues |
 | [iam-policy-analyzer](skills/iam-policy-analyzer/) | Analyze IAM policies and auto-generate least-privilege permissions |
-| [localstack-extensions](skills/localstack-extensions/) | Manage LocalStack extensions and plugins |
+| [localstack-extensions](skills/localstack-extensions/) | Manage LocalStack extensions and plugins (legacy CLI) |
 
 ## Installation
 
@@ -28,9 +28,34 @@ claude plugin install localstack@localstack-dev
 
 ## Prerequisites
 
-- [LocalStack](https://docs.localstack.cloud/getting-started/installation/) installed and configured
-- [AWS CLI](https://aws.amazon.com/cli/) or [awslocal](https://docs.localstack.cloud/user-guide/integrations/aws-cli/#localstack-aws-cli-awslocal) wrapper
 - Docker running on your machine
+- A [LocalStack account](https://app.localstack.cloud/) and auth token
+- The [`lstk` CLI](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/), the current LocalStack CLI:
+
+  ```bash
+  # Homebrew (macOS/Linux)
+  brew install localstack/tap/lstk
+
+  # npm
+  npm install -g @localstack/lstk
+
+  # Authenticate
+  lstk login
+  ```
+
+- The tools you want `lstk` to proxy, on your `PATH`: [AWS CLI](https://aws.amazon.com/cli/), `terraform`, `cdk`, or `sam`. `lstk aws`, `lstk terraform`, `lstk cdk`, and `lstk sam` point them at LocalStack for you, replacing the `awslocal`, `tflocal`, `cdklocal`, and `samlocal` wrappers.
+
+### Optional extra CLIs
+
+The `lstk` CLI does not cover every workflow yet. Install these only if you need them:
+
+| Tool | Install | Needed for |
+|------|---------|-----------|
+| `pulumilocal` | `pip install pulumi-local` | Pulumi deployments — `lstk` has no Pulumi proxy |
+| `samlocal` | `pip install aws-sam-cli-local` | Image/container-based Lambda (ECR) deploys and nested CloudFormation stacks, which `lstk sam` does not support |
+| legacy `localstack` CLI | `pip install localstack` | LocalStack Extensions, and the `localstack aws iam stream` / `summary` policy generators |
+
+The legacy `localstack` CLI is deprecated and will be removed in a future version — use it only for the gaps listed above. It manages its own container, so stop one CLI's emulator before starting the other's.
 
 ## Usage
 
diff --git a/skills/iac-deployment/SKILL.md b/skills/iac-deployment/SKILL.md
index a0ce91a..fcce781 100644
--- a/skills/iac-deployment/SKILL.md
+++ b/skills/iac-deployment/SKILL.md
@@ -1,40 +1,63 @@
 ---
 name: localstack-deploy
-description: Deploy infrastructure to LocalStack using IaC tools. Use when users want to deploy Terraform, CDK, CloudFormation, or Pulumi to LocalStack, or need help configuring tflocal, cdklocal, pulumilocal, or awslocal wrappers.
+description: Deploy infrastructure to LocalStack using IaC tools. Use when users want to deploy Terraform, CDK, CloudFormation, SAM, or Pulumi to LocalStack, or need help with the lstk proxy commands (lstk terraform, lstk cdk, lstk sam, lstk aws) or the pulumilocal wrapper.
 ---
 
 # Infrastructure as Code Deployment
 
-Deploy AWS infrastructure to LocalStack using popular IaC tools including Terraform, AWS CDK, CloudFormation, and Pulumi.
+Deploy AWS infrastructure to LocalStack using popular IaC tools including Terraform, AWS CDK, CloudFormation, SAM, and Pulumi.
 
 ## Capabilities
 
 - Deploy Terraform configurations to LocalStack
 - Run AWS CDK deployments locally
 - Deploy CloudFormation stacks
+- Build and deploy AWS SAM applications
 - Execute Pulumi programs against LocalStack
 - Validate infrastructure before deployment
 
+## Prerequisites
+
+- The `lstk` CLI installed and the emulator running (`lstk start`) — see the `localstack` skill
+- The underlying tool on your `PATH`: `terraform`, `cdk`, `sam`, or `aws`. `lstk` proxies them; it does not bundle them.
+
+`lstk` replaces the old `awslocal` / `tflocal` / `cdklocal` / `samlocal` wrappers — you no longer need to `pip install`/`npm install` them. Pulumi is the exception; see [Pulumi](#pulumi).
+
 ## Terraform
 
-### Using tflocal (Preferred)
+### Using `lstk terraform` (Preferred)
+
+`lstk terraform` (alias `lstk tf`) runs Terraform against LocalStack by generating a provider-override file, so your `.tf` files need no LocalStack-specific changes.
+
+```bash
+lstk terraform init
+lstk terraform plan
+lstk terraform apply -auto-approve
+lstk terraform destroy -auto-approve
+
+# Short alias
+lstk tf apply -auto-approve
+```
 
-The `tflocal` wrapper is the preferred way to deploy Terraform configurations to LocalStack. It automatically configures all AWS provider endpoints to point to LocalStack, requiring no changes to your Terraform files.
+`lstk`-specific flags go **before** the Terraform subcommand:
 
 ```bash
-# Install tflocal wrapper
-pip install terraform-local
-
-# Use tflocal instead of terraform - no provider changes needed
-tflocal init
-tflocal plan
-tflocal apply -auto-approve
-tflocal destroy -auto-approve
+lstk terraform --region us-west-2 plan
+lstk terraform --account 000000000000 apply
 ```
 
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--region <region>` | `us-east-1` | Falls back to `AWS_REGION` |
+| `--account <id>` | `test` | 12 digits; falls back to `AWS_ACCESS_KEY_ID` |
+
+Useful environment variables: `AWS_ENDPOINT_URL`, `LSTK_TF_CMD` (binary name, default `terraform`), `LSTK_TF_OVERRIDE_FILE_NAME` (default `localstack_providers_override.tf`), `LSTK_TF_DRY_RUN`.
+
+`lstk terraform` targets the AWS emulator only.
+
 ### Manual Provider Configuration (Fallback)
 
-Only use manual provider configuration if `tflocal` cannot be installed (e.g., Python/pip is not available in the environment). This approach requires modifying your Terraform files:
+Only use manual provider configuration if `lstk` cannot be used (for example, a CI image that only has `terraform`). This approach requires modifying your Terraform files:
 
 ```hcl
 # In your provider configuration:
@@ -60,59 +83,76 @@ Note: When using manual configuration, you must list endpoints for each AWS serv
 
 ## AWS CDK
 
-### Setup
+Requires AWS CDK CLI `2.177.0` or newer.
 
 ```bash
-# Install cdklocal wrapper
-npm install -g aws-cdk-local aws-cdk
-
 # Bootstrap (first time only)
-cdklocal bootstrap
-```
-
-### Deploy
+lstk cdk bootstrap
 
-```bash
 # Deploy all stacks
-cdklocal deploy --all --require-approval never
+lstk cdk deploy --all --require-approval never
+
+# Deploy a specific stack
+lstk cdk deploy MyStack
 
-# Deploy specific stack
-cdklocal deploy MyStack
+# Synthesize
+lstk cdk synth
 
 # Destroy
-cdklocal destroy --all --force
+lstk cdk destroy --all --force
 ```
 
+`lstk cdk` accepts `--region <region>` (default `us-east-1`) before the CDK command. There is no `--account` flag — CDK always targets the default account `000000000000`.
+
+Useful environment variables: `AWS_ENDPOINT_URL`, `AWS_ENDPOINT_URL_S3`, `LSTK_CDK_CMD` (default `cdk`), `AWS_REGION`.
+
 ## CloudFormation
 
-### Deploy with awslocal
+Use `lstk aws`, which proxies the host `aws` CLI with the endpoint, credentials, and region pre-configured.
 
 ```bash
 # Create stack
-awslocal cloudformation create-stack \
+lstk aws cloudformation create-stack \
   --stack-name my-stack \
   --template-body file://template.yaml
 
 # Update stack
-awslocal cloudformation update-stack \
+lstk aws cloudformation update-stack \
   --stack-name my-stack \
   --template-body file://template.yaml
 
 # Delete stack
-awslocal cloudformation delete-stack --stack-name my-stack
+lstk aws cloudformation delete-stack --stack-name my-stack
 
 # Describe stack
-awslocal cloudformation describe-stacks --stack-name my-stack
+lstk aws cloudformation describe-stacks --stack-name my-stack
+```
+
+If you would rather use the plain `aws` CLI, run `lstk setup aws` once to write a `localstack` profile into `~/.aws/config` and `~/.aws/credentials`, then use `aws --profile localstack ...`.
+
+## AWS SAM
+
+Requires AWS SAM CLI `1.95.0` or newer.
+
+```bash
+lstk sam build
+lstk sam validate
+lstk sam deploy
+lstk sam --region us-west-2 deploy
 ```
 
+`lstk sam` accepts `--region <region>` (default `us-east-1`) and `--account <id>` (default `000000000000`) before the SAM command.
+
+**Limitation:** image/container-based Lambda (ECR) deploys and nested CloudFormation stacks are not supported by `lstk sam`. For those workflows, install the `samlocal` wrapper (`pip install aws-sam-cli-local`) and use it instead.
+
 ## Pulumi
 
-### Using pulumilocal (Preferred)
+`lstk` has no Pulumi proxy command, so Pulumi still needs the `pulumilocal` wrapper.
 
-The `pulumilocal` wrapper is the preferred way to deploy Pulumi programs to LocalStack. It automatically configures AWS endpoints, requiring no changes to your Pulumi configuration.
+### Using `pulumilocal` (Preferred)
 
 ```bash
-# Install pulumilocal wrapper
+# Requires Python/pip — this is an extra install beyond lstk
 pip install pulumi-local
 
 # Use pulumilocal instead of pulumi - no config changes needed
@@ -140,9 +180,14 @@ pulumi up --yes
 pulumi destroy --yes
 ```
 
+## Endpoint Resolution
+
+`lstk aws`, `lstk terraform`, `lstk cdk`, and `lstk sam` probe whether `localhost.localstack.cloud` resolves to `127.0.0.1` and use it when it does; otherwise they fall back to `127.0.0.1:4566`. Override with the `LOCALSTACK_HOST` environment variable.
+
 ## Best Practices
 
-- Use wrapper tools (`tflocal`, `cdklocal`, `awslocal`) for simplified configuration
+- Use the `lstk` proxy commands (`lstk terraform`, `lstk cdk`, `lstk sam`, `lstk aws`) rather than editing endpoints into your IaC files
 - Test infrastructure changes locally before deploying to AWS
-- Use `PERSISTENCE=1` to retain state across LocalStack restarts
-- Leverage Cloud Pods to save/restore infrastructure state
+- Use `lstk start --persist` to retain state across LocalStack restarts
+- Snapshot deployed infrastructure with `lstk save` so you can restore it instantly instead of re-deploying — see the `localstack-state` skill
+- In CI, add `--non-interactive` to `lstk` commands and set `LOCALSTACK_AUTH_TOKEN`
diff --git a/skills/iam-policy-analyzer/SKILL.md b/skills/iam-policy-analyzer/SKILL.md
index de1030a..b9228b8 100644
--- a/skills/iam-policy-analyzer/SKILL.md
+++ b/skills/iam-policy-analyzer/SKILL.md
@@ -17,22 +17,32 @@ Analyze IAM policies, detect permission violations, and automatically generate l
 
 ## Prerequisites
 
-IAM enforcement requires LocalStack Pro:
-
-```bash
-export LOCALSTACK_AUTH_TOKEN=<your-token>
-```
+- The `lstk` CLI, authenticated with a LocalStack account (`lstk login`, or `LOCALSTACK_AUTH_TOKEN` in CI) — see the `localstack` skill
+- Optional: the legacy `localstack` CLI (`pip install localstack`) for the IAM policy stream — see [Auto-Generate Policies](#auto-generate-policies). `lstk` has no equivalent command yet.
 
 ## IAM Enforcement Modes
 
 ### Enable Enforcement
 
+`lstk` forwards host environment variables prefixed with `LOCALSTACK_`, so `ENFORCE_IAM` is set as `LOCALSTACK_ENFORCE_IAM`:
+
 ```bash
 # Soft mode - logs violations but allows requests
-ENFORCE_IAM=soft localstack start -d
+LOCALSTACK_ENFORCE_IAM=soft lstk start
 
 # Enforced mode - denies unauthorized requests
-ENFORCE_IAM=1 localstack start -d
+LOCALSTACK_ENFORCE_IAM=1 lstk start
+```
+
+To make enforcement the default for a project, use an environment profile in `config.toml` (keys inside a profile need no prefix):
+
+```toml
+[[containers]]
+type = "aws"
+env  = ["iam"]
+
+[env.iam]
+ENFORCE_IAM = "soft"
 ```
 
 ### Configuration
@@ -45,17 +55,19 @@ ENFORCE_IAM=1 localstack start -d
 
 ## Creating IAM Resources
 
+`lstk aws` proxies the host `aws` CLI with the LocalStack endpoint, credentials, and region pre-configured.
+
 ### Create a User with Policy
 
 ```bash
 # Create user
-awslocal iam create-user --user-name dev-user
+lstk aws iam create-user --user-name dev-user
 
 # Create access key
-awslocal iam create-access-key --user-name dev-user
+lstk aws iam create-access-key --user-name dev-user
 
 # Attach policy
-awslocal iam attach-user-policy \
+lstk aws iam attach-user-policy \
   --user-name dev-user \
   --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess
 ```
@@ -64,11 +76,13 @@ awslocal iam attach-user-policy \
 
 ```bash
 # Create policy from JSON file
-awslocal iam create-policy \
+lstk aws iam create-policy \
   --policy-name my-custom-policy \
   --policy-document file://policy.json
+```
 
-# Example policy.json
+```json
+// Example policy.json
 {
   "Version": "2012-10-17",
   "Statement": [
@@ -93,18 +107,34 @@ awslocal iam create-policy \
 3. Check logs for access denied messages
 
 ```bash
-# View IAM-related log entries
-localstack logs | grep -i "access denied"
-localstack logs | grep -i "iam"
+# View IAM-related log entries (-v disables lstk's default log filtering)
+lstk logs -v | grep -i "access denied"
+lstk logs -v | grep -i "iam"
 ```
 
 ### Auto-Generate Policies
 
-Based on access patterns observed in soft mode, create least-privilege policies:
+The legacy `localstack` CLI can print the exact policy each request would need, which is far more reliable than reading logs. There is no `lstk` equivalent yet, so install the legacy CLI alongside `lstk` for this workflow:
+
+```bash
+pip install localstack
+
+# Live stream of recommended policies as requests come in
+localstack aws iam stream
+localstack aws iam stream --format json
+
+# Aggregate summary of policies for all enforced requests
+localstack aws iam summary
+```
+
+Workflow:
+
+1. Start with `LOCALSTACK_ENFORCE_IAM=soft lstk start`
+2. Run `localstack aws iam stream` in a second terminal
+3. Exercise your application
+4. Collect the recommended statements and merge them into a minimal policy
 
-1. Run application with `ENFORCE_IAM=soft`
-2. Collect all accessed resources and actions from logs
-3. Generate minimal policy covering observed access
+If the legacy CLI is not available, fall back to reading `lstk logs -v` for access-denied entries and building the policy from the observed actions and resources.
 
 ## Testing Policies
 
@@ -112,7 +142,7 @@ Based on access patterns observed in soft mode, create least-privilege policies:
 
 ```bash
 # Test if action would be allowed
-awslocal iam simulate-principal-policy \
+lstk aws iam simulate-principal-policy \
   --policy-source-arn arn:aws:iam::000000000000:user/dev-user \
   --action-names s3:GetObject \
   --resource-arns arn:aws:s3:::my-bucket/file.txt
@@ -122,7 +152,7 @@ awslocal iam simulate-principal-policy \
 
 ```bash
 # Check policy syntax
-awslocal accessanalyzer validate-policy \
+lstk aws accessanalyzer validate-policy \
   --policy-document file://policy.json \
   --policy-type IDENTITY_POLICY
 ```
@@ -130,7 +160,9 @@ awslocal accessanalyzer validate-policy \
 ## Best Practices
 
 - Start with soft enforcement to discover required permissions
+- Use `localstack aws iam stream` rather than log grepping when generating policies
 - Use least-privilege principles when creating policies
 - Test policies locally before deploying to AWS
+- Snapshot a known-good IAM setup with `lstk save` so you can restore it after experiments
 - Regularly audit and refine policies based on actual usage
 - Use IAM roles instead of users where possible
diff --git a/skills/localstack-extensions/SKILL.md b/skills/localstack-extensions/SKILL.md
index 362fd01..084e407 100644
--- a/skills/localstack-extensions/SKILL.md
+++ b/skills/localstack-extensions/SKILL.md
@@ -1,12 +1,16 @@
 ---
 name: localstack-extensions
-description: Manage LocalStack Extensions. Use when users want to install, uninstall, list, or configure LocalStack extensions, or develop custom extensions to extend LocalStack functionality.
+description: Manage LocalStack Extensions. Use when users want to install, uninstall, list, or configure LocalStack extensions, or develop custom extensions to extend LocalStack functionality. Extensions require the legacy localstack CLI, not lstk.
 ---
 
 # LocalStack Extensions
 
 Manage LocalStack Extensions to add custom functionality, integrate third-party tools, and extend LocalStack capabilities.
 
+> **`lstk` does not support Extensions.** There is no `lstk extensions` command suite. Extension workflows must use the legacy `localstack` CLI for both installing extensions *and* starting the emulator — `lstk` keeps its own volume directory (`lstk volume path`, e.g. `~/Library/Caches/lstk/volume/localstack-aws`), separate from the legacy volume that extensions install into, so an emulator started by `lstk` will not load them.
+>
+> For everything else — lifecycle, IaC, snapshots, logs — prefer `lstk`. See the `localstack` skill.
+
 ## Capabilities
 
 - Install and manage LocalStack Extensions
@@ -14,6 +18,17 @@ Manage LocalStack Extensions to add custom functionality, integrate third-party
 - Configure extension settings
 - Develop custom extensions
 
+## Prerequisites
+
+The legacy CLI and, for the examples below, the `awslocal` wrapper:
+
+```bash
+pip install localstack
+pip install awscli-local   # optional; or use: aws --endpoint-url=http://localhost:4566
+```
+
+Do not run `lstk start` and `localstack start` at the same time — each manages its own container and they will conflict on port 4566. Stop one before starting the other (`lstk stop` / `localstack stop`).
+
 ## Extension Management
 
 ### List Installed Extensions
@@ -51,9 +66,7 @@ EXTENSION_NAME_ENABLED=0 localstack start -d
 
 ## Available Extensions
 
-### Community Extensions
-
-Check the [LocalStack Extensions Registry](https://docs.localstack.cloud/user-guide/extensions/) for community-contributed extensions.
+Browse the [Official Extensions Library](https://app.localstack.cloud/extensions/library) and the [Extensions documentation](https://docs.localstack.cloud/aws/capabilities/extensions/) for available extensions.
 
 ## Using Extensions
 
@@ -63,7 +76,7 @@ Check the [LocalStack Extensions Registry](https://docs.localstack.cloud/user-gu
 # Install
 localstack extensions install localstack-extension-mailhog
 
-# Start LocalStack
+# Start LocalStack with the legacy CLI so the extension is loaded
 localstack start -d
 
 # Access MailHog UI
@@ -114,11 +127,15 @@ class MyExtension(Extension):
 ```bash
 # Install in development mode
 localstack extensions install -e ./my-extension
+
+# Developer mode helpers
+localstack extensions dev list
+localstack extensions dev enable ./my-extension
 ```
 
 ## Configuration
 
-Extensions can be configured via environment variables:
+Extensions are configured via environment variables passed to `localstack start`:
 
 ```bash
 # General pattern
@@ -128,8 +145,13 @@ EXTENSION_<NAME>_<SETTING>=value localstack start -d
 EXTENSION_MAILHOG_PORT=8025 localstack start -d
 ```
 
+Note that the legacy CLI takes these variables **without** the `LOCALSTACK_` prefix that `lstk` requires.
+
 ## Troubleshooting
 
-- **Extension not loading**: Check `localstack logs` for errors
-- **Conflicts**: Disable conflicting extensions
-- **Version issues**: Ensure extension is compatible with your LocalStack version
+- **Extension not loading**: Confirm you started the emulator with `localstack start`, not `lstk start` — `lstk` uses a different volume directory and will not see installed extensions
+- **Port conflict on 4566**: an `lstk`-managed container may still be running; `lstk stop` first
+- **Errors on startup**: check `localstack logs` for extension stack traces
+- **Conflicts**: disable conflicting extensions
+- **Version issues**: ensure the extension is compatible with your LocalStack version
+- **Docker Compose users**: point `LOCALSTACK_VOLUME_DIR` at the LocalStack volume on your host (`~/.cache/localstack` on Linux, `~/Library/Caches/localstack` on macOS) so the CLI installs into the right place
diff --git a/skills/localstack-lifecycle/SKILL.md b/skills/localstack-lifecycle/SKILL.md
index 6d27137..7a61c3e 100644
--- a/skills/localstack-lifecycle/SKILL.md
+++ b/skills/localstack-lifecycle/SKILL.md
@@ -1,81 +1,193 @@
 ---
 name: localstack
-description: Manage LocalStack container lifecycle. Use when users need to start, stop, restart, or check status of LocalStack, configure LocalStack environment variables, or troubleshoot LocalStack container issues.
+description: Manage the LocalStack emulator lifecycle with the lstk CLI. Use when users need to start, stop, restart, reset, or check status of LocalStack, configure LocalStack environment variables, or troubleshoot LocalStack container issues.
 ---
 
 # LocalStack Lifecycle Management
 
-Manage the LocalStack container lifecycle including starting, stopping, and monitoring the local cloud environment.
+Manage the LocalStack emulator lifecycle — starting, stopping, and monitoring the local cloud environment — using `lstk`, the current LocalStack CLI.
 
 ## Capabilities
 
 - Start LocalStack with custom configuration
-- Stop running LocalStack instances
+- Stop, restart, and reset running LocalStack instances
 - Check LocalStack status and health
-- Restart LocalStack with new settings
-- View LocalStack version and configuration
+- Manage the emulator volume and persisted state
+- Authenticate against the LocalStack platform
+
+## Prerequisites
+
+- Docker installed and running
+- A LocalStack account (`lstk` pulls the `localstack/localstack-pro` image and requires a valid license)
+- The `lstk` CLI:
+
+```bash
+# Homebrew (macOS/Linux)
+brew install localstack/tap/lstk
+
+# npm
+npm install -g @localstack/lstk
+
+# Verify
+lstk --version
+```
+
+> The legacy `localstack` CLI is deprecated and will be removed in a future version. Prefer `lstk`. A few features still live only in the legacy CLI — see [Legacy CLI fallbacks](#legacy-cli-fallbacks).
+
+## Authentication
+
+```bash
+# Interactive browser login; stores the token in the system keyring
+lstk login
+
+# Remove stored credentials
+lstk logout
+```
+
+In CI or any non-TTY environment, set the auth token instead (a CI Auth Token — a personal Developer Auth Token will not work in CI):
+
+```bash
+export LOCALSTACK_AUTH_TOKEN=<token>
+lstk --non-interactive start
+```
+
+Token resolution order: system keyring (from `lstk login`) → `LOCALSTACK_AUTH_TOKEN` → interactive browser login. The keyring wins over the environment variable, so run `lstk logout` first if you need to switch.
 
 ## Common Commands
 
 ### Start LocalStack
 
 ```bash
-# Basic start
-localstack start -d
+# Start the emulator (bare `lstk` is equivalent to `lstk start`)
+lstk start
 
-# Start with debug mode
-DEBUG=1 localstack start -d
+# Start and keep state across restarts
+lstk start --persist
 
-# Start with Pro features (requires auth token)
-LOCALSTACK_AUTH_TOKEN=<token> localstack start -d
+# Start with debug logging (note the LOCALSTACK_ prefix)
+LOCALSTACK_DEBUG=1 lstk start
+
+# Pick the emulator type
+lstk start --type aws          # also: snowflake, azure
+
+# Plain output for scripts/CI, with a startup deadline
+lstk --non-interactive --timeout 90s start
 ```
 
+`lstk start` runs the container in the background and returns once the emulator is ready — there is no `-d` flag.
+
 ### Check Status
 
 ```bash
-# Check if LocalStack is running
-localstack status
+# Emulator state plus the resources currently deployed in it
+lstk status
 
-# Check service health
-curl http://localhost:4566/_localstack/health
+# Plain-text output for scripts
+lstk --non-interactive status
 
-# View running Docker container
-docker ps | grep localstack
+# Service health endpoint
+curl http://localhost:4566/_localstack/health | jq
 ```
 
-### Stop LocalStack
+### Stop and Restart
 
 ```bash
-# Graceful stop
-localstack stop
+lstk stop
+lstk restart
+lstk restart --persist
+```
+
+### Reset State
 
-# Force stop via Docker
-docker stop localstack-main
+```bash
+# Discard all in-memory resources; the emulator keeps running
+lstk reset
+lstk reset --force        # skip the confirmation prompt
 ```
 
 ### View Logs
 
 ```bash
-# Follow logs
-localstack logs -f
+lstk logs                 # print available logs
+lstk logs -f              # follow in real time
+lstk logs -n 100          # last 100 lines
+lstk logs -v              # unfiltered output
+```
+
+### Manage the Volume
+
+```bash
+lstk volume path          # print the volume directory
+lstk volume clear         # wipe certificates, cached tools, persisted data
+lstk volume clear --force
+```
 
-# View last 100 lines
-localstack logs --tail 100
+`lstk reset` clears in-memory state; `lstk volume clear` wipes the on-disk volume. Stop the emulator before clearing the volume.
+
+## Configuration
+
+### Passing environment variables
+
+`lstk` forwards **host environment variables prefixed with `LOCALSTACK_`** into the emulator. Any LocalStack config variable you used to pass bare must now carry that prefix:
+
+```bash
+LOCALSTACK_DEBUG=1 lstk start
+LOCALSTACK_SERVICES=s3,sqs lstk start
+LOCALSTACK_ENFORCE_IAM=soft lstk start
 ```
 
-## Configuration Options
+The host `LOCALSTACK_AUTH_TOKEN` is deliberately *not* forwarded, so it cannot override the token `lstk` resolved.
+
+### Environment profiles in `config.toml`
+
+For settings you want on every run, define named profiles in `config.toml` and reference them from the container block. Keys inside a profile do **not** need the `LOCALSTACK_` prefix:
+
+```toml
+[[containers]]
+type = "aws"
+tag  = "latest"
+port = "4566"
+env  = ["debug", "ci"]
+
+[env.debug]
+DEBUG = "1"
+PERSISTENCE = "1"
+
+[env.ci]
+SERVICES = "s3,sqs"
+EAGER_SERVICE_LOADING = "1"
+```
+
+Config file resolution order: `./.lstk/config.toml` (project-local) → `$HOME/.config/lstk/config.toml` → OS default location. Print the active path with `lstk config path`.
+
+### Common configuration options
+
+| Variable | Description | How to set |
+|----------|-------------|------------|
+| `DEBUG` | Enable debug logging | `LOCALSTACK_DEBUG=1 lstk start` or `[env.*]` profile |
+| `PERSISTENCE` | Persist state across restarts | `lstk start --persist` (preferred) or profile |
+| `SERVICES` | Limit the services started | `LOCALSTACK_SERVICES=s3,sqs lstk start` |
+| `GATEWAY_LISTEN` | Bind address/ports | `GATEWAY_LISTEN = "0.0.0.0:4566"` in a profile |
+| `LOCALSTACK_AUTH_TOKEN` | Platform auth token | Env var, or `lstk login` |
+| `LOCALSTACK_HOST` | Override the endpoint host used by `lstk aws` and friends | Env var |
+
+Pin an image version with `tag` in `config.toml` (e.g. `tag = "2026.4"`), or point `image` at an internal registry for air-gapped setups.
+
+## Legacy CLI fallbacks
+
+`lstk` does not cover every legacy feature yet. Install the legacy CLI (`pip install localstack`) alongside `lstk` only if you need:
 
-Key environment variables for LocalStack:
+- **Extensions** — there is no `lstk extensions` command suite; see the `localstack-extensions` skill
+- **`localstack aws iam stream` / `summary`** — IAM policy stream and summary; see the `localstack-iam` skill
+- **Advanced DNS configuration** (systemd-resolved integration) and ephemeral cloud instances
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `DEBUG` | Enable debug logging | `0` |
-| `PERSISTENCE` | Enable persistence across restarts | `0` |
-| `LOCALSTACK_AUTH_TOKEN` | Auth token for Pro features | None |
-| `GATEWAY_LISTEN` | Port configuration | `4566` |
+`lstk` manages its own Docker container and cannot be mixed with a Docker Compose LocalStack setup, or with a container started by the legacy `localstack start`. To point `lstk` at an emulator you manage yourself, use `--endpoint-url`.
 
 ## Troubleshooting
 
-- **Container won't start**: Check if port 4566 is already in use
-- **Services unavailable**: Verify Docker is running and has sufficient resources
-- **Auth errors**: Ensure `LOCALSTACK_AUTH_TOKEN` is set for Pro features
+- **`Error: runtime not healthy`**: Docker is not running. Start Docker Desktop or the daemon, or set `DOCKER_HOST` for a custom socket.
+- **Port 443 conflict**: set `GATEWAY_LISTEN = "0.0.0.0:4566"` in an environment profile so only 4566 is bound.
+- **Auth errors in CI**: set `LOCALSTACK_AUTH_TOKEN` before `lstk start`; a TTY-less environment cannot run the browser flow.
+- **Stale license**: `lstk logout && lstk login`.
+- **Unknown env var had no effect**: confirm it is prefixed with `LOCALSTACK_` on the host, or moved into an `[env.*]` profile.
+- **Diagnostics**: `lstk` writes `lstk.log` next to the config file — find it with `lstk config path`.
diff --git a/skills/logs-analysis/SKILL.md b/skills/logs-analysis/SKILL.md
index 9a0139d..a0ec50d 100644
--- a/skills/logs-analysis/SKILL.md
+++ b/skills/logs-analysis/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: localstack-logs
-description: Analyze LocalStack logs and debug issues. Use when users need to view LocalStack logs, debug AWS API errors, troubleshoot Lambda functions, identify error patterns, or enable debug mode.
+description: Analyze LocalStack logs and debug issues with lstk. Use when users need to view LocalStack logs, debug AWS API errors, troubleshoot Lambda functions, identify error patterns, or enable debug mode.
 ---
 
 # LocalStack Logs Analysis
@@ -15,50 +15,79 @@ Analyze LocalStack logs to debug issues, identify errors, and understand AWS API
 - Track service-specific operations
 - Debug Lambda function executions
 
+## Prerequisites
+
+- The `lstk` CLI with a running emulator — see the `localstack` skill
+
 ## Viewing Logs
 
 ### Basic Log Commands
 
 ```bash
-# Follow logs in real-time
-localstack logs -f
+# Print available logs
+lstk logs
+
+# Follow logs in real time
+lstk logs -f
 
-# View last N lines
-localstack logs --tail 100
+# Last N lines
+lstk logs -n 100
 
-# Via Docker
-docker logs localstack-main -f
-docker logs localstack-main --tail 200
+# Unfiltered output (lstk filters noise by default)
+lstk logs -v
 ```
 
+Reach for `lstk logs -v` whenever a log line you expect is missing — the default view drops low-signal output.
+
 ### Filtering Logs
 
 ```bash
 # Filter by service
-localstack logs | grep -i s3
-localstack logs | grep -i lambda
-localstack logs | grep -i dynamodb
+lstk logs | grep -i s3
+lstk logs | grep -i lambda
+lstk logs | grep -i dynamodb
 
 # Filter errors only
-localstack logs | grep -i error
-localstack logs | grep -i exception
+lstk logs | grep -i error
+lstk logs | grep -i exception
+
+# Filter by request ID (use -v so nothing is filtered out first)
+lstk logs -v | grep "request-id-here"
+```
+
+### Diagnostic Logs
+
+`lstk` writes its own diagnostic log to `lstk.log` in the config directory — useful when the CLI itself misbehaves rather than the emulator:
 
-# Filter by request ID
-localstack logs | grep "request-id-here"
+```bash
+lstk config path      # the lstk.log sits alongside this file
 ```
 
 ## Debug Mode
 
-Enable detailed logging:
+`lstk` forwards host environment variables **prefixed with `LOCALSTACK_`** into the emulator, so LocalStack config variables need that prefix:
 
 ```bash
 # Start with debug mode
-DEBUG=1 localstack start -d
+LOCALSTACK_DEBUG=1 lstk start
 
-# Enable specific debug flags
-LS_LOG=trace localstack start -d
+# Trace-level logging
+LOCALSTACK_LS_LOG=trace lstk start
 ```
 
+To make debug logging the default for a project, use an environment profile in `config.toml`:
+
+```toml
+[[containers]]
+type = "aws"
+env  = ["debug"]
+
+[env.debug]
+DEBUG = "1"
+```
+
+Keys inside an `[env.*]` profile do not need the `LOCALSTACK_` prefix.
+
 ## Analyzing API Requests
 
 ### Request/Response Tracking
@@ -76,11 +105,20 @@ AWS dynamodb.PutItem => 200
 AWS lambda.Invoke => 200
 ```
 
+### Deployed Resources
+
+`lstk status` lists the resources currently deployed in the emulator, which is often faster than grepping logs to answer "does this resource exist?":
+
+```bash
+lstk status
+lstk --non-interactive status
+```
+
 ### Common Error Patterns
 
 | Error | Possible Cause | Solution |
 |-------|---------------|----------|
-| `ResourceNotFoundException` | Resource doesn't exist | Create the resource first |
+| `ResourceNotFoundException` | Resource doesn't exist | Create the resource first; confirm with `lstk status` |
 | `AccessDeniedException` | IAM policy issue | Check IAM enforcement mode |
 | `ValidationException` | Invalid parameters | Verify request parameters |
 | `ServiceException` | Internal error | Check LocalStack logs for details |
@@ -90,12 +128,12 @@ AWS lambda.Invoke => 200
 ### View Lambda Logs
 
 ```bash
-# Lambda function logs appear in LocalStack logs
-localstack logs | grep -A 10 "Lambda"
+# Lambda function logs appear in the emulator logs
+lstk logs -v | grep -A 10 "Lambda"
 
 # Or use CloudWatch Logs locally
-awslocal logs describe-log-groups
-awslocal logs get-log-events \
+lstk aws logs describe-log-groups
+lstk aws logs get-log-events \
   --log-group-name /aws/lambda/my-function \
   --log-stream-name <stream-name>
 ```
@@ -103,7 +141,7 @@ awslocal logs get-log-events \
 ### Enable Lambda Debug Mode
 
 ```bash
-LAMBDA_DEBUG=1 localstack start -d
+LOCALSTACK_LAMBDA_DEBUG=1 lstk start
 ```
 
 ## Health Check
@@ -118,7 +156,9 @@ curl http://localhost:4566/_localstack/health | jq '.services.s3'
 
 ## Troubleshooting Tips
 
-- **No logs appearing**: Ensure LocalStack is running (`localstack status`)
-- **Missing debug info**: Enable `DEBUG=1` for verbose logging
-- **Lambda issues**: Check both LocalStack logs and CloudWatch Logs
+- **No logs appearing**: Ensure the emulator is running (`lstk status`)
+- **Expected line missing**: Re-run with `lstk logs -v` — the default view is filtered
+- **Missing debug info**: Start with `LOCALSTACK_DEBUG=1` for verbose logging
+- **Lambda issues**: Check both the emulator logs and CloudWatch Logs
 - **Intermittent errors**: Look for resource limits or timing issues
+- **CLI-level problems**: Check `lstk.log` in the directory reported by `lstk config path`
diff --git a/skills/state-management/SKILL.md b/skills/state-management/SKILL.md
index efe2107..c3b0dc4 100644
--- a/skills/state-management/SKILL.md
+++ b/skills/state-management/SKILL.md
@@ -1,134 +1,211 @@
 ---
 name: localstack-state
-description: Manage LocalStack state and snapshots. Use when users want to save, load, export, or import LocalStack state, work with Cloud Pods, create local snapshots, or enable persistence across restarts.
+description: Manage LocalStack state and snapshots with lstk. Use when users want to save, load, export, or import LocalStack state, work with Cloud Pods or S3-backed snapshots, or enable persistence across restarts.
 ---
 
 # State Management
 
-Save, load, and manage LocalStack state for reproducible development environments and state snapshots.
+Save, load, and manage LocalStack state for reproducible development environments and state snapshots, using `lstk snapshot` and its `lstk save` / `lstk load` aliases.
 
 ## Capabilities
 
-- Export and import state locally to files
-- Save and load state to/from Cloud Pods (remote storage)
+- Save and restore state as local snapshot files
+- Save and load state to/from Cloud Pods (LocalStack platform storage)
+- Save and load state to/from your own S3 bucket
 - Share state across teams via Cloud Pods
+- Auto-load a snapshot every time the emulator starts
 - Enable persistent state across container restarts
 
-## Local Snapshots (state export/import)
+## Prerequisites
 
-Local snapshots allow you to export LocalStack state to files and import them back. This works without requiring a Pro subscription.
+- `lstk` installed and authenticated (`lstk login`, or `LOCALSTACK_AUTH_TOKEN` in CI) — see the `localstack` skill
+- A running emulator for `save` (`lstk load` will start one for you if needed)
 
-### Export State
+`lstk save` / `lstk load` replace the legacy `localstack state export/import` and `localstack pod save/load` commands with a single snapshot interface. The destination REF decides where the state goes.
+
+## Snapshot References (REF)
+
+| REF form | Destination |
+|----------|-------------|
+| *(omitted)* | Auto-named local file `./snapshot-<timestamp>-<hex>.snapshot` |
+| `./my-snapshot.snapshot` | Explicit local path |
+| `pod:my-baseline` | Cloud Pod on the LocalStack platform |
+| `pod:my-baseline:3` | Version 3 of that Cloud Pod |
+| `my-pod s3://my-bucket/prefix` | Your own S3 bucket |
+
+## Local Snapshots
+
+### Save
 
 ```bash
-# Export current state to a local file
-localstack state export my-state.zip
+# Save to an auto-named file in the current directory
+lstk save
+
+# Save to a specific path (the .snapshot extension is added if omitted)
+lstk save ./my-snapshot.snapshot
+lstk save /tmp/my-state
 
-# Export to a specific path
-localstack state export /path/to/backup/state.zip
+# Limit the snapshot to a subset of services
+lstk save --services s3,lambda
 ```
 
-### Import State
+### Load
 
 ```bash
-# Import state from a local file
-localstack state import my-state.zip
+# Loads ./my-baseline or ./my-baseline.snapshot
+lstk load my-baseline
 
-# Import from a specific path
-localstack state import /path/to/backup/state.zip
+# Load from an explicit path
+lstk load ./checkpoint.snapshot
 ```
 
 ### Use Cases for Local Snapshots
 
 - **Backup/restore**: Save state before destructive operations
-- **CI/CD pipelines**: Commit state files to version control for reproducible tests
-- **Offline workflows**: Work with state files without cloud connectivity
+- **CI/CD pipelines**: Commit snapshot files to version control for reproducible tests
+- **Offline workflows**: Work with snapshot files without cloud connectivity
 - **Quick snapshots**: Fast local save/restore during development
 
-## Cloud Pods (pod save/load)
+## Cloud Pods
 
-Cloud Pods store state in LocalStack's cloud platform, enabling team collaboration and remote state management.
+Cloud Pods store state on the LocalStack platform, enabling team collaboration and remote state management. They require authentication (`lstk login` or `LOCALSTACK_AUTH_TOKEN`).
 
-### Prerequisites
-
-Cloud Pods require a LocalStack Pro subscription and auth token:
+### Save to a Cloud Pod
 
 ```bash
-export LOCALSTACK_AUTH_TOKEN=<your-token>
+lstk save pod:my-baseline
+
+# Only part of the state
+lstk save pod:my-baseline --services s3,lambda
 ```
 
-### Save to Cloud Pod
+Every save to an existing pod name creates a new version.
+
+### Load from a Cloud Pod
 
 ```bash
-# Save current state to a Cloud Pod
-localstack pod save my-pod-name
+lstk load pod:my-baseline
 
-# Save with a message
-localstack pod save my-pod-name --message "Initial setup with S3 and DynamoDB"
+# A specific version
+lstk load pod:my-baseline:3
+
+# Preview the changes without applying them (Cloud Pod refs only)
+lstk load pod:my-baseline --dry-run
 ```
 
-### Load from Cloud Pod
+### List, Inspect, and Remove
 
 ```bash
-# Load state from a Cloud Pod
-localstack pod load my-pod-name
+# Your Cloud Pods
+lstk snapshot list
+
+# Everything in your organisation
+lstk snapshot list --all
 
-# Load and merge with existing state
-localstack pod load my-pod-name --merge
+# Metadata: created date, size, LocalStack version, per-service resource counts
+lstk snapshot show pod:my-baseline
+lstk snapshot show pod:my-baseline:3
+
+# Version history
+lstk snapshot versions pod:my-baseline
+
+# Delete (cloud snapshots only, cannot be undone)
+lstk snapshot remove pod:my-baseline
+lstk snapshot remove pod:my-baseline --force
 ```
 
-### List Cloud Pods
+### Use Cases for Cloud Pods
+
+- **Team collaboration**: Share consistent development environments across team members
+- **Demo environments**: Prepare and share demo-ready states
+- **Cross-machine development**: Access the same state from different machines
+
+## S3-Backed Snapshots
+
+Store snapshots in a bucket you own. Credentials are read from `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`, from `--profile`, or from the profile named by `AWS_PROFILE` — never put credentials in the URL.
 
 ```bash
-# List all available Cloud Pods
-localstack pod list
+lstk save my-pod s3://my-bucket/prefix
+lstk save my-pod s3://my-bucket/prefix --profile my-aws-profile
+
+lstk load my-pod s3://my-bucket/prefix
+
+lstk snapshot list s3://my-bucket/prefix
 ```
 
-### Delete Cloud Pods
+## Merge Strategies
+
+`lstk load` controls how snapshot state combines with state already in the emulator:
+
+| Strategy | Behavior |
+|----------|----------|
+| `account-region-merge` *(default)* | Snapshot wins on overlapping (service, account, region) |
+| `overwrite` | Wipe running state, then load |
+| `service-merge` | Snapshot wins per resource; non-overlapping resources are combined |
 
 ```bash
-# Delete a Cloud Pod
-localstack pod delete my-pod-name
+lstk load pod:my-baseline --merge=overwrite
 ```
 
-### Inspect Cloud Pods
+You can also set `LSTK_MERGE_STRATEGY` instead of passing the flag.
 
-```bash
-# View Cloud Pod details
-localstack pod inspect my-pod-name
+## Auto-Loading a Snapshot on Start
+
+For the AWS emulator, set the `snapshot` field on the container block so a snapshot loads on every start:
+
+```toml
+[[containers]]
+type     = "aws"
+snapshot = "pod:my-baseline"
 ```
 
-### Use Cases for Cloud Pods
+Override or skip it for a single run:
 
-- **Team collaboration**: Share consistent development environments across team members
-- **Demo environments**: Prepare and share demo-ready states
-- **Cross-machine development**: Access the same state from different machines
+```bash
+lstk start --snapshot pod:other-baseline
+lstk start --no-snapshot
+```
 
 ## Local Persistence
 
-For automatic persistence across LocalStack restarts (without explicit export/import):
+For automatic persistence across restarts without explicit save/load:
 
 ```bash
-# Enable local persistence
-PERSISTENCE=1 localstack start -d
+lstk start --persist
+lstk restart --persist
+```
+
+`--persist` injects `LOCALSTACK_PERSISTENCE=1` and writes state to the mounted volume, which is reloaded on the next start. Find that directory with `lstk volume path`; wipe it with `lstk volume clear`.
+
+You can also set `PERSISTENCE = "1"` in an `[env.*]` profile in `config.toml` to make it the default for every run.
 
-# State is saved to .localstack/ directory
-# Survives container restarts
+## Clearing State
+
+```bash
+# Discard in-memory resources, keep the emulator running
+lstk reset
+
+# Wipe the on-disk volume (stop the emulator first)
+lstk volume clear
 ```
 
 ## Comparison
 
-| Feature | Local Snapshots (export/import) | Cloud Pods (save/load) |
-|---------|----------------------------|------------------------|
-| Storage | Local files | LocalStack cloud |
-| Pro required | No | Yes |
-| Team sharing | Manual file sharing | Built-in |
-| Version control | Can commit files | Cloud-managed |
-| Offline use | Yes | No |
+| Feature | Local snapshot files | Cloud Pods (`pod:`) | Your S3 bucket (`s3://`) |
+|---------|----------------------|---------------------|--------------------------|
+| Storage | Local files | LocalStack platform | Your AWS account |
+| Extra auth | None beyond `lstk` | LocalStack auth token | AWS credentials |
+| Team sharing | Manual file sharing | Built-in | Via bucket permissions |
+| Versioning | Manual | Built-in (`snapshot versions`) | Manual |
+| Offline use | Yes | No | No |
+
+Note that `lstk` itself always requires a LocalStack account and license, regardless of which snapshot backend you use.
 
 ## Best Practices
 
-- Use `state export/import` for local development and CI/CD pipelines
+- Use local snapshot files for development checkpoints and CI/CD pipelines
 - Use Cloud Pods for team collaboration and shared environments
 - Use descriptive names that indicate the state contents
-- Enable `PERSISTENCE=1` for simple state retention across restarts
+- Use `--services` to keep snapshots small when you only care about part of the stack
+- Use `--dry-run` before loading an unfamiliar Cloud Pod into a populated emulator
+- Use `lstk start --persist` for simple state retention across restarts