docs: lead with the agent-native claim; skills first, Modules as building blocks

[wmadden-electric]

The docs never made the central claim: Composer is the fastest, most reliable way to build an app with your agent — scratch to deployed on Prisma Cloud in minutes. They read as a framework reference that happened to ship a skill near the bottom. This puts the claim first and updates the skill to match.

What changed

README opens with the claim, and installing the skill becomes the first step rather than a footnote. It names the three properties that make an agent-built app actually run, instead of just asserting agent-friendliness:

• Modules snap together — a capability arrives as a Module owning its internals behind a typed port, so it's composition, not an integration the agent invents.
• Everything is typechecked — a wrong wire, a missing handler, a bad config shape fails tsc in seconds, not a deploy ten minutes later.
• Deploys are deterministic — one command, no infrastructure config to hallucinate, re-runs converge.

getting-started now opens with the skill install (including why to do it even if you plan to write every line yourself), then frames the manual walkthrough as "the point of what follows is that you can read what your agent writes."

building-an-app reframes the shared modules as the building blocks you compose instead of reimplementing, and documents where new ones come from.

The skill gets the same treatment from the agent's side: compose before you write, typecheck before reaching for the cloud, and the building-block catalogue is now explicitly "small, and growing."

The prisma-composer-* convention, stated honestly

An extension is an npm package named prisma-composer-*. Nothing matches that name today, so the docs present it as the place to look, not a catalogue that already has what you need — and the skill explicitly tells the agent not to reach for a prisma-composer-* package without checking npm first. That guard is deliberate: the whole failure mode this skill exists to prevent is an agent confidently importing an API that doesn't ship.

Verification

• Every relative link and intra-guide anchor script-checked; lint:framework-vocabulary clean.
• Skill self-containment holds — no link escapes skills/prisma-composer/; folder and frontmatter names still match.
• No claim added about surface that doesn't ship: the three Modules are the real ones, the install command is the real one, and the extension ecosystem is described as empty-but-conventional rather than populated.

Note

The docs site (#95) renders docs/guides/ at build time, so it picks these guide changes up automatically once both land. Its hand-authored landing-page hero still carries the older framing — I'll update that on the #95 branch so the site leads with the same claim.

🤖 Generated with Claude Code