improve agent readiness - #891
Open
HarshCasper wants to merge 10 commits into
Open
Conversation
Add a schema.org JSON-LD @graph (Organization + WebSite + SoftwareApplication) to the homepage head so agents and crawlers can resolve LocalStack's identity programmatically. The Organization node carries contactPoint (support email) and a PostalAddress for business verification and contact queries. Emit og:image / twitter:image site-wide using the official LocalStack social card (1200x630); Starlight already emits og:type and twitter:card but no image. Addresses Is-Agentic checks: JSON-LD structured data, Organization schema completeness, and metadata completeness (og:image).
Override Starlight's default 404 with a page that gives humans and agents a way to recover: links to the docs home, each product section, getting-started, and help/support, plus a dedicated section pointing agents at the machine-readable indexes (sitemap, llms.txt, llms-full.txt, agents.md, api-catalog). Cloudflare Pages serves dist/404.html with a real HTTP 404 status for unmatched paths, so agents get a 404 code and a useful body instead of a bare 'Page not found'. Exclude the generated/static resources linked from the page (llms*.txt, sitemap-index.xml, agents.md, .well-known/**) from the links validator, since they are not Starlight content routes. Addresses Is-Agentic check: agent-friendly 404s.
Add three server-rendered sections below the hero and product cards —
'What is LocalStack?', 'Who is LocalStack for?', and 'Where to go
next' — with a proper h2 heading hierarchy and internal links. This
gives AI crawlers meaningful, structured content in the raw HTML
(no JavaScript required) and directly answers the common agent query
'what does this site do and who is it for?'.
Also replace the placeholder frontmatter description ('Welcome to
LocalStack Docs') with the real product one-liner, improving the meta
description and og:description.
The existing hero and product-card visual design is unchanged.
Addresses Is-Agentic check: content without JavaScript.
Tell agents when LocalStack is the right tool. Add a heading-less 'when to use' + 'how to call it from an agent' block to llms.txt via the plugin's details option, plus optionalLinks surfacing agents.md and the MCP server. Add a 'When to use LocalStack' section near the top of agents.md naming the best-fit use cases (local dev, CI testing, IaC validation, offline debugging) and the boundary (not a production runtime). Addresses Is-Agentic check: agent instruction / when-to-use guidance.
Add Vary: Accept, Accept-Encoding site-wide via _headers to signal representation negotiation to caches and agents. Cloudflare's edge cache ignores non-encoding Vary, so there is no caching cost. Full text/markdown content negotiation still requires a Cloudflare Pages Function and is intentionally out of scope here (pure-static build).
HarshCasper
requested review from
quetzalliwrites and
remotesynth
as code owners
August 24, 2026 15:29
Deploying localstack-docs with
|
| Latest commit: |
64d8d65
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://cc83350f.localstack-docs.pages.dev |
| Branch Preview URL: | https://aws-docs-agent-readiness.localstack-docs.pages.dev |
HarshCasper
changed the title
Update the LocalStack identity description (used in the homepage JSON-LD Organization/WebSite/SoftwareApplication nodes and in the llms.txt summary) to the platform-oriented wording, and correct the SoftwareApplication offer to the current tiers (Hobby, Starter, Ultimate, Enterprise).
Rewrite the homepage 'What is / Who is it for / Where to go next' sections using facts from the localstack.cloud FAQ (same APIs, SDKs, and IaC tools as the live cloud; development and testing only; no provisioning delays or cloud bills; ephemeral and AI-agent sandboxes), and align the page meta description with the platform wording. Drop em dashes and promotional phrasing from the copy I authored (the homepage sections and the 404 recovery links) so it does not read as AI-generated. Remaining em dashes on the homepage are in the pre-existing HeroSection component, which is out of scope here.
Replace the hero paragraph with plain, factual copy: LocalStack runs
AWS, Snowflake, and Azure APIs in local containers, you use the same
SDKs/CLIs/IaC tools, then deploy to the real cloud. Removes the em
dashes and promotional phrasing ('Spin up fully functional',
'integrates seamlessly', 'ship faster and safer') so the homepage does
not read as AI-generated. Styling and the 'Choose a product' heading
are unchanged.
HarshCasper
changed the title
quetzalliwrites
requested changes
Aug 25, 2026
quetzalliwrites
left a comment
quetzalliwrites
left a comment
Collaborator
There was a problem hiding this comment.
this looks like a messy ai slop hastily slapped into the homepage, so let's not :D
Collaborator
|
PR Review: Structural & Information Architecture Adjustments Thanks for again for working on this @HarshCasper and helping us keep improving our agentic readiness in docs! Adding a summary here of what we discussed today offline... The current page structure (homepage updates) is inverted because it asks users to choose a product line before explaining what LocalStack is. We need to align the layout with standard progressive disclosure principles. Here is what needs to be updated and why:
Target Page Sequence:
I will now reorder these components to match this flow, and add a commit w/ the fixes. @HarshCasper |
Lead with "What is LocalStack?" and "Who is LocalStack for?" above the fold, move the product-choice hero/cards below that context, drop the redundant "Where to go next" section, and turn the AI-agent pointer into a note callout next to the product cards.
Collaborator
|
Pushed
|
Collaborator
|
Already much better experience: Next, I'm taking a quick look at the homepage content. I want to make it concise where possible while retaining the new value. |
Collaborator
|
@HarshCasper @remotesynth wty, thoughts? What if we update harsh's new suggested content in the homepage for a slightly more concise version, like below? Let me know if you think it's strips away value to the reader/too brief. Welcome to LocalStack Docs What is LocalStack? Use your existing SDKs, CLIs, and IaC tools (CDK, Terraform, Pulumi). Code that runs against LocalStack deploys to the real cloud without changes. It is designed purely for development and test workloads, giving you instant feedback loops with zero cloud costs or provisioning delays. Who is LocalStack for?
|
Collaborator
|
hey @HarshCasper brian just noticed a tiny css font centering problem in the last paragragh 
|
Apply the more concise rewrite proposed in PR review discussion, trimming both sections roughly in half while keeping the core claims.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improves how
docs.localstack.cloudpresents itself to AI agents and crawlers,following an Is-Agentic readiness audit that scored the
site 59/100. The site is a static Astro + Starlight build on Cloudflare Pages, so
every change here is a static-file or build-time change — no runtime or
architecture change, and the existing hero/product-card visual design is
preserved.
Changes (mapped to audit items)
src/content/docs/404.mdoverrides Starlight's default 404. Cloudflare Pages serves it with a real HTTP 404, and the body gives humans and agents recovery links: docs home + product sections, plus a dedicated "For AI agents" section pointing at the sitemap,llms.txt,llms-full.txt,agents.md, and the API catalog.description. Hero and product cards are unchanged.@graph—Organization+WebSite+SoftwareApplication.Organizationnode includescontactPoint(support@localstack.cloud) and aPostalAddress(LocalStack GmbH, Zurich).og:image/twitter:imageadded site-wide using the official LocalStack social card.canonical,html lang, andog:typewere already present.agents.mdandllms.txt(via thedetails+optionalLinksplugin options), naming best-fit use cases and how to call LocalStack from an agent.Vary: Accept, Accept-Encodingadvertised via_headers. FullAccept-header negotiation needs a Pages Function (see below) and is intentionally out of scope for this pure-static change.The links validator config gains an
excludelist for the generated/staticresources linked from the 404 page (
llms*.txt,sitemap-index.xml,agents.md,.well-known/**) so the build stays green.Verification
npm run build(Node 22.12.0) — success, 401 pages, "All internal links are valid".dist/: JSON-LD parses with all three nodes and the required Organization fields;og:image/twitter:imagepresent; 404 recovery links present;Vary: Acceptheader present; when-to-use text inagents.mdandllms.txt;.well-knownJSON valid.Deferred — need an infrastructure or product decision (not in this PR)
Accept-header content negotiation — a departure from the current pure-static architecture. Biggest remaining score lever if approved./about,/contact): these live onwww.localstack.cloud; not duplicated on the docs subdomain.