Document GraphQL as one interface over the typed content model

[tonyketcham]

Source: flatbread-flow-pmf-audit.md

Project metadata

• Phase: Type-safe consumption APIs
• Sequence: 14
• Priority: P1
• Suggested owner role: docs
• Supporting roles: DX
• Dependency status: blocked
• Blocked by: Publish focused positioning statement and non-goals #142 Publish focused positioning statement and non-goals; Prototype generated TypeScript read API alongside GraphQL #154 Prototype generated TypeScript read API alongside GraphQL

Task details

• Clarify where GraphQL fits once the typed content model and generated TypeScript read API are in place.
• Help users choose the right interface based on app needs rather than framing GraphQL as the product itself.

Acceptance criteria

• Docs explain when to use GraphQL versus the generated TypeScript API.
• GraphQL is described as an interface over the typed model.
• Examples connect back to the canonical posts/authors/tags quickstart.

[tonyketcham]

This follow-up is based on changes in PR #177.

• Landed: the GraphQL-vs-generated TypeScript interface-choice narrative is present.
• Still remaining: \ and \ still point readers at broken quickstart/read-interface anchors instead of linking to the canonical sections in .

Next step: update those back-links so readers flow from the example/codegen docs into the canonical interface-choice + quickstart sections in .

[tonyketcham]

Reposting with corrected Markdown formatting (backticks previously rendered incorrectly).

This follow-up is based on changes in PR #177.

• Landed: the GraphQL-vs-generated TypeScript interface-choice narrative is present.
• Still remaining: examples/nextjs/README.md and packages/codegen/README.md still point readers at broken quickstart/read-interface anchors instead of linking to the canonical sections in packages/flatbread/README.md.

Next step: update those back-links so readers flow from the example/codegen docs into the canonical interface-choice + quickstart sections in packages/flatbread/README.md.