Rewrite main READMEs - #266
Conversation
**Summary of changes** - split the Flatbread start path between Proof agent memory and relational app content - recast Proof as portable, Git-tracked alignment across sessions and coworkers - move corrected filters, pagination, and override details into a query reference ### Please don't delete this checklist! Before submitting the PR, please make sure you do the following: - [x] I added doc comments to any new public exports, and inline comments to any hard-to-understand areas (not applicable: docs only) - [x] My changes generate no new console errors locally - [x] If applicable, try to include a test that fails without this PR but passes with it (not applicable: docs only) ### Does this introduce any non-backwards compatible changes? - [ ] Yes - [x] No ### Does this include any user config changes? - [ ] Yes - [x] No Test plan: - pnpm lint:fix:fast - pnpm lint - verify README commands in scratch projects - check local and external links Change-Id: I487546b09a0390dbccb9da4a4c218bcb092961ba Co-authored-by: Erika Ruth Witt <erikawitt@users.noreply.github.com>
State that read and write commands need a complete proofContent preset while bootstrap reports missing or incomplete setup. Tested with: - pnpm lint:fix:fast - pnpm lint - scratch bootstrap checks for action_required and ready states Change-Id: I7e784d9689e1f16ee2112a3e2a4a31aa3439e48c Co-authored-by: Erika Ruth Witt <erikawitt@users.noreply.github.com>
|
Tick the box to add this pull request to the merge queue (same as
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
REQUEST_CHANGES. The two-path README split is sound, and the query, bootstrap, and CLI claims match packages/core. Two defects should land before merge.
Must fix
packages/proof/README.mdnames the edgederive_from. The writer, planner, and glossary usederives_from. An agent that copies the README field will fail the write.- This rewrite dropped
#quickstart-posts-authors-and-tagsand#choosing-a-read-interface. Those fragments are still linked fromCONTRIBUTING.md,docs/positioning.md,packages/codegen/README.md,examples/nextjs/README.md, and the content READMEs. Restore HTML anchors, or retarget those links to Path 2 / the Next.js example in this PR.
Also fix
docs/query-reference.mdsaysan.array[]maps over every element.query-executortest 15 andfieldOverridestests showresolvegets the whole raw array. Say that.
Held / not blocking
- No Proof journal in this PR. The README itself plus
dec-lead-flatbread-1-0-with-effort-graph-agent-memoralready carry the two-path reason. A new Decision fails unique-signal (same bar as #260 / #261). - Sample pins
v1.1.0/flatbread@1.1.0matchpackages/proof/skills/proof/release.json. Keep the samples; the prose already points at the manifest. - After rebase onto
main(#265), adddocs/comparison.mdto the “Find the next detail” table. Do not link it on this branch: the file is not here. - Path 1 bootstrap is duplicated with the Proof README. Collapse the main README path to a short pitch plus a link if you want less drift later.
- The query reference is GraphQL-only. The prototype TypeScript read API is
all()/find()and does not takefilter/sortBy/skip/limit. Say so when you point codegen readers at that page.
Prior notes closed: none. First review of this PR. No open threads.
Domain verdicts
- architecture: REQUEST_CHANGES (inbound heading IDs; comparison row after rebase)
- quality: REQUEST_CHANGES (same inbound IDs; duplicated Path 1 bootstrap)
- proof-journal: APPROVE (no new record required)
- correctness: REQUEST_CHANGES (
derive_from;an.array[])
Models: architecture, proof-journal, and correctness inherit latest Cursor Grok. Quality is composer-2.5. Oven missing; Task fallback. Judge: /tmp/review-judge-final.md.
Sent by Cursor Automation: Flatbread PR Review
| | **Blob** | Attached content such as a document, JSON payload, or image | | ||
|
|
||
| Typed relations preserve the reasoning between records. A Decision can | ||
| `derive_from` the Findings, Constraints, and Issues it responds to. A Finding |
There was a problem hiding this comment.
This is not a valid Proof edge. The writer, planner, and glossary use derives_from. An agent that copies derive_from into flatbread proof write will fail validation.
Rename this to derives_from.
| authors by id, and Flatbread resolves them. You get versioned, reviewable | ||
| content and joins over files without a CMS database. Start with the | ||
| [Quickstart](#quickstart-posts-authors-and-tags). | ||
| ## Path 2: relational content for apps |
There was a problem hiding this comment.
Path 2 replaces the old #quickstart-posts-authors-and-tags and #choosing-a-read-interface sections, but those heading IDs are gone. These links now 404:
CONTRIBUTING.md(GitHub blob#quickstart-posts-authors-and-tags)docs/positioning.mdpackages/codegen/README.md(both fragments)examples/nextjs/README.md(five links)examples/content/README.md,examples/nextjs/content/README.md,examples/sveltekit/content/README.md
Either add HTML anchors (<a id="quickstart-posts-authors-and-tags"> and choosing-a-read-interface) on this path, or retarget those files to Path 2 / the Next.js example in this PR.
| | Pattern | Meaning | | ||
| | ----------------------- | ------------------------------------------------------ | | ||
| | `nested.object` | A field inside a nested object | | ||
| | `an.array[]` | Map over every element of an array field | |
There was a problem hiding this comment.
an.array[] does not map resolve over each element. getFieldOverrides strips a trailing [] and passes the whole raw array (packages/core/src/utils/tests/fieldOverrides.test.ts, query-executor test 15: “resolves trailing-array overrides against the whole raw array”). The Next.js OverrideTest resolver also calls .map on that array itself.
Say “resolve receives the raw array”. The per-element case is an.array[]with.object.
2 participants
No description provided.