[blog] Add post on agent-friendly Markdown registry docs

[fnune]

Announce the five public Pulumi Cloud registry documentation endpoints
(/readme, /installation, /nav, /docs/{token}, /examples),
their Markdown response format with size savings over JSON, the Link: ...; rel="alternate" advertisement on JSON responses, and the pulumi api docs hint that pulumi package add now emits when it detects an
AI coding agent. Targets publish on 2026-05-19.

Also swap --format=markdown to --output=markdown (and --format=json
to --output=json) in content/docs/iac/cli/cloud-api.md and
layouts/index.llms.txt to match the pulumi api flag rename in
pulumi/pulumi#23072. The post relies on the new
flag name; the existing docs and llms.txt copies were stale.

Test plan

• make lint passes
• make serve renders the post at /blog/agent-friendly-registry-docs-api/
• URLs and pulumi api examples in the post were verified against the
  live api.pulumi.com (public packages, no auth needed) and against a
  local build of pulumi/pulumi master (v3.238.0-dev), including Link:
  header presence, Cache-Control: immutable on resolved versions,
  content negotiation behavior, and the two token-encoding forms

[claude]

Docs Review — PR #18923

Solid post overall: tight prose, concrete examples, useful size-savings table, and the social/meta block is fully filled in. A few items to address before publish.

Issues

1. Command-name inconsistency: pulumi api vs pulumi cloud api

The blog uses pulumi api throughout (lines 28, 34, 52, 56, 60, 63, 85–88, 91, 104, 141), but it links the first mention to /docs/iac/cli/cloud-api/ — that page is titled "Calling the Cloud API" and uses pulumi cloud api everywhere. The two files in this same PR (content/docs/iac/cli/cloud-api.md, layouts/index.llms.txt) also keep pulumi cloud api. If the command was renamed alongside the --format → --output change, the docs page and llms.txt need to be updated to match the blog. If not, the blog should use pulumi cloud api. Either way, blog + docs + llms.txt need to agree.

2. Title exceeds 60 chars (currently 64)

content/blog/agent-friendly-registry-docs-api/index.md line 2 — "Agent-Friendly Markdown Docs for Pulumi Providers and Components" is 64 characters. Either shorten or opt in with allow_long_title: true.

title: "Agent-Friendly Markdown Docs for Pulumi Providers and Components"
allow_long_title: true

3. Links to a (likely) private repo

Two links point at pulumi/pulumi-service, which is a private repository — external readers will see 404:

• Line 139: [small shared helper](https://github.com/pulumi/pulumi-service/blob/master/cmd/service/api/rest/negotiate.go) — either drop the link or point to a public surface that describes the negotiation behavior.
• Line 143: [GitHub](https://github.com/pulumi/pulumi-service/issues) — the closing CTA. Point this at pulumi/pulumi or pulumi/docs so external readers can actually file an issue.

4. Fenced code blocks missing language specifiers

The blog review criteria require a language tag on every fenced block:

• Line 38–40 (URL prefix): use text
• Line 82–89 (CLI output): use text (or console)
• Line 135–137 (Link: header): use http (or text)

5. First mention of named tools is not linked

Line 80: "Claude Code, Cursor, Codex, Aider" — first mentions of tools/products should be hyperlinked. Suggest linking each, or rephrase to "AI coding agents like…" and link only the ones the team explicitly wants to call out.

6. Sentence fragment

Line 45: "installation and configuration guide. 404 when the package doesn't ship one." — the second sentence has no subject.

- [`/installation`](/docs/reference/cloud-rest-api/registry/#get-apiregistrypackagessourcepublishernameversionsversioninstallation): installation and configuration guide. Returns 404 when the package doesn't ship one.

Minor

• Line 34: "available in Pulumi CLI v3.238.0 and later" — confirm 3.238.0 is the released version readers will get from pulumi update; the PR description references v3.238.0-dev.
• Line 80: "Aider, and so on" — consider replacing "and so on" with "and others" for tone, or drop the trailing phrase.
• Line 93: "private and community packages get their actual canonical path, not a hardcoded pulumi/pulumi" — the prior paragraphs all use pulumi/pulumi/random URLs, so this contrast may read as confusing. A one-line example of a non-pulumi/pulumi source (e.g. a community package URL) would make the point land.
• Line 116–123: nice table. Consider adding a one-line caption noting whether "Tokens saved" was measured by character count, byte count, or actual tokenizer output — readers will assume LLM tokens given the framing.
• Line 125: ?lang= appears twice in one sentence ("?lang=typescript" and "?lang= filtering"); fine, just calling it out for readability.

Publishing-readiness checklist

• social: block present with twitter, linkedin, bluesky
• meta_image: meta.png set
• Verify meta.png uses current Pulumi logos (can't check from CI)
• <!--more--> break present after intro (line 30)
• Author idp-team exists (data/team/team/idp-team.toml)
• Links to pulumi/pulumi-service need to be fixed (private repo)
• Code examples need language specifiers on three blocks
• No animated GIFs
• No screenshots requiring borders
• Title is 64 chars — either trim or set allow_long_title: true

---

Mention @claude if you'd like another pass after edits or want me to dig into anything specific.