v2 Getting Started (AWS)

[remotesynth]

The concepts behind this draft:

1. update cli mentions to feature lstk
2. decouple the Quickstart from the Getting Started
3. bring AI and agent use cases up front

DOC-12

[cloudflare-workers-and-pages]

Deploying localstack-docs with Cloudflare Pages

Latest commit:	80382bb
Status:	✅ Deploy successful!
Preview URL:	https://be1982b3.localstack-docs.pages.dev
Branch Preview URL:	https://revise-getting-started.localstack-docs.pages.dev

View logs

[quetzalliwrites]

added do not merge label + made it a draft to avoid any accidental merges @remotesynth 😸

[peter-smith-phd]

Thanks for sharing this PR. It's really nice to see the focus of Local, CI, and AI, and the working example is the perfect size to get something up and running in 10 minutes.

But, I think there's more trimming to be done. There's still a lot of complexity in these pages that go beyond "Getting Started". It'd suggest you document the happy path for the common case, and just hyperlink to the more advanced pages for more detail. If we can't get the happy path working well, then we need to fix the software to make it work better.

[quetzalliwrites]

PR Audit Summary

Status: Needs Significant Rework

This PR introduces several critical technical inaccuracies, broken code snippets, and information architectural redundancies. To maintain our technical integrity and avoid introducing "docs debt," the following must be addressed before merging.

Technical & Architectural Requirements

1) Technical Accuracy (High Priority)

• Incorrect Resource Labeling: Describing LocalStack as "real Lambda" or "real DynamoDB" is technically incorrect. We are an emulation layer. We must accurately state these are "LocalStack-hosted" or "emulated" resources to ensure technical accuracy.

• Incorrect Tool Categorization: Docker, Docker Compose, and Helm are CLI/Orchestration tools, not GUIs. They must be removed from the /installation GUI section.

• Incorrect CI Providers: The CI/CD tabs include Docker/Compose options which are not CI providers. These must be scoped strictly to CI-specific tools (e.g., GitHub Actions, Jenkins).

2) Code Integrity (Blockers):

All code blocks must be validated and "copy-paste ready" before deployment.

• Python Script Fails Upon Execution: The indentation in each line of this Python script is incorrect, thus #step-2 is currently invalid and fails upon execution.

• CLI Syntax: The cleanup command in #step-5 incorrectly includes bash within the executable block.

3) Documentation Information Architecture (DRY Principles):

• Single Source of Truth (SSOT): The /ai-workflows/ doc currently duplicates content from the MCP documentation. To prevent maintenance overhead, we are removing the duplicate text and replacing it with a note block directing users to the primary MCP doc as the source of truth.

• Structure: The "Summary" section in /ai-workflows/ lacks a narrative conclusion and contains a use-case table. This table is being moved to the Introduction for better high-level visibility.

4) Editorial Standards:

• Voice & Tone: The current draft uses informal, "blog-style" phrasing (e.g., "That's the win"). We are reverting this to a proffesional, technical documentation voice to maintain authority.

• Punctuation: Consistent with our style guide, we are replacing the over use of em-dashes with colons or period breaks to remove AI-generated markers + improve readability.

• Redundancy: The /auth-token/ introduction currently repeats the same information from the body content. This must be tightened to a high-signal summary.

Why this is necessary:

We are holding this PR to ensure the "Getting Started" experience (the most high-traffic area of our site) is technically accurate and the information architecture is consistent. Merging in the current state would introduce immediate technical debt and user friction.

[quetzalliwrites]

Information Architecture Realignment: Removing Quickstart Anti-Pattern

As part of the v2 Getting Started experience, I am realigning our information architecture (and sidebar hierarchy) to resolve a long-standing architectural anti-pattern: housing a specific Quickstart tutorial within the general "Getting Started" folder.

Rationale for the Restructure:

• Eliminating Cognitive Load: Titling a page "Local Development" while the internal content refers to it as a "Quickstart" creates a significant disconnect for the user. Users expect "Local Development" to cover core operational concepts (persistence, networking, dev loops); finding a specific Lambda/DynamoDB tutorial instead is a misleading user experience.

• Getting Started as a Journey: Industry standard dictates that "Getting Started" is a high-level journey. Covering the Overview, Installation, and initial Configuration. It is the foundation, not the specific implementation.

• Decoupling Content Types: A Quickstart is a specific functional recipe, whereas Getting Started is system onboarding. To scale effectively, we must decouple these. This realignment is the first step toward our Quickstart Library (currently tracked in this Linear DOCS Project), mirroring the successful developer experiences of enterprise leaders like Stripe and HashiCorp.

Action Taken: I am stripping the "Quickstart" branding from the "Local Development" page and reframing it as a declarative guide for deploying your first local serverless API. This ensures the folder remains a cohesive onboarding path, while the upcoming Quickstart Library will serve as the dedicated home for specialized, multi-language recipes.

[remotesynth]

Updated from main and resolved merge conflicts:

Files resolved

File	Resolution
astro.config.mjs	Kept main's consolidated Developer Tools sidebar; removed duplicate Tooling/Integrations sections
public/_redirects	Used main's new paths, kept branch redirects for quickstart → local-development
custom-tls-certificates.mdx	Updated links to new installation/customization paths
auth-token.mdx	Kept branch's streamlined rewrite; dropped duplicate main content
installation.mdx	Kept lstk-first install flow; updated doc links to new paths; kept CLI troubleshooting
localstack-cli.md	Kept full deprecated CLI reference at developer-tools/running-localstack/; merged lstk note
index.md	Deleted — branch uses index.mdx with SectionCards
quickstart.mdx	Deleted — replaced by local-development.mdx (redirects preserved)
tooling/localstack-cli.mdx	Deleted — canonical page is under developer-tools (redirect exists)

Additional fixes

• Updated stale links in index.mdx (Cloud Pods, IAM, Chaos, Kubernetes)
• Updated lstk doc links from /aws/tooling/lstk/ to /aws/developer-tools/running-localstack/lstk/

[quetzalliwrites]

Naming our foundational quickstart the same name as the section in our Getting Started does not make sense.

Since this is our first foundational quickstart, we want a name that highlights either the foundational nature of this quickstart or the specific action the users are doing.

App Inspector is the headline feature here.

We want a name that balances the specific tool (App Inspector) they are using + the ultimate benefit they get (iow, is seeing how their Lambda and DynamoDB talk to each other).

This quickstart specifically guides users to "Use the LocalStack Web Application to inspect, browse, snapshot, and trace the serverless API you deployed."

Thus, here are a few naming angles:

Option 1: Action & Stack Focused

These tell the user exactly what they are building right away, which makes the library look like a practical cookbook.

Example:

• Deploying a Serverless API

Option 2: Core Platform Feature Focused

We chose to emphasize how users interact with our LocalStack Web App (the Web App, inspecting, tracing), which means we can pick a title along that angle.

Examples:

• Web Application Tour
• Inspecting Deployed APIs
• Application Inspection & Tracing

[quetzalliwrites]

Renamed foundational Quickstart to Application Inspection & Tracing

Naming our foundational quickstart the same name as the "Local Development" section in our Getting Started does not make sense.

Since this is our first foundational quickstart, we want a name that highlights either the foundational nature of this quickstart or the specific action the users are doing.

App Inspector is the headline feature here.

We want a name that balances the specific tool (App Inspector) they are using + the ultimate benefit they get (iow, is seeing how their Lambda and DynamoDB talk to each other).

This quickstart specifically guides users to "Use the LocalStack Web Application to inspect, browse, snapshot, and trace the serverless API you deployed."

Thus, here are a few naming angles:

Option 1: Action & Stack Focused

These tell the user exactly what they are building right away, which makes the library look like a practical cookbook.

Example:

• Deploying a Serverless API

Option 2: Core Platform Feature Focused

We chose to emphasize how users interact with our LocalStack Web App (the Web App, inspecting, tracing), which means we can pick a title along that angle.

Examples:

• Web Application Tour
• Inspecting Deployed APIs
• Application Inspection & Tracing

---

I've updated this PR to move forward with the new title, Application Inspection & Tracing.