Rework docs

.cursor/agents/flatbread-architecture-planner.md

@@ -27,7 +27,7 @@ Return:
 - Validation plan.
 - Open questions and human checkpoints.
 
-Keep recommendations aligned with `flatbread-flow-pmf-audit.md` and `flatbread-flow-agentic-workflows.md`.
+Keep recommendations aligned with `internal/flatbread-flow-agentic-workflows.md`.
 
 ## Output Schema For DAG Handoff
 

.cursor/skills/flatbread-major-migration/SKILL.md

@@ -64,7 +64,7 @@ Treat breaking work as a coordinated monorepo release across `flatbread`, `@flat
 
 ## Default DAG Shape
 
-When this skill is run under the external Oven CLI (`@flatbread/oven` from https://github.com/FlatbreadLabs/oven), use the topology in `flatbread-flow-agentic-workflows.md` ("DAG Topology" section). The canonical schema-migration shape — express the DAG via `depends_on` only; the runner computes ranks via Kahn topo-sort. The shape below is what `pnpm exec oven --init-only` produces for the starter template (21 tasks across 7 ranks):
+When this skill is run under the external Oven CLI (`@flatbread/oven` from https://github.com/FlatbreadLabs/oven), use the topology in `internal/flatbread-flow-agentic-workflows.md` ("DAG Topology" section). The canonical schema-migration shape — express the DAG via `depends_on` only; the runner computes ranks via Kahn topo-sort. The shape below is what `pnpm exec oven --init-only` produces for the starter template (21 tasks across 7 ranks):
 
 ```
 rank 1  diag-schema, diag-resolvers, diag-types, diag-codegen, diag-cli,

.flatbread-proof/findings/fnd-comparison-page-now-matches-shipped-watch-and-va--bkat8y0abty4pvcz.md

@@ -0,0 +1,23 @@
+---
+id: fnd-comparison-page-now-matches-shipped-watch-and-va--bkat8y0abty4pvcz
+effort: eff-relational-content-foundation--8a8332x4cazgf2k0
+title: Comparison page now matches shipped watch and validation
+kind: retrospective
+created_at: '2026-08-23T09:05:17.857Z'
+derives_from:
+  - fnd-reference-integrity-is-roadmap-critical--2ss712xpmsfh77xf
+supersedes:
+  - fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe
+---
+
+The comparison page previously understated watch and configured-ref checks. This PR rewrote `docs/comparison.md`, so those gaps no longer hold. The old Finding was true of the PMF rubric; the rewrite is the refresh its Implication asked for.
+
+## Evidence
+
+- `docs/comparison.md` rates local development **Medium–Strong** and says `flatbread start --watch` reloads valid content and config. Package code and app refresh still need their own rebuild or restart.
+- The same page rates configured `refs` **Strong** and says loading checks for duplicate IDs, missing targets, and invalid reference values run before schema build.
+- `docs/local-dev-loop.md` and `packages/flatbread/src/cli/index.ts` still document `start --watch` as the supported path.
+
+## Implication
+
+The buyer-facing comparison page now matches shipped watch and configured-ref validation. Later agents should not treat this as an open docs gap.

.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md

@@ -7,11 +7,13 @@ created_at: '2026-07-19T01:30:56.615Z'
 derives_from:
   - fnd-reference-integrity-is-roadmap-critical--2ss712xpmsfh77xf
   - fnd-unified-watch-loop-is-the-intended-runtime-contr--t9ghag8yqxgf3p5t
+superseded_by:
+  - fnd-comparison-page-now-matches-shipped-watch-and-va--bkat8y0abty4pvcz
 ---
 
 ## Evidence
 
-- `docs/pmf-decision-rubric.md` describes reliable content hot reload as not yet a pillar and treats ordinary content edits requiring a full restart as a no-go signal.
+- `docs/comparison.md` describes reliable content hot reload as not yet a pillar and treats ordinary content edits requiring a full restart as a no-go signal.
 - `docs/local-dev-loop.md` documents `flatbread start --watch` as the supported unified path: valid content/config edits hot-swap the GraphQL schema without restarting the framework.
 - `packages/flatbread/src/cli/index.ts` exposes `start --watch`, and live-server tests cover filesystem watch to schema hot-swap.
 - The same rubric describes configured reference integrity as uneven and suggests silent query-time null chains, while `validateRecords` runs before schema generation and reports duplicate IDs, missing targets, and invalid reference shapes.

docs/pmf-decision-rubric.md → docs/comparison.md

@@ -1,7 +1,7 @@
 # Comparing Flatbread with other tools
 
-This page helps explain where Flatbread fits. It compares Flatbread with tools
-that people often consider for the same job.
+This page compares Flatbread with tools people often consider for the same job,
+so you can decide whether it fits your project.
 
 **Flatbread in one sentence:** it turns related content files in a TypeScript
 project into data your app can read. GraphQL and codegen are common ways to
@@ -27,9 +27,9 @@ Each column describes a group of tools, not every product in that group.
 | **Local development**          | **Medium–Strong** — `flatbread start --watch` reloads valid content and config changes. Package code and app refresh behavior still need their own rebuild or restart. | **Strong** — local databases and migration tools are well established. | **Varies** — offline work and previews depend on the provider.                          | **Medium–Strong** — many tools rebuild when files change.                             | **Strong for saving files** — structured data updates need extra tooling.                        |
 | **Reading data from an agent** | **Medium** — GraphQL and generated TypeScript can read related data; more direct agent tools are still developing.                                                     | **Strong** when the agent can use SQL safely.                          | **Medium** — HTTP APIs work, but authentication and rate limits add steps.              | **Medium** — build-time access is simple; asking new questions at run time is harder. | **Weak–Medium** — search is common, but structured filtering is less common.                     |
 
-## What to emphasize
+## When to choose Flatbread
 
-| If someone is comparing Flatbread with…    | Explain that Flatbread offers…                                                                                                         |
+| If you are coming from…                    | Flatbread gives you…                                                                                                                   |
 | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
 | **SQLite or Postgres**                     | Content files that stay in Git and can be reviewed in pull requests. It does not replace database transactions or many-writer systems. |
 | **Notion, Contentful, or Sanity**          | Repository ownership and file-based content instead of a hosted editing service.                                                       |

docs/data-ownership.md

@@ -1,6 +1,6 @@
 # Data ownership and exit story
 
-Flatbread's portability story starts with a simple constraint: **your flat files
+Flatbread's portability rests on one constraint: **your flat files
 remain the source of truth**. Markdown, YAML, and any other source files live in
 your repository, move through normal Git workflows, and can be reviewed without
 a hosted dashboard.
@@ -52,8 +52,8 @@ const csv = await exportCollectionsAsCsv(configResult, {
 ```
 
 Both exports validate the content graph before returning output. Broken refs or
-duplicate IDs fail before snapshots are produced, which keeps the export story
-aligned with Flatbread's relational integrity work.
+duplicate IDs fail before snapshots are produced, which keeps exports
+consistent with the validated content graph.
 
 See [snapshot export docs](./json-export.md) for sort order, path behavior,
 relation handling, and CSV flattening details.
@@ -66,10 +66,9 @@ Flatbread server is running, standard GraphQL tooling can introspect
 GraphQL documents and generated TypeScript operation types are useful migration
 artifacts because they show the read shapes your app depended on.
 
-If you leave Flatbread, the prototype generated read API should be treated as a
-convenience wrapper to replace or reimplement; the raw files, JSON/CSV
-snapshots, GraphQL operation documents, and operation result types are the more
-durable exit surfaces.
+If you leave Flatbread, treat the generated read API as a convenience wrapper
+to replace or reimplement; the raw files, JSON/CSV snapshots, GraphQL operation
+documents, and operation result types are the more durable exit surfaces.
 
 ## What Flatbread does not lock in