docs: publish Flatbread positioning

[tonyketcham]

Summary of changes

Completes the Flatbread project-board stack through #169:

• Product/docs/experiments: positioning, glossary, PMF rubric, command guidance, canonical quickstart, relation-first narrative, GraphQL-vs-TypeScript read interface guidance, local dev loop boundaries, edit-file/query-update demo, snapshot export docs, data ownership/exit story, starter benchmark, TypeScript safety experiment, export trust experiment, artifact retrieval benchmark, and validation-driven roadmap.
• Agent artifact experiments: Effort Graph wire-up, adversarial multi-layout schema test, and retrieval leverage benchmark.
• Core integrity/type safety: normalized ID semantics, missing-reference validation, duplicate-ID diagnostics, relation cardinality coverage, validation diagnostic snapshots, narrowed core content type surfaces.
• Codegen/API: generated Flatbread content model types and prototype generated TypeScript read API alongside GraphQL, exercised by the Next.js example.
• Portability: stable JSON collection export API and flat CSV collection export API.

Closes #142
Closes #143
Closes #144
Closes #145
Closes #146
Closes #147
Closes #148
Closes #149
Closes #150
Closes #151
Closes #152
Closes #153
Closes #154
Closes #155
Closes #156
Closes #157
Closes #158
Closes #159
Closes #160
Closes #161
Closes #162
Closes #163
Closes #164
Closes #165
Closes #167
Closes #168
Closes #169

Testing

• pnpm build
• pnpm lint
• pnpm test:ava
• pnpm -F @flatbread/codegen exec vitest run
• pnpm --filter nextjs exec flatbread codegen --clear-cache --verbose
• pnpm --filter nextjs build
• pnpm --filter nextjs run demo:watch-query with demo:edit/demo:restore
• Fresh-worktree starter benchmark completed in 49s; generated read API build verification completed in 18s.
• Issue-scoped proof DAGs completed through dag-flatbread-165-roadmap-review-r2.

Notes

mergify stack push failed with the integration token (HTTPError 403 from /user), so commits were pushed to the agent branch and this draft PR was updated manually.

  

[cursor]

Stale comment

I found 3 issues worth fixing before merge:

1. packages/codegen/README.md now shows a GraphQL example against posts { content }, but the schema and checked-in example operations in this repo use allPosts { _content { ... } }, so the primary codegen usage snippet will fail if readers copy/paste it.
2. docs/pmf-decision-rubric.md still says broken refs “silently” degrade results and that there is no credible export story, which contradicts the validation and export surface this same PR adds elsewhere.
3. examples/nextjs/README.md understates what the watch-demo scripts mutate; they also edit YAML author data and refs, not just the post title.

Assumption: reviewed against merge-base 49fba33903795214ed8f32d93f16d7cefa6bf8cb.

Change summary: the runtime/reference/export changes looked internally consistent on this pass; the blockers I found are documentation contradictions or copy-paste breakage.

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

This example no longer matches the schema Flatbread actually generates in this repo. The checked-in example documents use allPosts, and markdown bodies live under _content rather than content (see examples/nextjs/queries/posts.graphql). As written, a reader following the new codegen README will get a validation error from the first copy/pasted query.

[cursor]

These bullets are stale relative to the code/docs being introduced in the same PR. packages/core/src/providers/test/references.test.ts now covers missing refs failing before schema use, and docs/json-export.md documents the new JSON/CSV export story backed by packages/core/src/export/json.ts / csv.ts. Leaving silently degrade and no credible ... export story here makes the rubric contradict the rest of the positioning docs you just published.

[cursor]

The scripts table understates what this demo loop actually changes. demo-edit.mjs / demo-restore.mjs also mutate content/yaml/authors/dr-caffeine.yml (author name + friend ref), and watch-content-query.mjs watches both that YAML file and the Markdown post. Someone following the README to understand the expected output will be surprised when author/friend fields change too.

[cursor]

Stale comment

Found 1 correctness issue in the new export path.

I reviewed the merge-base diff and spot-checked the runtime changes with focused tests (pnpm exec ava ... for the touched @flatbread/core areas and pnpm -F @flatbread/codegen exec vitest run ... for the codegen changes). Those suites passed, but the exporter still has a snapshot-consistency bug called out inline below.

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

exportCollectionsAsJson() validates one snapshot and then serializes a second one. generateSchema(configResult) fetches/transforms content and validates IDs/refs, but after that we call config.source.fetch() again and export the second fetch.

That breaks the contract this PR documents for validated, deterministic snapshots: if a source plugin is nondeterministic or the content changes between those two awaits, export can succeed while returning data that was never validated. I reproduced this with a custom source whose first fetch returned a valid Post -> Author ref and whose second fetch returned author: "missing-author"; exportCollectionsAsJson() still returned the broken ref without throwing.

Please export the same transformed/validated node set that schema generation checked (or factor validation into a shared single-fetch pipeline) so the returned JSON/CSV snapshot is actually the validated snapshot.

[cursor]

Stale comment

Found 4 still-open issues on the current head.

• High: packages/core/src/export/json.ts still validates one content snapshot and serializes a second fetch, so the new JSON/CSV export APIs can return data that was never validated.
• Medium: packages/codegen/README.md still shows a copy-paste GraphQL example that does not match this repo’s generated schema (allPosts / _content vs posts / content).
• Medium: docs/pmf-decision-rubric.md still contradicts the same PR’s runtime/docs changes by claiming refs silently degrade and there is no credible watch/export story.
• Low: examples/nextjs/README.md still understates the demo loop; the helper scripts also edit and watch the YAML author file and change the friend ref.

I did not find additional correctness regressions beyond those existing open threads.

Validation run on this head:

• pnpm -F @flatbread/codegen exec vitest run
• pnpm test:ava -- --match='*reference*' --match='*ID*' --match='*Sift*'
• pnpm --filter nextjs build
• pnpm build

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

Stale comment

No review findings in the current PR state.

I reviewed the branch against the origin/main merge base and spot-checked the highest-risk areas in packages/core, packages/codegen, examples/nextjs, and the new docs/runtime guidance. I also ran:

• pnpm build
• pnpm -F @flatbread/codegen exec vitest run
• pnpm test:ava -- --match='*content types*'
• pnpm --filter nextjs build
• pnpm exec flatbread start -- next dev --turbopack from examples/nextjs, plus a live POST to http://localhost:5057/graphql and a fetch of http://localhost:3000

Residual risk:

• I did not run the full pnpm verify stack or exhaustive browser automation across every new docs path.
• pnpm --filter nextjs build still logs an ESLint plugin warning about eslint-plugin-react-hooks in this environment, although the build completes successfully and the app/runtime checks passed.

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

Found 2 issues that look worth fixing before merge:

• The new generated read API types over-promise nested relation data relative to the default selection generator, so FlatbreadRelationTarget is unsound for relation fields that contain nested objects.
• The updated Next.js example quickstart points users at http://localhost:3000, but one of the two documented startup paths (pnpm dev) actually serves the app over HTTPS.

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

FlatbreadRelationTarget is generated as the full target record here, but the default selection builder below only descends one object level. In the checked-in example that means flatbreadRead.Post.all() returns authors without nested fields like friend, image, or skills, even though FlatbreadRelationTarget<'Post', 'authors'> is typed as ReadonlyArray<Author | null> | null. A consumer can therefore write against author.friend.name and pass typecheck, then get undefined at runtime because those fields were never queried. Can we make relation results deep-partial (or otherwise tie them to the generated selection depth) before exposing this API?

[cursor]

Step 4 documents both pnpm exec flatbread start -- next dev --turbopack and pnpm dev, but pnpm dev runs flatbread start --https -- next dev --turbopack. Pointing step 5 at http://localhost:3000 is therefore wrong for one of the advertised startup paths and will send users to the wrong scheme during the default self-signed-cert flow. It would be clearer to either use https://localhost:3000 for the pnpm dev path or split the URL guidance by command.