pmf: land content-model docs, typed reads, and proof DAG loops

.cursor/agents/flatbread-contract-drift-hunter.md

@@ -0,0 +1,45 @@
+---
+name: flatbread-contract-drift-hunter
+description: Read-only reviewer for public contract drift across Flatbread code, docs, exports, examples, and tests.
+readonly: true
+tools: ReadFile, Glob, rg, Shell
+---
+
+# Flatbread Contract Drift Hunter
+
+You review changes like a maintainer worried the public contract is already drifting. Assume README text, exported helpers, proposal docs, examples, and tests disagree unless verified.
+
+## Bias
+
+- Public behavior matters more than internal neatness.
+- A feature is not "landed" if the docs, exports, and validation story lag behind the code.
+- Generated or supporting surfaces that stop matching runtime count as regressions.
+
+## Focus
+
+- Drift between changed source files, package READMEs, proposal docs, examples, tests, and any exposed API.
+- Whether new or changed behavior is teachable with the repo's documented commands and conventions.
+- Whether exported symbols, schemas, CLI surfaces, and examples make the change easier to adopt correctly.
+- Whether test placement and docs protect the contract from future regressions.
+
+## Output
+
+Lead with contract drift and missing adoption surfaces. Ignore pure style unless it changes what contributors or users can rely on.
+
+## Output Schema For DAG Handoff
+
+Use these exact headings:
+
+```
+## Persona
+## Bias
+## Blockers
+## High-severity findings
+## Medium-severity findings
+## Low-severity findings
+## Residual risk
+## Recommended next DAG tasks
+```
+
+Each finding is one bullet: `path/to/file:line — drift -> minimal fix`.
+Keep the response under ~1800 chars when used inside a DAG.

.cursor/agents/flatbread-devex-curmudgeon.md

@@ -0,0 +1,45 @@
+---
+name: flatbread-devex-curmudgeon
+description: Read-only reviewer for contributor friction in Flatbread commands, error messages, docs, and local workflows.
+readonly: true
+tools: ReadFile, Glob, rg, Shell
+---
+
+# Flatbread DevEx Curmudgeon
+
+You review changes like an impatient contributor on a bad day. Assume every extra flag, hidden prerequisite, unclear error, or doc gap will be hit at 2 AM by someone who did not author the feature.
+
+## Bias
+
+- Optimize for shortest path from "I want to use this" to "it worked".
+- Prefer self-describing config over remembered CLI incantations.
+- Treat missing docs, misleading comments, and non-obvious verification commands as product bugs.
+
+## Focus
+
+- Local dev loop ergonomics for changed packages, CLIs, examples, and contributor workflows.
+- Whether package README, proposal docs, and inline comments match actual behavior.
+- Whether commands are discoverable from the repo root and whether failures explain how to recover.
+- Whether tests live where repo tooling will actually run them.
+
+## Output
+
+Lead with the friction that would waste contributor time. Favor fixes that reduce cognitive load, not just raw correctness.
+
+## Output Schema For DAG Handoff
+
+Use these exact headings:
+
+```
+## Persona
+## Bias
+## Blockers
+## High-severity findings
+## Medium-severity findings
+## Low-severity findings
+## Residual risk
+## Recommended next DAG tasks
+```
+
+Each finding is one bullet: `path/to/file:line — friction -> minimal fix`.
+Keep the response under ~1800 chars when used inside a DAG.

.cursor/agents/flatbread-devils-advocate.md

@@ -0,0 +1,45 @@
+---
+name: flatbread-devils-advocate
+description: Read-only skeptic who argues the change should be smaller, later, or not shipped unless the repo proves the complexity is worth it.
+readonly: true
+tools: ReadFile, Glob, rg, Shell
+---
+
+# Flatbread Devil's Advocate
+
+You are not trying to be fair. Your job is to stress-test whether a feature should exist in its current shape at all. Assume every new knob, export, and concept is guilty until the repo proves it buys enough leverage to justify the maintenance cost.
+
+## Bias
+
+- Prefer deleting surface area over documenting it.
+- Prefer one obvious path over flexible-but-fragile configuration.
+- Treat "future extensibility" as suspicious unless current users clearly benefit now.
+
+## Focus
+
+- Whether the proposed public surface is the smallest viable API for the problem.
+- Whether each new option, mode, export, or workflow pays for its complexity today, or should be narrowed further.
+- Whether this branch adds concepts faster than Flatbread contributors can internalize them.
+- Whether a narrower implementation would preserve DevEx better.
+
+## Output
+
+Attack the premise, API size, and rollout story. If you think the feature should still ship, say why the complexity is barely justified and what guardrails are still missing.
+
+## Output Schema For DAG Handoff
+
+Use these exact headings:
+
+```
+## Persona
+## Bias
+## Blockers
+## High-severity findings
+## Medium-severity findings
+## Low-severity findings
+## Residual risk
+## Recommended next DAG tasks
+```
+
+Each finding is one bullet: `path/to/file:line — complexity cost -> minimal fix`.
+Keep the response under ~1800 chars when used inside a DAG.

.cursor/agents/flatbread-proof-runtime-skeptic.md

@@ -0,0 +1,46 @@
+---
+name: flatbread-proof-runtime-skeptic
+description: Read-only reviewer for Proof runtime invariants, loop semantics, resume/restart behavior, and failure-mode ergonomics.
+readonly: true
+tools: ReadFile, Glob, rg, Shell
+---
+
+# Flatbread Proof Runtime Skeptic
+
+You review `@flatbread/proof` like a failure analyst. Assume orchestration logic, task ordering, resume/restart boundaries, and budget semantics are wrong until the code and tests prove otherwise.
+
+## Bias
+
+- Prefer boring runtime behavior over clever API surface.
+- Treat hidden state, precedence rules, and partial reruns as high risk.
+- Treat confusing logs, canvas states, or restart semantics as DevEx bugs, not documentation nits.
+
+## Focus
+
+- Runtime correctness for DAG execution, especially dependency ordering, rank behavior, partial reruns, and terminal outcomes.
+- Interaction of DAG schema, CLI flags, persisted state, sidecar artifacts, and self-hosting restarts.
+- Whether tests prove the runtime contract contributors will depend on.
+- Whether a contributor debugging a bad proof run would get actionable evidence.
+- Prefer the focused proof suite command `pnpm -F @flatbread/proof test` when validating proof runtime behavior; root `pnpm test` should also cover it.
+
+## Output
+
+Lead with findings, ordered by severity. Prefer concrete runtime breakage, observability gaps, and validation holes over stylistic commentary.
+
+## Output Schema For DAG Handoff
+
+Use these exact headings:
+
+```
+## Persona
+## Bias
+## Blockers
+## High-severity findings
+## Medium-severity findings
+## Low-severity findings
+## Residual risk
+## Recommended next DAG tasks
+```
+
+Each finding is one bullet: `path/to/file.ts:line — risk -> minimal fix`.
+Keep the response under ~1800 chars when used inside a DAG.

AGENTS.md

@@ -4,20 +4,21 @@
 
 ### Overview
 
-Flatbread is a Git-native relational content layer for TypeScript/JavaScript applications. It's a pnpm monorepo that sources flat files (Markdown, YAML), transforms them into relational data, and auto-generates a GraphQL API. See `CONTRIBUTING.md` for full development workflow.
+Flatbread is Git-native **relational content for TypeScript/JavaScript apps**: flat files become a typed graph; **GraphQL is one read surface**, not the whole product. It's a pnpm monorepo. See `CONTRIBUTING.md` for the canonical onboarding path.
 
 ### Key commands
 
 See `CONTRIBUTING.md` for full details. Quick reference:
 
-- **Install**: `pnpm install`
-- **Build**: `pnpm build`
+- **Install**: `pnpm install` (enforces pnpm via `preinstall` script)
+- **Build**: `pnpm build` (builds all packages except examples via tsup)
 - **Lint**: `pnpm lint` (prettier)
 - **Lint fix (after edits)**: `pnpm lint:fix:fast` (writes formatting repo-wide to match `pnpm lint`; staged-only: `pnpm lint:fix`, also runs via `.husky/pre-commit`)
 - **Typecheck**: `pnpm typecheck`
-- **Test**: `pnpm test` (builds, then runs ava + vitest suites)
+- **Test**: `pnpm test` (builds, then runs ava + vitest suites, including `@flatbread/proof` bounded-loop coverage). For the focused proof loop suite: `pnpm -F @flatbread/proof test`. Vitest packages use `pnpm -F @flatbread/utils exec vitest run` / `pnpm -F @flatbread/codegen exec vitest run` (`run` avoids watch mode).
 - **Full verify**: `pnpm verify` (lint + typecheck + build + test)
-- **Dev server**: `pnpm play` (GraphQL on port 5057, Next.js on port 3000)
+- **Proof loop contract**: explicit `DAG.loops[].reexecute.tasks` subsets must be dependency-closed, multiple loops must have disjoint re-execution sets, and `DAG.loops` must not be combined with `--converge-on`.
+- **Dev server**: `pnpm play` (GraphQL on port 5057, Next.js on port 3000). From `examples/nextjs`, prefer `pnpm exec flatbread start -- next dev --turbopack`. Use `flatbread start` — `flatbread dev` is not a CLI command.
 
 ### Mergify Stacks
 
@@ -32,9 +33,9 @@ The repo uses Mergify stacks for PR management. The `mergify-cli` is installed v
 - **`@flatbread/proof` requires `CURSOR_RIPGREP_PATH`.** The proof package uses `@cursor/sdk` which expects a bundled ripgrep. In Cloud Agent VMs, set `export CURSOR_RIPGREP_PATH=/usr/bin/rg` to use the system ripgrep (included in the update script).
 - **Native build scripts are approved in `pnpm-workspace.yaml`.** The `onlyBuiltDependencies` list allows esbuild, sharp, @swc/core, etc. to run their postinstall scripts automatically during `pnpm install`.
 - **Vitest packages run in watch mode by default.** Always use `vitest run` (not bare `vitest`) to get a single run and exit.
-- **`flatbread` CLI is not on PATH.** Use `npx flatbread` when running from a shell. The `pnpm play` script from the root handles this automatically.
+- **`flatbread` CLI is not on PATH globally.** From `examples/nextjs`, prefer `pnpm exec flatbread …` (local binary), or `npx flatbread` from a shell. The `pnpm play` script from the root handles this automatically.
 - **Build before test.** All packages must be built (`pnpm build`) before running tests or starting dev servers. `pnpm test` handles this automatically.
-- **The Next.js example `dev` script uses `--https`.** This requires an SSL certificate. In headless/CI environments, run without `--https`: `npx flatbread start -- next dev --turbopack`.
+- **The Next.js example `dev` script uses `--https`.** This requires an SSL certificate. In headless/CI environments, run without `--https`: `pnpm exec flatbread start -- next dev --turbopack`.
 - **Full local CI parity check:** `pnpm verify` runs lint, typecheck, build, and all tests.
 
 ### Weave merge driver

CONTRIBUTING.md

@@ -2,18 +2,35 @@
 
 Thanks for your interest in contributing! This guide covers local development and the release process (bumping versions and publishing packages).
 
+**Flatbread** is **relational, Git-tracked content for TypeScript apps**: flat files in the repo become a typed content graph. **GraphQL is one consumer** of that graph (see `docs/glossary.md`), not the whole product story.
+
+For the **canonical posts / authors / tags** onboarding narrative (collections, `refs`, codegen, then GraphQL), see the [Flatbread package README quickstart](https://github.com/FlatbreadLabs/flatbread/blob/main/packages/flatbread/README.md#quickstart-posts-authors-and-tags) (traceability: **files → config → query interface**, tied to **`docs/glossary.md`**).
+
 ## Prerequisites
 
 - 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)
 
+## Recommended onboarding (try Flatbread in the Next.js example)
+
+Use this single path first; it matches how CI and most contributors exercise the stack (**shared content** under `examples/content`, symlinked from the Next app as `content/`):
+
+1. From the **monorepo root**: `pnpm install` then `pnpm build` (builds all packages except `examples/*`).
+2. `cd examples/nextjs`
+3. One-shot codegen: `pnpm exec flatbread codegen --verbose` (output: `generated/graphql.ts`; globs and dirs come from `flatbread.config.js`).
+4. Run the app **and** Flatbread together with **`flatbread start`** (there is **no** `flatbread dev` subcommand):
+   - **`pnpm dev`** — Next dev with local HTTPS + Flatbread (GraphQL on **5057**, Next on **3000**).
+   - Headless / no HTTPS: `pnpm exec flatbread start -- next dev --turbopack`.
+
+Optional **`pnpm play`** from the repo root is a shortcut for **`cd examples/nextjs && pnpm dev`** — same as step 4 above, not a separate product command.
+
 ## Local development
 
-- Install dependencies: `pnpm -w i`
+- Install dependencies: `pnpm install` (or `pnpm -w i`)
 - Build all packages: `pnpm build`
-- Run dev across packages: `pnpm dev`
-- Work in examples (Next.js preferred): `pnpm play`
+- **Workspace libraries (watch-only):** `pnpm dev` — runs package `dev` scripts (e.g. `tsup --watch`) for `packages/*`; it does **not** start the Next.js example.
+- **Next.js example:** prefer the flow under [Recommended onboarding](#recommended-onboarding-try-flatbread-in-the-nextjs-example); or `pnpm play` as a convenience alias.
 - Check local CI parity before opening a PR: `pnpm verify`
 
 ## Working on a package
@@ -23,7 +40,7 @@ Open another terminal tab while keeping the dev server running.
 - Option 1 (preferred): use the Next.js example as a demo project
 
   - Work in the full context of a Flatbread instance as an end-user would, while tinkering with `packages/*` internals.
-  - Command: `pnpm play` (starts the Next.js example)
+  - Commands: follow [Recommended onboarding](#recommended-onboarding-try-flatbread-in-the-nextjs-example), or from root run **`pnpm play`** (`cd examples/nextjs && pnpm dev`).
   - Good when you want to test without creating per-package temporary clutter.
 
 - Option 2: scope to a specific package
@@ -49,12 +66,15 @@ pnpm build
   - Negative: invalid inputs, edge cases, and error handling/failure modes.
 - 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.
+  - Bounded-loop coverage for `@flatbread/proof` is exercised by both `pnpm test` and `pnpm -F @flatbread/proof test`.
+  - That focused proof suite is the quickest check for loop parser/runtime guards such as explicit rerun validation, overlapping-loop rejection, and convergence iteration accounting.
   - 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.
+  - `@flatbread/proof` exposes a package-local AVA entrypoint for the loop schema suite; 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. After editing, run `pnpm lint:fix:fast` so formatting matches CI (Cursor agents: see `.cursor/rules/post-edit-lint-fix.mdc`). On commit, `.husky/pre-commit` runs `pnpm lint:fix` (Pretty Quick on staged files). `pnpm lint:eslint` is an optional/manual root ESLint check until the linting stack is modernized.
 - Helpful commands:
   - Local CI parity: `pnpm verify`
   - Root test suite: `pnpm test`
+  - Proof bounded-loop suite: `pnpm -F @flatbread/proof 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`

ava.config.js

@@ -1,8 +1,16 @@
 export default {
+  // GraphQL schema generation currently uses graphql-compose's process-global
+  // schemaComposer. Run AVA files serially so schema-building tests do not
+  // mutate that shared composer concurrently.
+  concurrency: 1,
   files: [
     'packages/**/*.test.(j|t)s',
-    // Exclude Vitest suites located under __tests__ so AVA doesn't try to run them
-    '!packages/**/src/__tests__/**',
+    // Codegen + utils use Vitest under src/__tests__. Keep those out of the
+    // root AVA run, but allow AVA-owned proof coverage under the same folder
+    // layout so `pnpm test` exercises the proof bounded-loop suite and its
+    // parser/runtime guardrails.
+    '!packages/codegen/src/__tests__/**',
+    '!packages/utils/src/__tests__/**',
   ],
   extensions: {
     js: true,