Rework docs

[tonyketcham]

What changed

1. Trim — deleted internal-only docs.
2. Rewrite — renamed pmf-decision-rubric.md → comparison.md; rewrote internal-staff language for end-users.
3. Fix refs — repaired every dangling link repo-wide.

What's gone

• docs/edit-file-see-query-update-demo.md — issue Ship edit-file-see-query-update demo #158 repro harness, not the production flatbread start path.
• docs/experiments/ — starter benchmarks (Benchmark canonical starter path to first typed read result #162), TS safety tests (Run TypeScript safety interview/test #163), export-trust (Run export trust self-review demo #164), Effort-Graph layout (Document representative Effort Graph reference-layout mapping #167), adversarial schema (Document three-layout Effort Graph schema mapping #168), retrieval benchmark (Benchmark representative artifact-byte reduction for blocking-decision retrieval #169), plus DAG fixtures and issue drafts.
• docs/research/performant-context-search/ — internal /proof DAG methodology README.
  ~1,200 lines removed.

What's kept (6 end-user docs)

File	For
glossary.md	collections, records, refs, relations, IDs, validation
positioning.md	what Flatbread is and isn't; Proof + relational-content use cases
comparison.md	Flatbread vs SQL DBs, hosted CMSs, build tools, note tools
data-ownership.md	what you own + exit paths (raw files, Git, JSON/CSV, GraphQL, types)
json-export.md	exportCollectionsAsJson / exportCollectionsAsCsv API
local-dev-loop.md	flatbread start --watch behavior, reload matrix, limits

Language rewritten (staff → user)

• comparison.md: the "What to emphasize" sales-enablement table ("If someone is comparing Flatbread with… Explain that Flatbread offers…") → "When to choose Flatbread" ("If you are coming from… Flatbread gives you…").
• glossary.md: dropped roadmap notes ("future ID work should…", "Near-term validation work should…", "Any future generated TypeScript reader…"); states current validation behavior.
• data-ownership.md: "portability story starts with a simple constraint" → "portability rests on one constraint"; "relational integrity work" → "validated content graph"; dropped the "prototype" hedge.
• json-export.md: dropped "A future option may…" and "do not yet have a stable flat representation".
• local-dev-loop.md: "prototype read API" → "read API".

Dangling refs fixed

• flatbread-flow-pmf-audit.md → rubric link now ./docs/comparison.md.
• flatbread-search-and-memory-research.md → removed broken links to deleted docs/research/performant-context-search/README.md; reworded (dossiers were never checked in).
• .flatbread-proof/findings/fnd-pmf-rubric-understates… → citation path pmf-decision-rubric.md → comparison.md. Path-only fix; claim unchanged. Flagging because Proof records normally use typed mutations — there is no rename-citation mutation, so I edited the file directly.
• examples/nextjs/README.md → "Full walkthrough" link to the deleted demo doc replaced with the existing demo:restore instruction.

Why

Many docs were written for internal use before Proof shipped. End-users reading docs/ hit benchmarks, issue drafts, and sales-enablement language. This keeps only what helps a user install, understand, and decide.

How to review

Fast path: skim the diffstat (mostly deletions), then read docs/comparison.md and docs/glossary.md in full — those carry the substantive rewrites. The other four kept docs only had a line or two changed each.

Verification

• pnpm lint:fix:fast clean; pretty-quick --staged passed each commit.
• Repo-wide grep for every deleted/renamed path and filename: no matches.
• All kept-doc internal links + external README links resolve to existing files.

---

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• I added doc comments to any new public exports, and inline comments to any hard-to-understand areas — N/A, docs-only PR; no new public exports.
• My changes generate no new console errors locally — N/A, docs-only.
• If applicable, try to include a test that fails without this PR but passes with it — N/A, no behavior change to test.

Does this introduce any non-backwards compatible changes?

• Yes
• No — docs and one README edit only; no code or config touched.

Does this include any user config changes?

• Yes
• No

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[cursor]

Stale comment

Verdict

REQUEST_CHANGES — the path-only Proof finding now states false facts about docs/comparison.md.

Prior notes

None. This PR had no earlier automation threads.

Domain verdicts

• Architecture: COMMENT
• Quality: COMMENT
• Proof journal: REQUEST_CHANGES
• Correctness: COMMENT (same HIGH on the stale finding)

What is fine

• docs/ is now six end-user pages. GraphQL stays one read interface.
• Deleted paths have no remaining live refs.
• Glossary ID/validation, export, and watch claims match packages/core (ids.ts, validate.ts, export JSON, watch coordinator).
• No new Decision is required for the docs/ vs internal/ split. internal/README.md already states it, so unique signal fails.
• Path retarget of the finding is allowed. There is no rename-citation mutation.

Required

Close fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe. This PR already did the refresh the Implication asked for: docs/comparison.md rates local development Medium–Strong with flatbread start --watch, and configured refs Strong with pre-schema checks. The finding still says the opposite.

Write a Finding on eff-relational-content-foundation--8a8332x4cazgf2k0 that the comparison page now matches shipped watch and validation, then Supersede this record. Use Invalidate only if you treat the current sentences as wrong rather than obsolete.

Held

• Root and packages/flatbread READMEs still omit docs/comparison.md (those files are not in this diff).
• examples/nextjs/README.md still calls the generated read API a prototype (those lines are not in the hunk).
• internal/flatbread-flow-agentic-workflows.md still opens as a PMF-audit execution workflow after that dossier was deleted.

Models

• Architecture, proof, correctness: inherit (latest Cursor Grok)
• Quality: composer-2.5
• Oven missing; Task fallback

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

Verdict

APPROVE — the stale comparison Finding is superseded. Kept docs match shipped watch and validation.

Prior notes

Closed the earlier request on fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe. New Finding fnd-comparison-page-now-matches-shipped-watch-and-va--bkat8y0abty4pvcz supersedes it on eff-relational-content-foundation--8a8332x4cazgf2k0. The old body stays as history. That is the right edge.

Domain verdicts

• Architecture: APPROVE
• Quality: COMMENT (wording only; no blocker)
• Proof journal: APPROVE
• Correctness: APPROVE

What is fine

• docs/ is six end-user pages. GraphQL stays one read interface.
• Deleted paths have no remaining live refs. The playbook no longer cites flatbread-flow-pmf-audit.md.
• Glossary ID/validation, export, and watch claims match packages/core (ids.ts, validate.ts, export JSON, watch coordinator) and flatbread start --watch.
• The new Finding scores 4/4. Typed WriteFinding + Supersede; back-edge is materialized. No extra Decision is needed for the docs/ vs internal/ split.

Optional

• examples/nextjs/README.md now says “Restore the files after with pnpm run demo:restore.” Prefer “Afterward, restore the files with…”.
• internal/README.md calls the playbook schema-migration guidance; the playbook also covers docs, CLI, and release gates.

Held

• Root and packages/flatbread READMEs still omit docs/comparison.md (those files are not in this diff).
• examples/nextjs/README.md still calls the generated read API a prototype (those lines are not in the hunk).
• The playbook opening still says “the PMF audit.” The file link is gone, and dag-flatbread-flow-pmf-audit.json still exists.

Models

• Architecture, proof, correctness: inherit (latest Cursor Grok)
• Quality: composer-2.5
• Oven missing; Task fallback

  

_{Sent by Cursor Automation: Flatbread PR Review}