docs: align modernization developer guidance

Objective: remediate documentation and DX smells from the adversarial proof audit.

Rationale: CONTRIBUTING still told developers to use Node 16+, omitted the pinned pnpm/Corepack path, described Vitest as the dominant runner, and did not mention the new pnpm verify command. The Flatbread package README linked to the old playground path and contained a broken fieldNameTransform example.

Migration notes: contributor guidance now reflects Node 20.19+, pnpm 10.33.x, root AVA plus package-local Vitest behavior, Prettier as the enforced lint gate, and pnpm verify for local CI parity.

Rollback: revert this commit to restore the prior docs only. No runtime code or package metadata changes are included.
Change-Id: I37b2abadd3433fb0d2145c2db64b4a0b9730f917

Author: cursoragent

CONTRIBUTING.md

@@ -4,8 +4,8 @@ Thanks for your interest in contributing! This guide covers local development an
 
 ## Prerequisites
 
-- Node 16+
-- pnpm
+- Node 20.19+
+- pnpm 10.33.x via Corepack (`corepack enable && corepack prepare pnpm@10.33.0 --activate`)
 - Clean git working tree (commit/stash your work first)
 
 ## Local development
@@ -14,6 +14,7 @@ Thanks for your interest in contributing! This guide covers local development an
 - Build all packages: `pnpm build`
 - Run dev across packages: `pnpm dev`
 - Work in examples (Next.js preferred): `pnpm play`
+- Check local CI parity before opening a PR: `pnpm verify`
 
 ## Working on a package
 
@@ -42,12 +43,19 @@ pnpm build
 
 - Keep PRs small and focused; link related issues.
 - Ensure CI passes all checks.
+- Run `pnpm verify` locally when your change touches source, tests, package metadata, or CI.
 - Add test coverage for both positive and negative cases:
   - Positive: expected success paths and typical inputs.
   - Negative: invalid inputs, edge cases, and error handling/failure modes.
-- Place tests in the relevant package and use its existing runner/config (Vitest in most packages; some legacy tests use Ava).
+- Place tests in the relevant package and use its existing runner/config.
+  - Root `pnpm test` builds the workspace, runs the AVA suite configured by `ava.config.js`, then runs the package-local Vitest suites.
+  - Vitest is currently used by `@flatbread/codegen` and `@flatbread/utils`.
+  - Most other packages are covered by the root AVA suite or do not yet expose a package-local `test` script.
+- `pnpm lint` is the enforced Prettier formatting gate. `pnpm lint:eslint` is an optional/manual root ESLint check until the linting stack is modernized.
 - Helpful commands:
-  - All packages: `pnpm -r test`
+  - Local CI parity: `pnpm verify`
+  - Root test suite: `pnpm test`
+  - Package-local test scripts where present: `pnpm -r --if-present test`
   - Single package: `pnpm -F <package-name> test`
   - Watch (where supported): `pnpm -F <package-name> test:watch`
 

docs/tooling-modernization.md

@@ -75,7 +75,29 @@ Rollback:
 - Revert `.github/workflows/pipeline.yml`. The local scripts from the previous
   entry remain independently useful.
 
-### 3. Decision record and deferred follow-ups
+### 3. Config hygiene from adversarial audit
+
+Objective:
+
+- Remove pnpm configuration that package manifests cannot enforce.
+- Make workspace path aliases and example package metadata explicit.
+
+Rationale:
+
+- `pnpm.peerDependencyRules` only applies from the workspace root, so package
+  local copies in `@flatbread/codegen` and `flatbread` created warning noise
+  without changing install behavior.
+- The Next.js example invoked the `flatbread` CLI without declaring the
+  workspace dependency it relies on.
+- Root path aliases should cover workspace packages consistently for editor and
+  package-local TS config consumers.
+
+Rollback:
+
+- Revert the config hygiene commit to restore the previous package metadata,
+  path aliases, and lockfile entries.
+
+### 4. Decision record and deferred follow-ups
 
 Objective:
 
@@ -127,6 +149,7 @@ Recommended future pilot:
 Measured locally in this cloud workspace:
 
 - Proof audit DAG: 5/5 tasks completed in about 1 minute 9 seconds.
+- Adversarial follow-up DAG: 5/5 tasks completed in about 55 seconds.
 - Updated `@flatbread/codegen` + `@flatbread/utils` builds completed in about
   4 seconds after the package-local TS configs were added.
 - `pnpm typecheck` for the current proof pilot completed in about 2.5 seconds.
@@ -144,7 +167,8 @@ CI impact must be measured from GitHub Actions after merge or on the draft PR:
 ## Deferred recommendations
 
 - Migrate or remove dormant root ESLint in a dedicated linting PR.
-- Unify AVA and Vitest, or document why both remain necessary.
+- Unify AVA and Vitest after deciding whether package-local tests should all
+  move to Vitest, or keep both with the contributor guide's current split.
 - Add package-level `typecheck` scripts and move toward project references or a
   monorepo `tsc -b` flow.
 - Add coverage collection and thresholds around critical paths after test runner
@@ -153,3 +177,5 @@ CI impact must be measured from GitHub Actions after merge or on the draft PR:
   Express-GraphQL separately from this tooling stack.
 - Confirm whether `@nrwl/workspace` is still used; remove it in its own PR if
   it is dead weight.
+- Resolve the existing SvelteKit route data typing issue, then add
+  `svelte-check` to CI.

packages/flatbread/README.md

@@ -18,7 +18,7 @@
 
 Eat your relational markdown data _and query it, too,_ with [GraphQL](https://graphql.org/) inside damn near any framework (statement awaiting peer-review).
 
-If it runs ES Modules + Node 16+, it's down to clown.
+For contributing to this monorepo, use Node 20.19+ with pnpm 10.33.x. Runtime support for published packages is tracked by each package's own metadata.
 
 Born out of a desire to [Gridsome](https://gridsome.org/) (or [Gatsby](https://www.gatsbyjs.com/)) anything, this project harnesses a plugin architecture to be easily customizable to fit your use cases.
 
@@ -251,7 +251,7 @@ Limits the number of returned entries to the specified amount. Accepts an intege
 
 ## Query within your app ❓❓
 
-[Check out the example integrations](https://github.com/FlatbreadLabs/flatbread/tree/main/playground) of using Flatbread with frameworks like SvelteKit and Next.js.
+[Check out the example integrations](https://github.com/FlatbreadLabs/flatbread/tree/main/examples) of using Flatbread with frameworks like SvelteKit and Next.js.
 
 ## Field overrides
 
@@ -304,7 +304,7 @@ Accepts a function which takes in field names and transforms them for the GraphQ
 {
   ...
   // replace all spaces in field names with an underscore
-  fieldNameTransform: (fieldName) => field.name.replace(/\s/g,'_')
+  fieldNameTransform: (fieldName) => fieldName.replace(/\s/g, '_')
   ...
 }
 ```