From 525c02f664802cb5a955027d4d9064678947b3a8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 23 Aug 2026 08:34:04 +0000 Subject: [PATCH 1/6] docs: remove internal-only docs, keep end-user content Delete docs written for internal use before Proof shipped: - docs/edit-file-see-query-update-demo.md: issue #158 repro harness - docs/experiments/: starter benchmarks, issue drafts, DAG fixtures - docs/research/: internal research methodology Keep the six end-user docs (glossary, positioning, pmf-decision-rubric, data-ownership, json-export, local-dev-loop). Fix the one inbound link in examples/nextjs/README.md that pointed at the removed demo walkthrough. Change-Id: Ia4a82d15c61a4f142b542840f048e3f6912e6f35 Co-authored-by: Erika Ruth Witt --- docs/edit-file-see-query-update-demo.md | 87 ------- .../cursor-proof-skill-effort-graph/README.md | 12 - .../167-blocking-reference-layout.md | 17 -- .../efforts/pmf-audit-dag.md | 13 - .../plans/flatbread-flow-pmf-audit-dag.md | 13 - .../sessions/proof-cli-session-20260508.md | 12 - .../issue-168-three-layout-snippets/README.md | 11 - .../acceptance-test-matrix.md | 19 -- .../layout-claude-code/skill-stub-excerpt.md | 16 -- .../layout-cursor/rules-and-dag-excerpt.md | 24 -- .../layout-gcc/representative-tree.md | 32 --- .../issue-162-relational-starter-benchmark.md | 223 ------------------ .../issue-163-typescript-safety-test.md | 142 ----------- .../issue-164-export-trust-experiment.md | 156 ------------ .../issue-167-effort-graph-layout-mapping.md | 159 ------------- ...sue-168-adversarial-multi-layout-schema.md | 95 -------- ...-169-agent-artifact-retrieval-benchmark.md | 150 ------------ .../performant-context-search/README.md | 19 -- examples/nextjs/README.md | 4 +- 19 files changed, 2 insertions(+), 1202 deletions(-) delete mode 100644 docs/edit-file-see-query-update-demo.md delete mode 100644 docs/experiments/fixtures/cursor-proof-skill-effort-graph/README.md delete mode 100644 docs/experiments/fixtures/cursor-proof-skill-effort-graph/decisions/167-blocking-reference-layout.md delete mode 100644 docs/experiments/fixtures/cursor-proof-skill-effort-graph/efforts/pmf-audit-dag.md delete mode 100644 docs/experiments/fixtures/cursor-proof-skill-effort-graph/plans/flatbread-flow-pmf-audit-dag.md delete mode 100644 docs/experiments/fixtures/cursor-proof-skill-effort-graph/sessions/proof-cli-session-20260508.md delete mode 100644 docs/experiments/fixtures/issue-168-three-layout-snippets/README.md delete mode 100644 docs/experiments/fixtures/issue-168-three-layout-snippets/acceptance-test-matrix.md delete mode 100644 docs/experiments/fixtures/issue-168-three-layout-snippets/layout-claude-code/skill-stub-excerpt.md delete mode 100644 docs/experiments/fixtures/issue-168-three-layout-snippets/layout-cursor/rules-and-dag-excerpt.md delete mode 100644 docs/experiments/fixtures/issue-168-three-layout-snippets/layout-gcc/representative-tree.md delete mode 100644 docs/experiments/issue-162-relational-starter-benchmark.md delete mode 100644 docs/experiments/issue-163-typescript-safety-test.md delete mode 100644 docs/experiments/issue-164-export-trust-experiment.md delete mode 100644 docs/experiments/issue-167-effort-graph-layout-mapping.md delete mode 100644 docs/experiments/issue-168-adversarial-multi-layout-schema.md delete mode 100644 docs/experiments/issue-169-agent-artifact-retrieval-benchmark.md delete mode 100644 docs/research/performant-context-search/README.md diff --git a/docs/edit-file-see-query-update-demo.md b/docs/edit-file-see-query-update-demo.md deleted file mode 100644 index 17786582..00000000 --- a/docs/edit-file-see-query-update-demo.md +++ /dev/null @@ -1,87 +0,0 @@ -# Edit file → see query update demo - -This is a single-process demo harness, not the long-running `flatbread start` -server. Production live-editing uses the unified watch path described in -[local-dev-loop.md](./local-dev-loop.md). - -This demo is the current reproducible path for issue #158. It shows the -edit/query loop for posts, authors, and tags without requiring a manual -restart. - -One-shot `flatbread start` builds its schema at startup; use -`flatbread start --watch` for live content/config updates (see -[local dev loop boundaries](./local-dev-loop.md)). This demo therefore -uses a tiny watcher script that rebuilds the Flatbread schema per file event -and executes the same posts/authors/tags query shape the generated TypeScript -read API uses in the Next.js example. - -## Run it from a clean checkout - -```bash -pnpm install -pnpm build -cd examples/nextjs -pnpm exec flatbread codegen --verbose -pnpm run demo:watch-query -``` - -The script watches both Markdown and YAML relation data: - -```text -examples/content/markdown/posts/example-post.md -examples/content/yaml/authors/dr-caffeine.yml -``` - -It prints JSON like: - -```json -{ - "data": { - "allPosts": [ - { - "id": "sdfsdf-23423-sdfsd-23444-dfghf", - "title": "The Art of Measuring Cats in Fruit Units", - "tags": ["cats", "measurements", "fruit-science", "important-research"], - "authors": [ - { "id": "40s3", "name": "Eva" }, - { "id": "2a3e", "name": "Tony" } - ] - } - ], - "allYamlAuthors": [ - { - "id": "caffeine-researcher", - "name": "Dr. Maya Espresso", - "friend": { "id": "2a3e", "name": "Tony" } - } - ] - } -} -``` - -## Try the edit - -In another terminal, edit the watched Markdown post title plus a YAML author -name and `friend` relation: - -```bash -pnpm --filter nextjs run demo:edit -``` - -The watcher prints fresh query results with the edited Markdown title, edited -YAML author name, and changed YAML `friend` relation. Restore the files after -the demo: - -```bash -pnpm --filter nextjs run demo:restore -``` - -## What this does and does not prove - -- ✅ Editing relation-backed Markdown and YAML updates the query result without - a manual restart in this demo path. -- ✅ The query includes post fields, tag facets, resolved Markdown author - records, and resolved YAML author records. -- ✅ The demo is reproducible from the monorepo root with pnpm commands. -- ⚠️ The demo watcher is a focused harness, not a replacement for the unified - `flatbread start --watch` path. diff --git a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/README.md b/docs/experiments/fixtures/cursor-proof-skill-effort-graph/README.md deleted file mode 100644 index 78209c91..00000000 --- a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/README.md +++ /dev/null @@ -1,12 +0,0 @@ -# Fixture: Cursor `proof` skill → Effort Graph rows - -**Purpose:** Representative markdown files showing how **existing** agent harness paths under [`.cursor/skills/proof/`](../../../../.cursor/skills/proof/) map to **Effort Graph** collections without moving or rewriting the harness. - -| File here | Collection | Maps from | -| -------------------------------------------- | ---------- | ----------------------------------------------------------------- | -| `efforts/pmf-audit-dag.md` | Effort | Logical thread for the PMF audit DAG work | -| `plans/flatbread-flow-pmf-audit-dag.md` | Plan | Title + provenance ↔ `examples/dag-flatbread-flow-pmf-audit.json` | -| `sessions/proof-cli-session-20260508.md` | Session | Synthetic “one run” of the proof skill / CLI | -| `decisions/167-blocking-reference-layout.md` | Decision | Issue #167 acceptance: layout indexed + queryable context | - -Use with the config excerpt in [issue-167-effort-graph-layout-mapping.md](../../issue-167-effort-graph-layout-mapping.md). diff --git a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/decisions/167-blocking-reference-layout.md b/docs/experiments/fixtures/cursor-proof-skill-effort-graph/decisions/167-blocking-reference-layout.md deleted file mode 100644 index 7b8b41b8..00000000 --- a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/decisions/167-blocking-reference-layout.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: decision-167-reference-layout -effort: pmf-audit-dag -plan: plan-pmf-audit-dag -session: session-proof-20260508 -title: 'Issue #167 — Reference Effort Graph layout must index agent proof artifacts' -status: open -blocking: true -decided_at: null -tool: cursor-proof ---- - -# Decision - -**Acceptance (issue #167):** One **real or representative** agent artifact layout is mapped to Effort Graph–style collections; a **single** query surface can return **blocking** decisions for the current effort with **plan** and **session** context in one response. - -This row models an **open, blocking** gate: shipping broader Effort Graph marketing before **ID normalization**, **ref validation**, and **watch** is explicitly discouraged in the PMF audit and artifact opportunity docs; confirm scope on GitHub #167 vs full Session/Run automation. diff --git a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/efforts/pmf-audit-dag.md b/docs/experiments/fixtures/cursor-proof-skill-effort-graph/efforts/pmf-audit-dag.md deleted file mode 100644 index d853b24b..00000000 --- a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/efforts/pmf-audit-dag.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -id: pmf-audit-dag -status: active -canonical_branch: cursor/docs-positioning-non-goals-18a9 -external_issue: '167' -focus: 'Flatbread Flow PMF audit — DAG-shaped planner output' ---- - -# Effort: PMF audit DAG (proof skill) - -This effort groups agentic work where the **proof** Cursor skill authors a JSON DAG (see `.cursor/skills/proof/examples/dag-flatbread-flow-pmf-audit.json`) and executes it with local subagents. - -The **Effort** row is the stable anchor forPlans, Sessions, and Decisions that must be queryable as a graph. diff --git a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/plans/flatbread-flow-pmf-audit-dag.md b/docs/experiments/fixtures/cursor-proof-skill-effort-graph/plans/flatbread-flow-pmf-audit-dag.md deleted file mode 100644 index 9fed4cfb..00000000 --- a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/plans/flatbread-flow-pmf-audit-dag.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -id: plan-pmf-audit-dag -effort: pmf-audit-dag -title: 'Flatbread Flow PMF Audit (no sub-sub-agents)' -source_artifact: .cursor/skills/proof/examples/dag-flatbread-flow-pmf-audit.json -framing: 'Treat Flatbread as Git-native relational content for TypeScript apps, backed by flat files. GraphQL is one interface, not the whole product identity.' ---- - -# Plan body (derived from DAG) - -The canonical DAG spec lives at `source_artifact`. This markdown row exists so Flatbread can index **title**, **effort** ref, and narrative in **one** `Plan` collection while the JSON remains the machine-native task graph. - -Top-level tasks include `map-current-flow`, `relational-content-needs`, `recommend-roadmap`, and merge nodes—suitable for PMF positioning and architecture audits. diff --git a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/sessions/proof-cli-session-20260508.md b/docs/experiments/fixtures/cursor-proof-skill-effort-graph/sessions/proof-cli-session-20260508.md deleted file mode 100644 index f92f57b4..00000000 --- a/docs/experiments/fixtures/cursor-proof-skill-effort-graph/sessions/proof-cli-session-20260508.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: session-proof-20260508 -effort: pmf-audit-dag -runner: proof-cli -canvas_pattern: '.canvas.tsx (hot-recompiled DAG status)' ---- - -# Session: proof harness run (representative) - -Synthetic but representative **Session** for a single proof DAG execution: parent agent loads `dag-flatbread-flow-pmf-audit.json`, streams subagent status into the canvas, and persists human-facing summaries elsewhere. - -Full **Run**-level fidelity (append-only tool traces, per-task tokens) is **out of scope** for this fixture; see [flatbread-agent-artifact-opportunity.md §10](../../../../../flatbread-agent-artifact-opportunity.md). diff --git a/docs/experiments/fixtures/issue-168-three-layout-snippets/README.md b/docs/experiments/fixtures/issue-168-three-layout-snippets/README.md deleted file mode 100644 index 5d9415f4..00000000 --- a/docs/experiments/fixtures/issue-168-three-layout-snippets/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Fixtures: Issue #168 — Three harness layout snippets - -**Purpose:** Small, **non-authoritative** excerpts illustrating **L1** Claude-oriented skills, **L2** Cursor rules + skill/DAG, and **L3** synthetic GCC-style branch context. They support the adversarial schema report [issue-168-adversarial-multi-layout-schema.md](../../issue-168-adversarial-multi-layout-schema.md). - -| Path | Layout | -| ---------------------------------------------------------------------------------------- | ------------------------------------------------ | -| [`layout-claude-code/skill-stub-excerpt.md`](./layout-claude-code/skill-stub-excerpt.md) | Claude Code–style skill stub (YAML + body) | -| [`layout-cursor/rules-and-dag-excerpt.md`](./layout-cursor/rules-and-dag-excerpt.md) | Cursor `.mdc` rule + DAG JSON excerpt | -| [`layout-gcc/representative-tree.md`](./layout-gcc/representative-tree.md) | Synthetic `.GCC/` tree description + example row | - -**Acceptance test contract:** [`acceptance-test-matrix.md`](./acceptance-test-matrix.md) diff --git a/docs/experiments/fixtures/issue-168-three-layout-snippets/acceptance-test-matrix.md b/docs/experiments/fixtures/issue-168-three-layout-snippets/acceptance-test-matrix.md deleted file mode 100644 index 59f93442..00000000 --- a/docs/experiments/fixtures/issue-168-three-layout-snippets/acceptance-test-matrix.md +++ /dev/null @@ -1,19 +0,0 @@ -# Acceptance test matrix — Issue #168 (three harness layouts) - -**Intent:** Executable **markdown contract** for the adversarial schema experiment: each layout row must map to the **same** canonical collections (`Effort`, `Plan`, `Session`, `Decision`) without changing collection names. - -| TC | Layout | Harness source (fixture or repo path) | Prove (design / review) | -| -------- | ------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **TC-1** | **L1 — Claude-oriented** | [`layout-claude-code/skill-stub-excerpt.md`](./layout-claude-code/skill-stub-excerpt.md) | At least one **`Plan`** or **`Artifact`** mapping rule is defined for skill-style markdown; **`Effort.id`** is chosen independently of frontmatter `name` if they differ | -| **TC-2** | **L2 — Cursor rules + skills** | [`layout-cursor/rules-and-dag-excerpt.md`](./layout-cursor/rules-and-dag-excerpt.md) | **Split sources**: `.mdc` maps to **`Artifact`** (or explicit exclude) **and** DAG JSON maps to **`Plan.source_artifact`**; refs remain valid across both | -| **TC-3** | **L3 — GCC branch tree** | [`layout-gcc/representative-tree.md`](./layout-gcc/representative-tree.md) | Profile documents **branch-scoped paths** → canonical repo paths; **identity risk** (`Effort.external_branch`) is enumerated; merge behavior marked **policy**, not automatic | - -## Field stability assertions (must hold for all TCs) - -- **Stable after ingest:** `Effort.id`, `Decision.blocking`, `refs` targets (`effort`, `plan`, `session`). -- **Layout-specific mapping:** paths in `Plan.source_artifact`, session runner labels, inclusion of rule files as graph rows. - -## Pass / fail bar - -- **Pass:** Report [issue-168](../../issue-168-adversarial-multi-layout-schema.md) documents per-TC outcomes and concludes on **single schema + mapping layer** viability. -- **Fail:** Any TC requires **renaming collections** or **forking schemas** without a bridging profile — escalate to roadmap. diff --git a/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-claude-code/skill-stub-excerpt.md b/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-claude-code/skill-stub-excerpt.md deleted file mode 100644 index 80e87e98..00000000 --- a/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-claude-code/skill-stub-excerpt.md +++ /dev/null @@ -1,16 +0,0 @@ -## - -name: example-claude-skill -description: Example skill for layout stress — not installed product documentation. -allowed-tools: Bash(example:\*) -hidden: false - ---- - -# example-claude-skill - -Body is narrative; there is **no** companion JSON DAG in this excerpt. Mapping options for Flatbread: - -- **Plan.title** ← first `#` heading or frontmatter `name`. -- **Plan.source_artifact** ← path to this `SKILL.md`. -- **Effort** row may set `external_issue: "168"` for traceability while `id` remains a team-chosen slug. diff --git a/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-cursor/rules-and-dag-excerpt.md b/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-cursor/rules-and-dag-excerpt.md deleted file mode 100644 index 58aa54c6..00000000 --- a/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-cursor/rules-and-dag-excerpt.md +++ /dev/null @@ -1,24 +0,0 @@ -# Representative L2: Cursor rule frontmatter + DAG JSON shape (excerpt) - -## Rule file (`.cursor/rules/*.mdc` pattern) - -```yaml ---- -description: typescript, .tsx -alwaysApply: false ---- -# TypeScript Best Practices -``` - -**Mapping note:** `alwaysApply` + path are **tool-specific** metadata; if indexed, use **`Artifact`** with `kind: cursor-rule` (conceptual) or exclude from graph per team policy. - -## DAG JSON (proof skill example — truncated) - -```json -{ - "title": "Flatbread flow — PMF audit DAG", - "tasks": [{ "id": "t1", "subtask_prompt": "Plan the audit scope." }] -} -``` - -**Mapping note:** **`Plan.title`** and **`Plan.source_artifact`** point here; **`Effort`** slug is **not** implied by the JSON filename — declare explicitly on the Effort row (see [#167](../../cursor-proof-skill-effort-graph/) fixtures). diff --git a/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-gcc/representative-tree.md b/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-gcc/representative-tree.md deleted file mode 100644 index 0d109e72..00000000 --- a/docs/experiments/fixtures/issue-168-three-layout-snippets/layout-gcc/representative-tree.md +++ /dev/null @@ -1,32 +0,0 @@ -# Representative L3: GCC-style `.GCC/` tree (synthetic) - -**Note:** This repository does not ship a live `.GCC/` directory; this file describes the **expected shape** for adversarial mapping (per [Git Context Controller](https://arxiv.org/html/2508.00031v2) style branch knowledge). - -## Example tree (conceptual) - -```text -.GCC/ - branches/ - feature-pmf-audit/ - CONTEXT.md - DECISIONS.yaml - sessions/ - 2026-05-08-run.md -``` - -## Example `DECISIONS.yaml` fragment - -```yaml -decisions: - - id: gcc-decision-001 - blocking: true - status: open - effort_slug: pmf-audit-dag - relates_to_plan: ../CONTEXT.md -``` - -## Mapping stressors - -- **`Effort.external_branch`:** `feature-pmf-audit` vs canonical `Effort.id: pmf-audit-dag`. -- **Path relativity:** ingest must normalize branch-relative paths to repo anchors for `source_artifact`. -- **Merge:** closing or linking efforts when a branch merges is a **human / team policy** — core should not assume automatic row merges. diff --git a/docs/experiments/issue-162-relational-starter-benchmark.md b/docs/experiments/issue-162-relational-starter-benchmark.md deleted file mode 100644 index 0f6558c1..00000000 --- a/docs/experiments/issue-162-relational-starter-benchmark.md +++ /dev/null @@ -1,223 +0,0 @@ -# Experiment: Issue #162 — relational starter benchmark - -## Question - -Can a developer start from Flatbread's canonical existing example, understand -the `posts → authors + tags` model, and reach a typed read result in under 10 -minutes? - -## Benchmark path - -This uses the repo's canonical onboarding route on the existing example: - -1. Read the root README quickstart: - [`packages/flatbread/README.md#quickstart-posts-authors-and-tags`](../../packages/flatbread/README.md#quickstart-posts-authors-and-tags). -2. Inspect the backing files: - - `examples/content/markdown/posts/example-post.md` - - `examples/content/markdown/authors/tony.md` - - `examples/content/markdown/authors/eva.md` -3. Inspect the relation config: - `examples/nextjs/flatbread.config.js` -4. Generate typed artifacts from the example directory: - `cd examples/nextjs && pnpm exec flatbread codegen --clear-cache --verbose` -5. Confirm the typed read surface: - - GraphQL operation types in `examples/nextjs/generated/graphql.ts` - - generated read API usage in `examples/nextjs/lib/read.ts` -6. Verify the generated TypeScript read API path: - `pnpm --filter nextjs build` -7. Optional raw query watch proof: - `pnpm --filter nextjs run demo:watch-query` - -## Fresh-worktree run - -Environment: detached Git worktree created from the current branch with empty -workspace `node_modules` (pnpm reused the global package store). - -Command: - -```bash -git worktree add --detach /tmp/flatbread-starter-benchmark-worktree HEAD -cd /tmp/flatbread-starter-benchmark-worktree -start=$(date +%s) -corepack enable -pnpm install -pnpm build -cd examples/nextjs -pnpm exec flatbread codegen --clear-cache --verbose -timeout 8s pnpm run demo:watch-query -end=$(date +%s) -echo "elapsed_seconds=$((end-start))" -``` - -Observed result: - -```text -elapsed_seconds=49 -Done in 27.2s using pnpm v10.33.0 -✓ Generated TypeScript types: /tmp/flatbread-starter-benchmark-worktree/examples/nextjs/generated/graphql.ts -``` - -Relevant first-query output before the watcher timeout: - -```json -{ - "data": { - "allPosts": [ - { - "id": "sdfsdf-23423-sdfsd-23444-dfghf", - "title": "The Art of Measuring Cats in Fruit Units", - "tags": ["cats", "measurements", "fruit-science", "important-research"], - "authors": [ - { "id": "40s3", "name": "Eva" }, - { "id": "2a3e", "name": "Tony" } - ] - } - ], - "allYamlAuthors": [ - { - "id": "caffeine-researcher", - "name": "Dr. Maya Espresso", - "friend": { "id": "2a3e", "name": "Tony" } - } - ] - } -} -``` - -The watcher is intentionally long-running, so the shell command used -`timeout 8s`; the first render completed before timeout and no GraphQL `errors` -field was present. - -This completes the canonical install → build → codegen → first demo query path -on the existing example in under 10 minutes. - -## Generated TypeScript read API verification - -The Next.js home page imports `getPostsAuthorsAndTagsViaReadApi()` and -`getAuthorsViaReadApi()` from `examples/nextjs/lib/read.ts`. Static generation -therefore exercises the generated TypeScript read API path. - -Command: - -```bash -start=$(date +%s) -pnpm --filter nextjs build -end=$(date +%s) -echo "elapsed_seconds=$((end-start))" -``` - -Observed result: - -```text -elapsed_seconds=18 -✓ Compiled successfully in 3.0s -✓ Generating static pages (5/5) -Flatbread is done for now. Bye bye! 🥪 -``` - -The build still emits the known `eslint-plugin-react-hooks` warning, but exits -0 and renders the page path that calls the generated read API. - -## Warm-workspace rehearsal - -Environment: existing cloud workspace with dependencies already present. This -is a **canonical-command rehearsal**, not a true empty-cache/fresh-clone -measurement. - -Command: - -```bash -start=$(date +%s) -pnpm install -pnpm build -cd examples/nextjs -pnpm exec flatbread codegen --clear-cache --verbose -timeout 8s pnpm run demo:watch-query -end=$(date +%s) -echo "elapsed_seconds=$((end-start))" -``` - -Observed result: - -```text -elapsed_seconds=23 -Done in 1.9s using pnpm v10.33.0 -✓ Generated TypeScript types: /workspace/examples/nextjs/generated/graphql.ts -✓ TypeScript types generated successfully -"title": "The Art of Measuring Cats in Fruit Units" -"name": "Dr. Maya Espresso" -``` - -This is well under 10 minutes for the canonical command rehearsal in this -workspace. The fresh-worktree run above is the primary timing evidence; this -warm run remains useful for comparing maintainer-loop overhead. - -The docs now place the relation model before GraphQL, so the cognitive steps -are: - -- `Post` files carry `authors` IDs and `tags` string facets. -- `Author` files carry matching IDs. -- `flatbread.config.js` declares `refs: { authors: 'Author' }`. -- Codegen emits GraphQL operation types and Flatbread content-model/read helper - types. - -## Friction observed - -- The fresh-worktree benchmark reused the global pnpm store, so it is not a - network-cold install. -- `pnpm --filter nextjs build` succeeds and exercises the generated read API - path, but still prints a known - `eslint-plugin-react-hooks` load warning from the Next.js ESLint stack. -- `flatbread codegen --watch` is watch-only; docs must keep steering one-shot - benchmark users to `flatbread codegen --verbose`. -- The generated TypeScript read API is still a prototype and executes through - GraphQL, so the current first typed read result is strongest when described - as "GraphQL operations plus generated read helpers over one content model." - -## Follow-up issue drafts - -### Follow-up: Network-cold benchmark on a fresh clone/container - -**Problem:** This benchmark used a fresh worktree but reused the global pnpm -store. - -**Acceptance criteria:** - -- Run from a fresh clone/container with empty `node_modules` and cold pnpm - store/cache. -- Record install, build, codegen, and first query time separately. -- Note native dependency install warnings and remediation steps. - -### Follow-up: Turn friction notes into tracked issues - -**Problem:** This report can draft follow-up work, but the current automation -cannot create/close GitHub issues. - -**Acceptance criteria:** - -- Create project notes or issues for the cold-start benchmark and Next.js ESLint - warning. -- Link those issue URLs back into this report. - -This report is the current project note until GitHub-side follow-ups can be -created by a maintainer. - -### Follow-up: Clean Next.js ESLint dependency warning - -**Problem:** `pnpm --filter nextjs build` exits 0 but reports a missing -`eslint-plugin-react-hooks` plugin. - -**Acceptance criteria:** - -- Add or reconcile the missing plugin dependency. -- `pnpm --filter nextjs build` runs without the plugin warning. - -## Decision - -**Iterate / keep.** The canonical starter path on the existing example now -makes the relation-first value legible and reaches typed output, generated -TypeScript read API execution, and a demo query result comfortably under the -10-minute target in a fresh worktree / warm-store environment. This should be -described as time-to-first-query on the canonical example, not time-to-model -from zero. A stricter network-cold benchmark should still be run before using -the timing as external marketing evidence. diff --git a/docs/experiments/issue-163-typescript-safety-test.md b/docs/experiments/issue-163-typescript-safety-test.md deleted file mode 100644 index 1c971989..00000000 --- a/docs/experiments/issue-163-typescript-safety-test.md +++ /dev/null @@ -1,142 +0,0 @@ -# Experiment: Issue #163 — TypeScript safety interview/test - -## Question - -Do generated Flatbread types and the prototype TypeScript read API make -posts/authors/tags consumption materially safer than untyped flat-file reads or -hand-written GraphQL strings? - -## Test surface - -Representative files: - -- `examples/nextjs/generated/graphql.ts` -- `examples/nextjs/lib/read.ts` -- `packages/codegen/src/__tests__/e2e.test.ts` -- `packages/core/src/types.test.ts` - -## What works - -- `FlatbreadCollectionName` narrows collection names to configured literals. -- `FlatbreadRecord<'Post'>` ties app code to generated record shape. -- `FlatbreadRelationTarget<'Post', 'authors'>` ties relation traversal to the - configured `refs` target and cardinality. -- `tags` on `Post` remains a string facet (`Post['tags']`), not a relation - helper, because the canonical example does not model `Tag` as a collection. -- `FlatbreadRelationCardinality<'Post', 'authors'>` exposes whether a relation - is one or many. -- `createFlatbreadReadApi()` lets the app read `Post` and `Author` through a - generated collection-shaped API while GraphQL remains the underlying - execution layer. -- Core content/plugin types now use `unknown`, typed `ContentEntry.refs`, and - typed `Source.fetch` inputs instead of broad `any` surfaces. - -## Type-safety test run - -Commands: - -```bash -pnpm --filter @flatbread/codegen build -pnpm -F @flatbread/codegen exec vitest run -pnpm --filter @flatbread/core build -pnpm test:ava -- --match='*content types*' -pnpm --filter nextjs build -``` - -Observed results in this workspace: - -```text -@flatbread/codegen build: passed -@flatbread/codegen vitest: 39 tests passed -@flatbread/core build: passed -AVA content type assertions: passed (the command currently runs the broader AVA suite) -Next.js build: passed, with known eslint-plugin-react-hooks warning -``` - -## Inference gaps and confusing names - -- `createFlatbreadReadApi()` still accepts an optional GraphQL selection string - for advanced use. That selection is not type-checked, so the safest path is - the generated default selection. -- `FlatbreadReadApi` returns `Partial>` because the selected - fields are a runtime concern. This is honest, but less precise than a typed - selection builder would be. -- Generated relation helper names are verbose: - `FlatbreadRelationTargetCollection` versus `FlatbreadRelationTarget` can be - confusing without examples. -- Nullable GraphQL results and generated helper types are not yet perfectly - aligned. The prototype errs toward safe optional/partial reads. -- Flatbread metadata fields such as `_path` and `_slug` are still emitted as - nullable by GraphQL Code Generator even when Flatbread-managed records usually - provide them. -- Core plugin author types are narrower, but `ContentEntry` still permits - arbitrary extra keys for plugin/config extensibility. - -## Verification transcript - -```text -pnpm --filter @flatbread/codegen build -exit 0 - -pnpm -F @flatbread/codegen exec vitest run -Test Files 5 passed (5) -Tests 39 passed (39) - -pnpm --filter @flatbread/core build -exit 0 - -pnpm test:ava -- --match='*content types*' -exit 0 -73 tests passed -note: the match command currently runs the broader AVA suite because of the root script's argument forwarding - -pnpm --filter nextjs build -exit 0 -note: build succeeds but prints the known eslint-plugin-react-hooks warning - -pnpm lint -exit 0 -All matched files use Prettier code style! -``` - -## Follow-up issue drafts - -### Follow-up: Add typed selection builder for generated read API - -**Problem:** Selection strings are runtime GraphQL snippets, not typed -TypeScript selections. - -**Acceptance criteria:** - -- Generate a selection builder or typed projection API for collection reads. -- Compile-time tests reject unknown fields. -- Existing string selection remains documented as an escape hatch or is removed. - -### Follow-up: Tighten relation helper naming and examples - -**Problem:** `FlatbreadRelationTarget` and -`FlatbreadRelationTargetCollection` are useful but easy to confuse. - -**Acceptance criteria:** - -- Add generated JSDoc explaining each helper. -- Add examples for one-to-one and one-to-many relations. -- Ensure docs and generated names match the glossary. - -### Follow-up: Align nullability between GraphQL and read helper types - -**Problem:** GraphQL nullable list/member behavior is only approximately -represented by the read helper types. - -**Acceptance criteria:** - -- Derive nullability from the GraphQL schema for relation helpers. -- Add compile-time assertions for nullable singular, nullable list, and - non-null list relations. - -## Decision - -**Keep / iterate.** Type safety is a PMF-strengthening differentiator. The -generated content-model helpers and read API remove several weakly typed paths, -but the prototype still needs a typed selection story and sharper relation -helper documentation before it can be marketed as a fully type-safe read layer. diff --git a/docs/experiments/issue-164-export-trust-experiment.md b/docs/experiments/issue-164-export-trust-experiment.md deleted file mode 100644 index 3df7f332..00000000 --- a/docs/experiments/issue-164-export-trust-experiment.md +++ /dev/null @@ -1,156 +0,0 @@ -# Experiment: Issue #164 — export trust experiment - -## Question - -Does an explicit ownership story plus JSON/CSV export behavior make Flatbread -feel safer to adopt? - -## Demo prompt - -Use this prompt in interviews or demos after the posts/authors/tags quickstart. -Run command examples from `examples/nextjs`, where `flatbread.config.js` lives: - -1. Show raw source files: - - `examples/content/markdown/posts/example-post.md` - - `examples/content/markdown/authors/tony.md` - - `examples/content/markdown/authors/eva.md` -2. Show config-owned relations in `examples/nextjs/flatbread.config.js`. -3. Show the [data ownership story](../data-ownership.md). -4. Show the snapshot export APIs: - - ```ts - import { - exportCollectionsAsCsv, - exportCollectionsAsJson, - loadConfig, - } from 'flatbread'; - - const configResult = await loadConfig({ cwd: process.cwd() }); - - const json = await exportCollectionsAsJson(configResult, { - collections: ['Post', 'Author'], - }); - - const csv = await exportCollectionsAsCsv(configResult, { - collections: ['Post'], - }); - ``` - - See also: - - - [Data ownership](../data-ownership.md) - - [Snapshot export docs](../json-export.md) - -5. Explain the exit path: - - raw files remain usable without Flatbread; - - JSON snapshots preserve normalized IDs and refs; - - CSV flat views are spreadsheet-friendly; - - GraphQL documents/types preserve the app's read shapes. - -## Product self-review notes - -No external participant interview was available in this execution environment, -so these are product-review notes from the implemented demo path rather than -human interview findings. Treat them as project notes, not external validation. - -## Verification transcript - -Command (run from `examples/nextjs`): - -```bash -node --input-type=module - <<'NODE' -import { - loadConfig, - exportCollectionsAsCsv, - exportCollectionsAsJson, -} from 'flatbread'; - -const configResult = await loadConfig({ cwd: process.cwd() }); -const json = await exportCollectionsAsJson(configResult, { - collections: ['Post'], - pathRoot: process.cwd(), -}); -const csv = await exportCollectionsAsCsv(configResult, { - collections: ['Post'], - pathRoot: process.cwd(), -}); - -console.log(JSON.stringify(json.Post[0], null, 2).split('\n').slice(0, 12).join('\n')); -console.log('---CSV---'); -console.log(csv.Post.split('\n').slice(0, 2).join('\n')); -NODE -``` - -Trimmed output: - -```text -{ - "_content": { - "raw": "\nLorem ipsum\n" - }, - "_filename": "b.md", - "_path": "content/markdown/posts/b.md", - "_slug": "b", - "authors": [ - "1111", - "ab2c" - ], - "id": "2348fds-563fdh-59ddsd-3332-09876", ----CSV--- -id,_filename,_path,_slug,authors,category,controversial_opinions,rating,research_duration,slurp_factor,soups_tested,tags,temperature_preference,title -2348fds-563fdh-59ddsd-3332-09876,b.md,content/markdown/posts/b.md,b,1111;ab2c,,,44,,,,,,Test post B -``` - -| Prompt area | Trust signal | Remaining concern | -| --------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- | -| Raw Markdown/YAML files | Strong: source of truth is visible in Git | Derived fields / overrides require Flatbread to recompute | -| JSON export API | Strong: preserves IDs/refs and validates graph first | API-only today; non-developers need a CLI | -| CSV export API | Medium: useful for spreadsheet review | Nested fields are omitted and relation arrays are joined IDs | -| GraphQL introspection/types | Medium: preserves app read contract | Requires a working Flatbread schema/server or generated artifacts | -| Data ownership docs | Strong: clearly states non-goals and exit surfaces | Needs runnable CLI examples once export commands exist | - -## Keep / kill / iterate - -**Iterate based on product self-review.** Export behavior appears to improve the -adoption-trust story because it turns "your files are yours" into concrete -artifacts: raw files, JSON snapshots, CSV flat views, and generated read -contracts. - -Do not market this as externally validated or as a complete non-developer export -workflow yet. The trust story becomes materially stronger when JSON/CSV export -has a first-class CLI and when docs include copy-paste commands that write files -to disk. - -## Follow-up issue drafts - -### Follow-up: Add `flatbread export` CLI for JSON and CSV - -**Problem:** Export is currently an API, so adoption demos require a Node script. - -**Acceptance criteria:** - -- `flatbread export json --collections Post,Author --out snapshots/` -- `flatbread export csv --collections Post --out snapshots/` -- Commands fail with validation diagnostics for broken refs/duplicate IDs. -- Docs use CLI first and API second. - -### Follow-up: Add exit-story fixture output - -**Problem:** Docs describe export behavior but do not check in example output. - -**Acceptance criteria:** - -- Add a small `examples/exit-story/` fixture or generated snapshot directory. -- Include JSON and CSV outputs from the posts/authors/tags model. -- Add a test that verifies snapshots are deterministic. - -### Follow-up: Interview with two target users - -**Problem:** This report contains product-review notes, not external user -feedback. - -**Acceptance criteria:** - -- Run the demo prompt with at least two TypeScript/static-site developers. -- Record whether JSON/CSV exports increase adoption trust. -- Capture objections and update keep/kill/iterate decision. diff --git a/docs/experiments/issue-167-effort-graph-layout-mapping.md b/docs/experiments/issue-167-effort-graph-layout-mapping.md deleted file mode 100644 index f7f95a6a..00000000 --- a/docs/experiments/issue-167-effort-graph-layout-mapping.md +++ /dev/null @@ -1,159 +0,0 @@ -# Experiment: Issue #167 — Effort Graph reference layout (agent artifacts → indexed graph) - -**Scope:** Map one real in-repo agent artifact layout to the [Effort Graph sketch](../../flatbread-agent-artifact-opportunity.md) (§8): `Effort` → `Plan`, `Session`, `Decision` with `refs`. Demonstrate a **single retrieval surface** query—here, **GraphQL**—that returns **blocking decisions** for a chosen effort with **nested plan and session context**. This satisfies the “reference layout indexed + validated” bar from the [PMF decision rubric](../pmf-decision-rubric.md) as an **experiment**, not a shipped preset. - -**Non-goals (explicit):** Full **Session** / **Run** fidelity, importer scripts, or turning this repo’s proof harness into production artifact storage. GraphQL is **one** interface; the same filter object is intended to work against codegen-backed TypeScript or MCP when those surfaces expose the shared filter DSL ([§9 agent artifact opportunity](../../flatbread-agent-artifact-opportunity.md)). - ---- - -## 1. Source layout mapped (agent artifacts) - -**Canonical folder:** [`.cursor/skills/proof/`](../../.cursor/skills/proof/) — Cursor **Skill** for DAG-style proof runs. - -| Existing path | Role in harness | Effort Graph mapping | -| -------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -| `SKILL.md` | Human + agent docs for the skill | **Unindexed narrative** in v1; optional later **`Artifact`** row body or symlinked markdown | -| `examples/dag-flatbread-flow-pmf-audit.json` | Machine-authored **DAG spec** (title, tasks, models) | **`Plan`** row: `title` + provenance; body summarizes DAG; `source_artifact` frontmatter points back to this path | -| _(synthetic)_ proof CLI invocation | One **multi-step run** with canvas streaming | **`Session`** row: `runner`, `effort` ref, short body describing the run surface | -| _(synthetic)_ governance row | **Blocking** acceptance check | **`Decision`** row: `blocking`, `effort` / `plan` / `session` refs | - -This is **incremental adoption**: only new markdown under a dedicated tree needs frontmatter; harness files **stay in place** ([agent artifact opportunity §9.6](../../flatbread-agent-artifact-opportunity.md)). - ---- - -## 2. Target tree (preset-shaped) - -Representative fixtures live under: - -[`fixtures/cursor-proof-skill-effort-graph/`](./fixtures/cursor-proof-skill-effort-graph/) - -Suggested production mirror (from §8 sketch): - -```text -.flatbread-efforts/ - efforts/ - plans/ - sessions/ - decisions/ -``` - ---- - -## 3. Minimal `flatbread` config excerpt - -Wire the content arrays to the fixture paths (or to `.flatbread-efforts/*` once copied into a consumer repo): - -```javascript -import { defineConfig, transformerMarkdown, sourceFilesystem } from 'flatbread'; - -export default defineConfig({ - source: sourceFilesystem(), - transformer: transformerMarkdown({ markdown: { gfm: true } }), - content: [ - { - path: 'docs/experiments/fixtures/cursor-proof-skill-effort-graph/efforts', - collection: 'Effort', - }, - { - path: 'docs/experiments/fixtures/cursor-proof-skill-effort-graph/plans', - collection: 'Plan', - refs: { effort: 'Effort' }, - }, - { - path: 'docs/experiments/fixtures/cursor-proof-skill-effort-graph/sessions', - collection: 'Session', - refs: { effort: 'Effort' }, - }, - { - path: 'docs/experiments/fixtures/cursor-proof-skill-effort-graph/decisions', - collection: 'Decision', - refs: { effort: 'Effort', plan: 'Plan', session: 'Session' }, - }, - ], -}); -``` - -**Validation story:** Today, **broken `refs`** (typos in `effort` / `plan` / `session`) surface as missing relations at query time; duplicate `id` values within a collection remain a **roadmap** hardening item ([PMF audit §4](../../flatbread-flow-pmf-audit.md), [rubric](../pmf-decision-rubric.md)). - ---- - -## 4. Example query — one retrieval surface (GraphQL) - -**Intent:** “All **blocking** decisions for effort `pmf-audit-dag`, with **plan title** and **session** context.” - -```graphql -query BlockingDecisionsForEffort { - allDecisions( - filter: { effort: { eq: "pmf-audit-dag" }, blocking: { eq: true } } - sortBy: "decided_at" - order: DESC - ) { - id - title - status - blocking - decided_at - plan { - id - title - source_artifact - } - session { - id - runner - } - } -} -``` - -**Expected shape (illustrative):** One row for the #167 **reference layout** decision, with nested `Plan` matching the DAG JSON title and `Session` describing a proof-cli style run. **TS / MCP parity:** use the same `filter` JSON against the list resolver the app exposes ([agent artifact opportunity §9](../../flatbread-agent-artifact-opportunity.md)). - ---- - -## 5. Friction observed (concrete follow-ups) - -### Issue draft: **[Preset] Effort Graph field naming and codegen** - -**Problem:** GraphQL and docs benefit from **one canonical naming** policy (`blocking` vs `severity`, `decided_at` vs `decidedAt`). Today’s default `fieldNameTransform` only normalizes **spaces**, not snake_case→camelCase. - -**Acceptance criteria:** Document preset field names; optionally ship `fieldNameTransform: lodash.camelCase` for Effort Graph preset only; regenerate example GraphQL operations. - ---- - -### Issue draft: **[Core] Ref integrity diagnostics for agent presets** - -**Problem:** Missing `plan` / `session` on a blocking decision is a **product risk** ([rubric integrity bar](../pmf-decision-rubric.md)); today users discover gaps via empty nested selections, not necessarily a validator error. - -**Acceptance criteria:** Configurable **hard fail** (or structured diagnostic) when `Decision.blocking: true` and `plan` ref does not resolve; integration test from `diag-query-surface` notes. - ---- - -### Issue draft: **[MCP] Single-call “blocking decisions + context” for effort id** - -**Problem:** Agents should not re-learn GraphQL shapes per repo. - -**Acceptance criteria:** MCP tool accepts `effortId`, returns the same object shape as the query above (or executes the shared filter internally). - ---- - -### Project note (no issue number) - -**Canonical effort identity** (branch vs slug vs GitHub `#167`) is still a **human checkpoint**; this fixture uses **`pmf-audit-dag`** as a stable slug and **`external_issue: "167"`** on the Effort row for traceability. - ---- - -## 6. How to extend without migration day one - -1. Add **one** `Effort` row per research thread or feature. -2. When a DAG JSON exists, add a **Plan** row pointing at the file path in `source_artifact`. -3. For each proof run worth querying later, add a **Session** row. -4. Add **Decision** rows only for gates that must be machine-queryable (blocking / open decisions). - ---- - -## References - -- [flatbread-agent-artifact-opportunity.md §8 sketch](../../flatbread-agent-artifact-opportunity.md) -- [flatbread-flow-pmf-audit.md — Effort Graph positioning](../../flatbread-flow-pmf-audit.md) -- [pmf-decision-rubric.md](../pmf-decision-rubric.md) -- Proof DAG example: [`.cursor/skills/proof/examples/dag-flatbread-flow-pmf-audit.json`](../../.cursor/skills/proof/examples/dag-flatbread-flow-pmf-audit.json) diff --git a/docs/experiments/issue-168-adversarial-multi-layout-schema.md b/docs/experiments/issue-168-adversarial-multi-layout-schema.md deleted file mode 100644 index 8c97781d..00000000 --- a/docs/experiments/issue-168-adversarial-multi-layout-schema.md +++ /dev/null @@ -1,95 +0,0 @@ -# Experiment: Issue #168 — Adversarial Effort Graph schema across three harness layouts - -**Scope:** Execute [agent artifact opportunity §12.2](../../flatbread-agent-artifact-opportunity.md) — stress one **Effort Graph**–shaped model against **three** representative tool trees. Document which **entities and fields** stay stable, which need **tool-specific mapping**, and whether **one canonical schema + a mapping layer** remains a viable product bet. - -**Product framing:** Flatbread is **Git-native relational content** for TypeScript apps, materialized from flat files. **GraphQL** is **one** query adapter alongside generated TypeScript and MCP; it does not define the whole product. - -**Related:** Issue [#167 reference layout](./issue-167-effort-graph-layout-mapping.md) (single Cursor `proof` skill → indexed rows). This report generalizes that pattern across layouts. - -**Non-goals:** Importers, core validator code, or moving production harness files. **Fixtures are snippets** under [`fixtures/issue-168-three-layout-snippets/`](./fixtures/issue-168-three-layout-snippets/). - ---- - -## 1. Harness layouts under test - -| ID | Layout | Representative paths (this repo or synthetic) | Role in adversarial test | -| ------ | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -| **L1** | **Claude Code–oriented** (skills / agent packets) | [`.agents/skills/*/SKILL.md`](../../.agents/skills/) | YAML frontmatter + narrative body; skills as discoverable units without a single DAG file per effort | -| **L2** | **Cursor rules + skills** | [`.cursor/rules/*.mdc`](../../.cursor/rules/), [`.cursor/skills/proof/`](../../.cursor/skills/proof/) | Split between **rules** (policy) and **skills** (workflows + JSON DAG examples) | -| **L3** | **GCC-style branch context** (synthetic) | [`fixtures/issue-168-three-layout-snippets/layout-gcc/`](./fixtures/issue-168-three-layout-snippets/layout-gcc/representative-tree.md) | Per-branch knowledge tree; identity and merge semantics are the stressor | - -The machine-readable **acceptance matrix** (checkbox test contract) lives in [`acceptance-test-matrix.md`](./fixtures/issue-168-three-layout-snippets/acceptance-test-matrix.md). - ---- - -## 2. Canonical schema (held constant across layouts) - -Collections (names align with [#167](./issue-167-effort-graph-layout-mapping.md) and opportunity §8): - -- `Effort` — thread of work; stable slug `id`; optional `external_issue`, `external_branch` -- `Plan` — structured intent; `title`, `source_artifact`, `effort` ref -- `Session` — one run / invocation; `runner`, `effort` ref -- `Decision` — gate; `blocking`, `status`, `effort` / `plan` / `session` refs -- `Artifact` _(optional in v1)_ — indexed file bodies (rules, manifests) when teams choose not to treat them as narrative-only - ---- - -## 3. Entity and field stability - -### 3.1 Stable across layouts (same semantic column in the graph) - -| Entity | Fields / behavior | Why stable | -| --------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | -| `Effort` | `id` (slug), optional `external_*` | Chosen **canonical identity**; tools do not agree on branch vs issue — the row **declares** the slug | -| All row types | `refs` to other collections (`effort`, `plan`, `session`) | Relational shape is the product promise | -| `Decision` | `blocking`, `status`, temporal fields (e.g. `decided_at`) | Gate semantics are layout-agnostic once ingested | -| Query surfaces | Filter object over the same field names (GraphQL / TS / MCP) | One mental model for consumers | -| **Disk policy** | New markdown under `.flatbread-efforts/` (or preset path); harness files **unmoved** | Matches [#167 incremental adoption](./issue-167-effort-graph-layout-mapping.md) and migration notes from upstream diagnostics | - -### 3.2 Requires tool-specific mapping (profile / ingest rules) - -| Concern | L1 Claude-oriented | L2 Cursor | L3 GCC | -| ------------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------- | -| **Where “the plan” lives** | Often **narrative** `SKILL.md` or distributed docs; may lack one JSON DAG | **Split**: rules vs `SKILL.md` vs `examples/*.json` | Session / design files per branch; path encodes **branch** | -| **Plan row `source_artifact`** | Globs on skill roots; may need **multi-file** summary or primary file pick | Point to **JSON** for machine title; optional second row for skill narrative | Map branch-relative path → repo-relative at ingest time | -| **Session identity** | CLI / agent-reported run id varies | proof CLI / IDE session labels | GCC **run** or commit-scoped ids (tool-defined) | -| **Rules / manifests** | Less central in stub skills | `.mdc` with `alwaysApply` — candidate **`Artifact`** or excluded | Policy files may mirror branch | -| **Effort identity collision** | Skill name vs GitHub issue | Branch name vs `pmf-audit-dag` slug | **Branch name vs slug** — highest duplication risk when branches fold | - ---- - -## 4. Where a single schema breaks (unless mapping layer exists) - -1. **Identity:** Without a documented **canonical `Effort.id`** and `external_*` fields, the same work is forked across tools ([§5 human checkpoint #167](./issue-167-effort-graph-layout-mapping.md)). -2. **Partial graphs:** Blocking `Decision` rows with missing `plan` / `session` refs are worse when three layouts multiply ingest paths — **validation / diagnostics** become product-critical (per upstream **diag-stability-mapping**). -3. **Noise:** Promoting every rule file to `Artifact` explodes row count; needs **`kind`** + **`always_on`** (or equivalent) filtering policy. -4. **GCC lifecycle:** Branch merge does not imply graph merge — **Sessions**, **Efforts**, and **links** need team policy (no automatic semantics in core). - -None of these require **abandoning** a unified collection schema; they require **profiles** (globs, field extraction, optional joins) and **integrity rules**. - ---- - -## 5. Recommendation - -**Verdict: One canonical Effort Graph schema + an explicit mapping / profile layer is viable.** The opportunity is **not** too fragmented for a single relational model: the fragmentation is in **harness conventions and identity policy**, not in the core nouns (`Effort`, `Plan`, `Session`, `Decision`). - -- **Ship** a small set of **layout profiles** (at minimum: Claude-oriented skills tree, Cursor rules+skills, GCC branch tree) as **configuration**, not separate schemas. -- **Invest** early in **ref integrity diagnostics** and **blocking-decision invariants** so multi-layout ingest cannot silently degrade. -- **Defer** promising automatic merge semantics for GCC branches until a human policy is written. - -If the team cannot commit to **canonical slugs** and **validation**, the same schema technically works but **operational** fragmentation will **feel** like multiple products — that is a **process** failure mode, not a schema impossibility. - ---- - -## 6. Traceability and human gate - -- Align this experiment with the real tracker issue **#168** (scope, acceptance criteria, and whether it stays distinct from **#167** documentation). -- Before scaling fixtures: approve **`Effort.id`** scheme and whether `.mdc` / root manifests are **`Artifact` rows** vs narrative-only ([#167 §5](./issue-167-effort-graph-layout-mapping.md)). - ---- - -## References - -- [flatbread-agent-artifact-opportunity.md §12](../../flatbread-agent-artifact-opportunity.md) -- [issue-167-effort-graph-layout-mapping.md](./issue-167-effort-graph-layout-mapping.md) -- [PMF decision rubric](../pmf-decision-rubric.md) diff --git a/docs/experiments/issue-169-agent-artifact-retrieval-benchmark.md b/docs/experiments/issue-169-agent-artifact-retrieval-benchmark.md deleted file mode 100644 index 82b24d19..00000000 --- a/docs/experiments/issue-169-agent-artifact-retrieval-benchmark.md +++ /dev/null @@ -1,150 +0,0 @@ -# Experiment: Issue #169 — cold-start vs Flatbread-mediated artifact retrieval - -## Question - -Does a Flatbread-style Effort Graph retrieval surface reduce prompt/context -cost while preserving enough continuity to justify further MCP and agent-query -investment? - -## Benchmark setup - -Representative artifact set: - -- `flatbread-agent-artifact-opportunity.md` -- `docs/experiments/issue-167-effort-graph-layout-mapping.md` -- `docs/experiments/issue-168-adversarial-multi-layout-schema.md` -- Effort Graph fixture rows under - `docs/experiments/fixtures/cursor-proof-skill-effort-graph/` - -Task prompt: - -> For the PMF audit DAG effort, identify open blocking decisions and include -> linked plan/session context. - -## Strategies compared - -### A. Cold-start context stuffing - -Stuff the full strategy/experiment history into context: - -```text -flatbread-agent-artifact-opportunity.md -issue-167-effort-graph-layout-mapping.md -issue-168-adversarial-multi-layout-schema.md -``` - -Measured byte count: - -```text -19,750 flatbread-agent-artifact-opportunity.md - 7,658 issue-167-effort-graph-layout-mapping.md - 9,693 issue-168-adversarial-multi-layout-schema.md -37,101 total bytes -``` - -### B. Flatbread-mediated Effort Graph retrieval - -Retrieve only the blocking decision row plus linked plan/session rows: - -```text -836 decisions/167-blocking-reference-layout.md -771 plans/flatbread-flow-pmf-audit-dag.md -618 sessions/proof-cli-session-20260508.md -2,225 total bytes -``` - -Representative query shape from #167: - -```graphql -query BlockingDecisionsForEffort { - allDecisions( - filter: { effort: { eq: "pmf-audit-dag" }, blocking: { eq: true } } - sortBy: "decided_at" - order: DESC - ) { - id - title - status - blocking - plan { - id - title - source_artifact - } - session { - id - runner - } - } -} -``` - -## Result - -| Strategy | Approx. bytes retrieved | Continuity quality | Cost / noise | -| ---------------------------- | ----------------------: | ------------------------------------------------------------------ | --------------------------------------------- | -| Cold-start stuffing | 37,101 | High context recall, but requires rereading broad strategy docs | High: 16.7× larger than filtered rows | -| Flatbread-mediated retrieval | 2,225 | Enough for the target question: blocking decision + plan + session | Low: focused payload, less repeated discovery | - -Filtered retrieval is roughly **94% smaller** for this task: - -```text -1 - (2,225 / 37,101) ≈ 94.0% -``` - -## Continuity tradeoff - -Flatbread-mediated retrieval answers the target question directly: - -- **Decision:** issue #167 reference layout remains an open blocking gate. -- **Plan context:** linked PMF audit DAG plan/source artifact. -- **Session context:** proof CLI/session row describing the run surface. - -What it loses: - -- Broad market landscape and strategic rationale from the full artifact - opportunity memo. -- Nuanced tensions from the adversarial schema report unless the query expands - to include related artifacts. - -That tradeoff is acceptable for "what is blocking this effort?" It is not -enough for "should Flatbread become an agent memory company?" without an -expanded query. - -## Recommendation - -**Keep / invest further.** The retrieval leverage is strong enough to justify -the next MCP/agent-query slice. A 94% smaller context payload with preserved -blocking decision continuity is exactly the kind of advantage the Effort Graph -opportunity needs. - -## Follow-up issue drafts - -### Follow-up: MCP query for blocking decisions by effort - -**Acceptance criteria:** - -- Tool accepts `effortId`. -- Returns blocking decisions with plan/session context. -- Uses Flatbread filters internally. -- Includes deterministic tests against the issue #167 fixture. - -### Follow-up: Expand artifact retrieval benchmark - -**Acceptance criteria:** - -- Use at least one multi-session real effort, not only representative fixtures. -- Compare answer quality for at least three prompts: - - blocking decisions; - - why a product choice was made; - - what to do next. -- Record token counts from an actual model/tool invocation. - -### Follow-up: Related-artifact expansion policy - -**Acceptance criteria:** - -- Define when a decision query should pull source artifacts, plan body, or full - strategy docs. -- Add max-depth and max-byte guardrails. -- Document recommended defaults for MCP calls. diff --git a/docs/research/performant-context-search/README.md b/docs/research/performant-context-search/README.md deleted file mode 100644 index d331bf00..00000000 --- a/docs/research/performant-context-search/README.md +++ /dev/null @@ -1,19 +0,0 @@ -# Performant context search research (2026) - -This folder documents how [`flatbread-search-and-memory-research.md`](../../../flatbread-search-and-memory-research.md) (repo root) was produced and where to find evidence **from a fresh clone**. - -## Methodology - -The report was authored using a **`/proof` DAG**: parallel subagents produced intermediate dossiers (repository audits + literature surveys), then synthesis tasks merged them into the single markdown file at the repo root. - -The intermediate filenames below name that pipeline only — **they are not checked into git** (doing so would duplicate hundreds of kilobytes already folded into the report and §13 references): - -- `audit-flatbread-retrieval.md`, `audit-proof-context.md` -- `sota-dense-sparse-hybrid.md`, `sota-graph-structure.md`, `sota-agent-memory.md`, `sota-embeddable-runtimes.md` -- `synthesis-flatbread.md`, `synthesis-proof.md`, `synthesis-novel.md` - -**Canonical sources for readers:** [`flatbread-search-and-memory-research.md`](../../../flatbread-search-and-memory-research.md), its inline citations into this repo (`packages/core`, `packages/proof`, …), and the external URLs in **§13 — References**. - -## Proof run artifacts - -When reproducing or extending this research with `@flatbread/oven`, full DAG runs write per-task transcripts under **`/.oven/artifacts/`** by default. See the [Oven README](https://github.com/FlatbreadLabs/oven#readme) (`--full-output-dir`, `--no-artifacts`). diff --git a/examples/nextjs/README.md b/examples/nextjs/README.md index eb570260..c83a0ca4 100644 --- a/examples/nextjs/README.md +++ b/examples/nextjs/README.md @@ -79,8 +79,8 @@ pnpm run demo:watch-query ``` Then run `pnpm run demo:edit`; the terminal prints updated Markdown -posts/authors/tags and YAML author query results. Full walkthrough: -[`docs/edit-file-see-query-update-demo.md`](../../docs/edit-file-see-query-update-demo.md). +posts/authors/tags and YAML author query results. Restore the files after +with `pnpm run demo:restore`. ## Content path From a8d07158cbf349f0c91b36f476939171473bfa37 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 23 Aug 2026 08:40:12 +0000 Subject: [PATCH 2/6] docs: rewrite internal-staff language for end-users, rename pmf rubric Rename docs/pmf-decision-rubric.md to docs/comparison.md so the filename matches its user-facing title. Rewrite language that read as internal marketing or roadmap notes: - comparison.md: replace the 'What to emphasize' sales-enablement table ('If someone is comparing Flatbread with... Explain that Flatbread offers...') with a user-facing 'When to choose Flatbread' table that addresses the reader directly. Tighten the intro. - glossary.md: drop internal roadmap notes ('future ID work should...', 'Near-term validation work should...', 'Any future generated TypeScript reader...'). State current validation behavior. Update the See-also link to comparison.md. - positioning.md: update the comparison link to comparison.md. - data-ownership.md: replace 'portability story starts with a simple constraint' with 'portability rests on one constraint'; replace 'relational integrity work' with 'validated content graph'; drop the 'prototype' hedge on the generated read API. - json-export.md: drop 'A future option may strip _path / _filename...' and 'do not yet have a stable flat representation' roadmap language. - local-dev-loop.md: drop the 'prototype' hedge on the generated read API. Change-Id: I2eecee9e8e93617862d609359558b773901dc544 Co-authored-by: Erika Ruth Witt --- docs/{pmf-decision-rubric.md => comparison.md} | 8 ++++---- docs/data-ownership.md | 13 ++++++------- docs/glossary.md | 9 ++++----- docs/json-export.md | 6 ++---- docs/local-dev-loop.md | 4 ++-- docs/positioning.md | 2 +- 6 files changed, 19 insertions(+), 23 deletions(-) rename docs/{pmf-decision-rubric.md => comparison.md} (95%) diff --git a/docs/pmf-decision-rubric.md b/docs/comparison.md similarity index 95% rename from docs/pmf-decision-rubric.md rename to docs/comparison.md index 63fed5ba..b5dbd4e6 100644 --- a/docs/pmf-decision-rubric.md +++ b/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. | diff --git a/docs/data-ownership.md b/docs/data-ownership.md index 785e9012..b8421e73 100644 --- a/docs/data-ownership.md +++ b/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 diff --git a/docs/glossary.md b/docs/glossary.md index 1acc4d97..3e8a3e51 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -8,7 +8,7 @@ hosted CMS, a full writing product, or a general-purpose database. but it is only one option. See also: [Flatbread positioning](./positioning.md) and -[Comparing Flatbread with other tools](./pmf-decision-rubric.md). +[Comparing Flatbread with other tools](./comparison.md). --- @@ -33,7 +33,7 @@ A **named group** of content of the same kind, declared in your Flatbread config ### ID -An identifier Flatbread uses to **point at one item within a collection** so relations can resolve. Today, Flatbread expects loaded entries to expose an `id`-shaped value that query arguments and `refs` can compare against; future ID work should keep that rule explicit across files, generated types, and query interfaces. IDs wire the graph together **in the repository**; they are not a centralized “primary key service” like a server database would provide. +An identifier Flatbread uses to **point at one item within a collection** so relations can resolve. Flatbread expects loaded entries to expose an `id`-shaped value that query arguments and `refs` can compare against. IDs wire the graph together **in the repository**; they are not a centralized "primary key service" like a server database would provide. Current normalization rule: IDs may be **non-empty strings** or **finite numbers**. Flatbread compares record lookup arguments through a normalized string form, so a record with `id: 123`, a GraphQL argument `id: "123"`, and a GraphQL `ID` integer literal `id: 123` refer to the same record. Top-level equality and membership filters on a collection record’s `id` use the same normalized comparison; ordered filters (`lt`, `gt`, etc.) continue to use normal scalar comparison and should not be treated as stable ID semantics. String IDs are trimmed before comparison, so `id: " 123 "` normalizes to `"123"`. Empty strings, `null`, `undefined`, booleans, objects, `NaN`, and infinite numbers are rejected as invalid record IDs; if more than one record is invalid, Flatbread reports the invalid IDs together. Duplicate IDs after normalization (for example `123` and `"123"` in the same collection) are invalid because they would otherwise resolve inconsistently. @@ -50,8 +50,7 @@ When GraphQL is your **query interface**, the **generated GraphQL schema** descr **Generated TypeScript** from GraphQL document codegen (for example, an operation result type such as `GetPostsAuthorsAndTagsQuery`) types that way of reading data only. Records and relations still come from repository files and -config. Any future generated TypeScript reader without GraphQL would be -documented separately. +config. ### Record @@ -69,4 +68,4 @@ A **configured link** from entries in one collection to another (for example, `r ### Validation -Checks that your **Flatbread configuration, plugin wiring, and loaded content graph** are consistent enough to read safely. Near-term validation work should make broken references, duplicate IDs, and unsupported relation shapes clear before they become query-time surprises. This is still scoped to Flatbread’s content graph; it is not a promise of every database constraint or every editorial rule a CMS might enforce. +Checks that your **Flatbread configuration, plugin wiring, and loaded content graph** are consistent enough to read safely. Broken references, duplicate IDs, and unsupported relation shapes fail before they reach query time. This covers the content graph only; it is not a promise of every database constraint or editorial rule a CMS might enforce. diff --git a/docs/json-export.md b/docs/json-export.md index 3f8b1d34..0527c29f 100644 --- a/docs/json-export.md +++ b/docs/json-export.md @@ -43,8 +43,7 @@ console.log(JSON.stringify(snapshot, null, 2)); - JSON export is read-only; it does not mutate source files. - Relation values are exported as normalized IDs, not expanded nested records. -- Source metadata is included today so snapshots are actionable during review. - A future option may strip `_path` / `_filename` for content-only diffs. +- Source metadata is included so snapshots are actionable during review. ## CSV flat views @@ -53,8 +52,7 @@ CSV export is intentionally a flat view over the same validated JSON snapshot: - scalar fields become columns; - scalar arrays and relation-id arrays are joined with `;` by default; - relation fields remain normalized reference IDs rather than expanded records; -- nested objects such as `_content` are omitted because they do not yet have a - stable flat representation. +- nested objects such as `_content` are omitted from the flat view; - the delimiter defaults to `,`; `;` and tab are also supported; - joined array/relation values default to `;`, configurable with `relationSeparator`. diff --git a/docs/local-dev-loop.md b/docs/local-dev-loop.md index 71934d34..59e37dff 100644 --- a/docs/local-dev-loop.md +++ b/docs/local-dev-loop.md @@ -40,8 +40,8 @@ Expected behavior: hot-swaps, and generated artifact refreshes. - Editing a `.graphql` document or a content/config file refreshes `generated/graphql.ts`; do not run `flatbread codegen --watch` beside it. -- The generated content-model types and prototype read API are refreshed by - the same codegen command. +- The generated content-model types and read API are refreshed by the same + codegen command. - The running GraphQL endpoint at `http://localhost:5057/graphql` hot-swaps valid content and config generations without restarting the framework. diff --git a/docs/positioning.md b/docs/positioning.md index b558ba6b..4b04ae42 100644 --- a/docs/positioning.md +++ b/docs/positioning.md @@ -3,7 +3,7 @@ For installation and usage, see the [main README](../README.md). For definitions used in the docs and config, see the [glossary](./glossary.md). To compare Flatbread with databases, CMSs, and other file-based tools, see -[Comparing Flatbread with other tools](./pmf-decision-rubric.md). For keeping +[Comparing Flatbread with other tools](./comparison.md). For keeping and moving your data, see [data ownership](./data-ownership.md). Flatbread turns files in Git into a typed relational graph. A project has From a1e7616bdf4b502c8a17b24e5ff534a190ab0f64 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 23 Aug 2026 08:42:25 +0000 Subject: [PATCH 3/6] docs: fix dangling references to deleted and renamed docs After trimming internal docs and renaming pmf-decision-rubric.md to comparison.md, three tracked files still pointed at the old paths: - flatbread-flow-pmf-audit.md: update rubric link to ./docs/comparison.md. - flatbread-search-and-memory-research.md: drop the broken link to the deleted docs/research/performant-context-search/README.md (methodology dossiers were never checked in; reword to state that). - .flatbread-proof/findings/fnd-pmf-rubric-understates...: update the evidence citation path from docs/pmf-decision-rubric.md to docs/comparison.md so the citation resolves. Claim substance unchanged. Verified no remaining repo-wide references to edit-file-see-query-update-demo, docs/experiments, docs/research, pmf-decision-rubric, performant-context-search, or any individual deleted experiment file. All kept docs internal links and external README links resolve to existing files. Change-Id: I6e4e61f4463c90436b91502b5af634942aabc025 Co-authored-by: Erika Ruth Witt --- ...understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md | 2 +- flatbread-flow-pmf-audit.md | 2 +- flatbread-search-and-memory-research.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md b/.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md index ee9a0e5e..c64fadbd 100644 --- a/.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md +++ b/.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md @@ -11,7 +11,7 @@ derives_from: ## 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. diff --git a/flatbread-flow-pmf-audit.md b/flatbread-flow-pmf-audit.md index 0fe6e5b9..e0d5c677 100644 --- a/flatbread-flow-pmf-audit.md +++ b/flatbread-flow-pmf-audit.md @@ -6,7 +6,7 @@ Generated from the DAG task runner audit on May 7, 2026. > research, not current setup instructions. For the current development steps > and watch behavior, see [Local development loop](./docs/local-dev-loop.md). -**Buyer-facing comparison rubric** (SQLite, CMS, Contentlayer-like, agent-artifact workflows; issue #144 acceptance-style criteria): [docs/pmf-decision-rubric.md](./docs/pmf-decision-rubric.md). +**Buyer-facing comparison rubric** (SQLite, CMS, Contentlayer-like, agent-artifact workflows; issue #144 acceptance-style criteria): [docs/comparison.md](./docs/comparison.md). Canvas: `file:///Users/tonyketcham/.cursor/projects/Users-tonyketcham-Code-Github-personal-flatbread/canvases/dag-flatbread-pmf-audit.canvas.tsx` diff --git a/flatbread-search-and-memory-research.md b/flatbread-search-and-memory-research.md index 3c8b1fe4..04dbff85 100644 --- a/flatbread-search-and-memory-research.md +++ b/flatbread-search-and-memory-research.md @@ -2,7 +2,7 @@ A weighing of opportunities, hypotheses of outcome, and an ideal end state for the Flatbread + Proof axis as a search-and-memory substrate. -> Companion to [`flatbread-agent-artifact-opportunity.md`](flatbread-agent-artifact-opportunity.md) and [`flatbread-flow-pmf-audit.md`](flatbread-flow-pmf-audit.md). Authored via a `/proof` DAG; intermediate dossier names are listed in [`docs/research/performant-context-search/README.md`](docs/research/performant-context-search/README.md). Evidence for claims is in repo paths cited inline and in **§13 — References** (no ephemeral `file://` paths). +> Companion to [`flatbread-agent-artifact-opportunity.md`](flatbread-agent-artifact-opportunity.md) and [`flatbread-flow-pmf-audit.md`](flatbread-flow-pmf-audit.md). Authored via a `/proof` DAG; intermediate dossier names were folded into this report and are not checked into the repo. Evidence for claims is in repo paths cited inline and in **§13 — References** (no ephemeral `file://` paths). --- @@ -26,7 +26,7 @@ Flatbread's relational filter DSL is excellent on **declared frontmatter columns ### 2.1 Frontmatter-only retrieval is structurally insufficient -The internal Flatbread codebase audit (methodology: [`docs/research/performant-context-search/README.md`](docs/research/performant-context-search/README.md); sections cited here match the audit dossier §2.4–2.5, §3.1, §5) is unambiguous about today's retrieval surface in [`packages/core`](packages/core): +The internal Flatbread codebase audit (sections cited here match the audit dossier §2.4–2.5, §3.1, §5) is unambiguous about today's retrieval surface in [`packages/core`](packages/core): - The `filter` JSON DSL (`packages/core/src/utils/sift.ts`) is a Mongo-style comparator engine: `eq`, `ne`, `lt/lte/gt/gte`, `in/nin`, `includes/excludes`, `regex`, `wildcard`, `exists`, `strictlyExists`. It runs over an **in-memory `EntryNode` JSON graph**, with `resolveFilter` (`packages/core/src/resolvers/arguments.ts`) executing an internal GraphQL subquery to fetch only the leaf paths a filter mentions, then `sift()`-ing the result. - Boolean composition is **implicit AND** across flattened leaf conditions (`reduceBooleans('and')` in `packages/core/src/utils/sift.ts`); `$or` and `$nor` are unimplemented in the default sift path even though `reduceBooleans` supports `or` internally. `findMany(ids)` lacks the `filter` argument that `all*` has. `sortBy` only resolves top-level keys (`packages/core/src/resolvers/arguments.ts:162-176`). From a5a1ce31de8af74330a252d3079bfb76dccb8fcb Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 23 Aug 2026 08:47:48 +0000 Subject: [PATCH 4/6] internal: sequester root research dossiers into internal/ Move the four root-level internal research/playbook dossiers out of the repo front door into internal/: - flatbread-flow-pmf-audit.md (PMF audit) - flatbread-search-and-memory-research.md (search/memory research) - flatbread-agent-artifact-opportunity.md (agent-artifact opportunity) - flatbread-flow-agentic-workflows.md (agentic workflows playbook) These are internal strategy dossiers the agent harness uses as living alignment references, not end-user docs. The root now holds only user-facing files (README, AGENTS, CONTRIBUTING, CHANGELOG). Moving all four together keeps their mutual cross-links intact (intra-directory bare links still resolve). Add internal/README.md marking the directory as internal, not end-user docs, and pointing end-users back to docs/ and the root README. Fix the two .cursor/ config references that point at these files: - .cursor/agents/flatbread-architecture-planner.md - .cursor/skills/flatbread-major-migration/SKILL.md No end-user-facing file referenced the dossiers, so no other fixes needed. Change-Id: I6d68fa292030f38cff948a3b46a3604069311010 Co-authored-by: Erika Ruth Witt --- .../agents/flatbread-architecture-planner.md | 2 +- .../skills/flatbread-major-migration/SKILL.md | 2 +- internal/README.md | 24 +++++++++++++++++++ .../flatbread-agent-artifact-opportunity.md | 0 .../flatbread-flow-agentic-workflows.md | 0 .../flatbread-flow-pmf-audit.md | 0 .../flatbread-search-and-memory-research.md | 0 7 files changed, 26 insertions(+), 2 deletions(-) create mode 100644 internal/README.md rename flatbread-agent-artifact-opportunity.md => internal/flatbread-agent-artifact-opportunity.md (100%) rename flatbread-flow-agentic-workflows.md => internal/flatbread-flow-agentic-workflows.md (100%) rename flatbread-flow-pmf-audit.md => internal/flatbread-flow-pmf-audit.md (100%) rename flatbread-search-and-memory-research.md => internal/flatbread-search-and-memory-research.md (100%) diff --git a/.cursor/agents/flatbread-architecture-planner.md b/.cursor/agents/flatbread-architecture-planner.md index cb943216..45b0f5ff 100644 --- a/.cursor/agents/flatbread-architecture-planner.md +++ b/.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-pmf-audit.md` and `internal/flatbread-flow-agentic-workflows.md`. ## Output Schema For DAG Handoff diff --git a/.cursor/skills/flatbread-major-migration/SKILL.md b/.cursor/skills/flatbread-major-migration/SKILL.md index a4f787c6..f9742a09 100644 --- a/.cursor/skills/flatbread-major-migration/SKILL.md +++ b/.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, diff --git a/internal/README.md b/internal/README.md new file mode 100644 index 00000000..14ee1076 --- /dev/null +++ b/internal/README.md @@ -0,0 +1,24 @@ +# Internal research and playbooks + +This directory holds internal strategy dossiers and agent playbooks. They are +**not end-user documentation**. End-user docs live under [`docs/`](../docs/). + +These files record product-market-fit analysis, retrieval-and-memory +research, agent-artifact opportunity mapping, and the agentic-workflows +playbook. The agent harness uses them as living alignment references: + +- `.cursor/agents/flatbread-architecture-planner.md` keeps recommendations + aligned with the PMF audit and the agentic-workflows playbook here. +- `.cursor/skills/flatbread-major-migration/SKILL.md` points Oven CLI users + at the DAG topology in the agentic-workflows playbook here. + +## Files + +- `flatbread-flow-pmf-audit.md` — product-market-fit audit (May 2026 snapshot). +- `flatbread-search-and-memory-research.md` — search-and-memory substrate research. +- `flatbread-agent-artifact-opportunity.md` — agent-artifact opportunity and schema sketch. +- `flatbread-flow-agentic-workflows.md` — agentic-workflows playbook (DAG topology). + +Treat these as background context, not current setup instructions. For current +setup and behavior, see the end-user docs under [`docs/`](../docs/) and the +root [`README`](../README.md). diff --git a/flatbread-agent-artifact-opportunity.md b/internal/flatbread-agent-artifact-opportunity.md similarity index 100% rename from flatbread-agent-artifact-opportunity.md rename to internal/flatbread-agent-artifact-opportunity.md diff --git a/flatbread-flow-agentic-workflows.md b/internal/flatbread-flow-agentic-workflows.md similarity index 100% rename from flatbread-flow-agentic-workflows.md rename to internal/flatbread-flow-agentic-workflows.md diff --git a/flatbread-flow-pmf-audit.md b/internal/flatbread-flow-pmf-audit.md similarity index 100% rename from flatbread-flow-pmf-audit.md rename to internal/flatbread-flow-pmf-audit.md diff --git a/flatbread-search-and-memory-research.md b/internal/flatbread-search-and-memory-research.md similarity index 100% rename from flatbread-search-and-memory-research.md rename to internal/flatbread-search-and-memory-research.md From 34adb9d2db091bd66bb9106ee6da052683749f1c Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 23 Aug 2026 08:50:24 +0000 Subject: [PATCH 5/6] internal: delete stale research dossiers, keep live playbook The agent harness should not anchor to the PMF audit: it self-declares as a May 2026 stale snapshot ('background research, not current setup instructions'). The search-and-memory and agent-artifact dossiers are one-time research with no live agent-harness wiring. Only the agentic-workflows playbook is current and referenced by the harness (architecture-planner alignment + major-migration DAG topology). - Delete internal/flatbread-flow-pmf-audit.md - Delete internal/flatbread-search-and-memory-research.md - Delete internal/flatbread-agent-artifact-opportunity.md - .cursor/agents/flatbread-architecture-planner.md: drop the stale PMF-audit anchor; keep the playbook reference. - internal/flatbread-flow-agentic-workflows.md: reword line 3 to not name the deleted PMF audit file. - internal/README.md: list only the playbook. This also clears the ~13 root-relative markdown links my prior move had broken inside the three deleted dossiers. The playbook has no broken markdown links (its package references are code spans, not links). Change-Id: I348fff27ee55e1e35ea1530534a1e79f3dfea16a Co-authored-by: Erika Ruth Witt --- .../agents/flatbread-architecture-planner.md | 2 +- internal/README.md | 25 +- .../flatbread-agent-artifact-opportunity.md | 232 ------ internal/flatbread-flow-agentic-workflows.md | 2 +- internal/flatbread-flow-pmf-audit.md | 173 ----- .../flatbread-search-and-memory-research.md | 708 ------------------ 6 files changed, 11 insertions(+), 1131 deletions(-) delete mode 100644 internal/flatbread-agent-artifact-opportunity.md delete mode 100644 internal/flatbread-flow-pmf-audit.md delete mode 100644 internal/flatbread-search-and-memory-research.md diff --git a/.cursor/agents/flatbread-architecture-planner.md b/.cursor/agents/flatbread-architecture-planner.md index 45b0f5ff..f3cfdc69 100644 --- a/.cursor/agents/flatbread-architecture-planner.md +++ b/.cursor/agents/flatbread-architecture-planner.md @@ -27,7 +27,7 @@ Return: - Validation plan. - Open questions and human checkpoints. -Keep recommendations aligned with `internal/flatbread-flow-pmf-audit.md` and `internal/flatbread-flow-agentic-workflows.md`. +Keep recommendations aligned with `internal/flatbread-flow-agentic-workflows.md`. ## Output Schema For DAG Handoff diff --git a/internal/README.md b/internal/README.md index 14ee1076..e4a85dac 100644 --- a/internal/README.md +++ b/internal/README.md @@ -1,24 +1,17 @@ -# Internal research and playbooks +# Internal playbooks -This directory holds internal strategy dossiers and agent playbooks. They are -**not end-user documentation**. End-user docs live under [`docs/`](../docs/). +This directory holds internal agent playbooks. They are **not end-user +documentation**. End-user docs live under [`docs/`](../docs/). -These files record product-market-fit analysis, retrieval-and-memory -research, agent-artifact opportunity mapping, and the agentic-workflows -playbook. The agent harness uses them as living alignment references: +## Files -- `.cursor/agents/flatbread-architecture-planner.md` keeps recommendations - aligned with the PMF audit and the agentic-workflows playbook here. -- `.cursor/skills/flatbread-major-migration/SKILL.md` points Oven CLI users - at the DAG topology in the agentic-workflows playbook here. +- `flatbread-flow-agentic-workflows.md` — agentic-workflows playbook (execution phases, DAG topology, port-5057 safety, failure recovery, human checkpoints). -## Files +The agent harness uses this playbook as a living reference: -- `flatbread-flow-pmf-audit.md` — product-market-fit audit (May 2026 snapshot). -- `flatbread-search-and-memory-research.md` — search-and-memory substrate research. -- `flatbread-agent-artifact-opportunity.md` — agent-artifact opportunity and schema sketch. -- `flatbread-flow-agentic-workflows.md` — agentic-workflows playbook (DAG topology). +- `.cursor/agents/flatbread-architecture-planner.md` keeps recommendations aligned with it. +- `.cursor/skills/flatbread-major-migration/SKILL.md` points Oven CLI users at its DAG topology section. -Treat these as background context, not current setup instructions. For current +Treat it as operational guidance for schema-migration work. For current setup and behavior, see the end-user docs under [`docs/`](../docs/) and the root [`README`](../README.md). diff --git a/internal/flatbread-agent-artifact-opportunity.md b/internal/flatbread-agent-artifact-opportunity.md deleted file mode 100644 index 8c8d71e5..00000000 --- a/internal/flatbread-agent-artifact-opportunity.md +++ /dev/null @@ -1,232 +0,0 @@ -# Flatbread Agent Artifact Opportunity - -Research and product perspective on relational agent artifacts stored in git, state of the art (2026), and Flatbread's wedge as it pivots beyond GraphQL-only query surfaces. - -## 1. Executive Summary - -The agent artifact layer in 2026 is dense with conventions and files (`AGENTS.md`, `SKILL.md`, `.handoff/*.md`, `.GCC/branches/*`, `.cs/discoveries.md`, vault MCPs) but thin on **typed relational schemas** over those artifacts. Teams get search, backlinks, versioned memory trees, and handoff packets; they rarely get reference integrity, stable cross-tool IDs, or filterable graph queries like "all blocking decisions for this effort with owning plan and producing sessions." Flatbread already models collections, refs, and rich filters over markdown/YAML in git. Positioning it as **the relational layer for agent efforts in git**—with MCP and generated TypeScript alongside GraphQL—is a credible category move. The recommended posture is an **Proof**: a preset schema (Effort → Plan, Decision, Session, Artifact, Run) plus validation, append-oriented writes, and agent-facing query APIs, without building a CMS or competing on generic databases. - -## 2. The Problem - -Agent harnesses produce long outputs (plans, research dumps, code reviews, traces) but rarely persist them as **cohesive elements** bound to a named effort—feature, spike, migration, or research thread. The next phase of a pipeline often starts cold unless a human or script deliberately passes a markdown file into context. - -Consequences: - -- **Decision drift** — earlier conclusions are lost or contradicted across sessions. -- **Repeated discovery** — the same codebase areas get re-explained. -- **Weak accountability** — hard to answer "what did we decide about X for effort Y across all runs?" -- **Manifest scaling** — single-file hot memory (`AGENTS.md`, constitution files) works until it does not; real projects scale to tiered cold stores and specialist agents ([Codified Context](https://arxiv.org/html/2602.20478v1) reports on the order of tens of thousands of lines of machine-oriented specs for a ~108k LOC system). - -The missing abstraction is not "more markdown" but a **stable, queryable object graph** whose instances live in the repo and survive tool switches. - -## 3. State of the Art — Five Layers - -Patterns cluster into five layers. None alone delivers typed relations + integrity over arbitrary harness layouts. - -### Manifest layer - -Single-file or small-set instructions loaded every session: `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, Cursor rules with YAML frontmatter (`globs`, `alwaysApply`, `description`, path constraints). Empirical studies report adoption and content patterns across thousands of repos; one line of evidence associates **AGENTS.md** with roughly **29% lower median runtime** and **17% lower output token consumption** (as cited in [Codified Context](https://arxiv.org/html/2602.20478v1) related work). This layer optimizes **always-on priming**, not structured artifact graphs. - -### Skill / package layer - -Reusable procedures shipped as files (e.g. Claude Code [Skills](https://code.claude.com/docs/en/skills)), Cursor Agent Skills, packaged "agentic artifacts." [Agentic Beacon](https://github.com/Shadowsong27/agentic-beacon) frames a package-manager metaphor for contexts, knowledge, and skills across teams—addressing **context drift** analogously to code reuse. Strength: distribution and versioning of **playbooks**. Weakness: still not a relational model over instances (efforts, decisions, runs). - -### Workspace / handoff layer - -Deliberate disk layouts for continuity: [handoff](https://semiherdogan.medium.com/handoff-a-better-way-to-run-autonomous-development-loops-00e97e62d470)-style `.handoff/` trees (`FEATURE.md`, `SPEC.md`, `DESIGN.md`, `STATE.md`, `SESSION.md`); [AgentHandoff](https://github.com/aceandro2812/AgentHandoff) for switching between Claude Code, Codex, Cursor with structured packets and reported **60–85% token reduction** vs cold rediscovery; [long-running-harness](https://github.com/eddiearc/long-running-harness) patterns (`feature_list.json`, `progress.txt`); ecosystem demand for named persistent plans (e.g. Claude Code Plan Manager discussions). This layer fixes **handoff** between tools or phases; it does not standardize cross-effort querying or ref validation. - -### Memory-as-VCS layer - -Treat agent memory like version control. **Git Context Controller** ([GCC](https://arxiv.org/html/2508.00031v2)): `.GCC/main.md`, per-branch `commit.md`, `log.md`, `metadata.yaml`; commands `COMMIT`, `BRANCH`, `MERGE`, `CONTEXT` for layered retrieval; strong benchmark results (e.g. **80.2%** on SWE-Bench Verified with Claude 4 Sonnet in reported runs). **Lore** ([arXiv](https://arxiv.org/abs/2603.15566)) repurposes git commit trailers for structured decision shadows. **agmem** ([GitHub](https://github.com/vivek-tiwari-vt/agmem)): git-like, content-addressable agent memories. **claude-sessions** ([GitHub](https://github.com/hex/claude-sessions)): workspaces with discoveries, artifacts folders, checkpoints. These systems excel at **timelines, branches, and checkpoints**; they are weak on arbitrary typed edges (e.g. Decision → Plan → Effort) validated at index time. - -### Knowledge-graph / vault layer - -Markdown vaults + retrieval: **Codified Context** ([paper](https://arxiv.org/html/2602.20478v1))—constitution (hot), specialist agents, cold markdown specs + MCP keyword retrieval (`find_relevant_context`, `suggest_agent`), scaled to hundreds of sessions. **engraph**, **memory-graph**, **Obsidian**-oriented stacks combine wiki-links, embeddings, BM25/FTS. **MCP vault servers** (e.g. [markdown-vault-mcp](https://github.com/pvliesdonk/markdown-vault-mcp), [vault-mcp](https://github.com/Lincyaw/vault-mcp), [vault-semantic-mcp](https://github.com/eman-hc/vault-semantic-mcp), [knowledge-mcp](https://github.com/andrewbergsma/knowledge-mcp)) expose search, backlinks, sometimes hybrid semantic + lexical retrieval. Strength: **find related notes**. Weakness: links are typically untyped strings; "Tier 3 document lists" are not foreign keys. - -### Adjacent: Markdown content tooling - -[Velite](https://velite.js.org/), Keystatic, `next-mdx-remote`, and the legacy Contentlayer space optimize **sites and apps** from markdown collections. They overlap Flatbread on "typed-ish content in repos" but do not target **multi-session agent efforts** or harness-native conventions. - -## 4. The Gap - -Across manifest, skill, workspace, memory-as-VCS, and vault layers, convergent capabilities include: - -- File and folder conventions. -- Full-text and semantic search. -- Versioned or branching narrative memory. -- Wiki-links and backlinks. - -Conspicuously absent as a **first-class product**: - -| Missing capability | Why it matters | -| ---------------------------------------------- | -------------------------------------------------------------------------------------- | -| **Typed relational schemas** over artifacts | Filters like `status`, `blocking`, `effort_id` need columns, not only embeddings. | -| **Reference integrity** | Broken Plan → Decision links should fail at load/validate time, not at retrieval luck. | -| **Stable IDs** | Renames and multi-branch workflows should not orphan edges. | -| **Canonical Effort (or equivalent) aggregate** | Same role PR plays for commits: one object that owns the thread. | -| **Non-text queries** | Traverse + filter + sort without grepping or re-ranking chunks. | - -Example that is painful everywhere above but natural in a relational content layer: _"Decisions for Effort X where `blocking: true`, ordered by `decided_at`, with `plan.title` and `session.tool`."_ - -## 5. Why Flatbread Is Shaped For This - -Flatbread's existing architecture maps cleanly onto the gap: - -- **Collections and refs** — GraphQL schema generation from content collections and cross-collection references ([`packages/core/src/generators/schema.ts`](packages/core/src/generators/schema.ts)) matches Effort-linked entity graphs. -- **Structured filtering** — Mongo-style filter operators on collection fields ([root README](README.md) — `eq`, `in`, `exists`, `regex`, `wildcard`, etc.) exceed typical vault MCP keyword APIs for **predicate-rich** agent queries. -- **Markdown/YAML as rows** — [`packages/transformer-markdown`](packages/transformer-markdown), [`packages/transformer-yaml`](packages/transformer-yaml) align with how harnesses already emit artifacts. -- **Pluggable sources** — [`packages/source-filesystem`](packages/source-filesystem) can ingest `.agents/`, `.cursor/`, `.handoff/`, `.GCC/`, `.cs/` trees as additional content paths without a new storage paradigm. -- **Codegen path** — [`packages/codegen/src/generator.ts`](packages/codegen/src/generator.ts) is the right place to grow **generated TypeScript accessors** as the agent-ergonomic surface GraphQL is not. - -The [PMF audit](flatbread-flow-pmf-audit.md) near-term list (config typing, ID normalization, relation validation, watch mode) is **the same prerequisite work** an agent-artifact product needs—not a competing roadmap. - -## 6. Three Product Postures (Options) - -### Posture A — Agent Artifact OS - -Flatbread becomes a full memory product: authoring UI, lifecycle, branching UX, primary store for traces. **Target:** teams wanting one vendor for agent memory. **Surfaces:** dashboard, editors, sync. **Strength:** largest narrative TAM if execution wins. **Risk:** collides with IDE vendors and GCC-like research stacks; violates current PMF guidance to avoid hosted CMS/dashboard; requires broad writes and permissions Flatbread does not have today. - -### Posture B — Relational Adapter for Agent Harnesses - -Read-mostly preset: index existing harness folders, validate optional schemas, expose MCP + TS helpers. **Target:** harness engineers wiring Cursor/Claude/GCC without migrating storage. **Strength:** low displacement, fits today's read skew. **Risk:** commodity "nice indexer" unless paired with a sharp noun and integrity story. - -### Posture C — Proof (recommended) - -Own the **Effort** aggregate explicitly: typed collections **Effort**, **Plan**, **Decision**, **Session**, **Artifact**, **Run** (and optional **Agent**, **Review**) with refs and validation; MCP + generated TS + GraphQL over one model; **append-oriented** agent writes into the graph. **Target:** multi-week agentic work in repos. **Strength:** differentiated category, testable MVP, uses every Flatbread primitive; clarifies the GraphQL pivot as "one of several query adapters." **Risk:** needs a minimal credible write path and a schema flexible enough for real harness diversity without dissolving into bespoke configs. - -**Relational sketch (conceptual):** - -```mermaid -flowchart LR - Effort --> Plan - Effort --> Session - Plan --> Decision - Session --> Artifact - Session --> Run - Decision --> Artifact -``` - -## 7. Recommended Thesis - -> **Flatbread is the relational layer for agent efforts in git.** Model efforts, plans, decisions, sessions, and artifacts as typed flat-file collections. Query them with **MCP**, **GraphQL**, or **generated TypeScript**. Catch broken references before the next session loses the thread. - -**Why not A:** Avoids building a competing memory OS and UI; stays compositional with existing harnesses. - -**Why not only B:** B is the implementation spine of C; C adds the **Effort** noun and integrity guarantees that make the positioning legible and defensible during a pivot away from GraphQL-only. - -## 8. Reference Schema Sketch - -Illustrative only—not a shipping API. Shows how collections and `refs` express the graph (paths and collection names are placeholders): - -```js -import { defineConfig, transformerMarkdown, sourceFilesystem } from 'flatbread'; - -export default defineConfig({ - source: sourceFilesystem(), - transformer: transformerMarkdown({ markdown: { gfm: true } }), - content: [ - { - path: '.flatbread-proof/efforts', - collection: 'Effort', - refs: { owner_agent: 'Agent' }, - }, - { - path: '.flatbread-proof/plans', - collection: 'Plan', - refs: { effort: 'Effort' }, - }, - { - path: '.flatbread-proof/decisions', - collection: 'Decision', - refs: { effort: 'Effort', plan: 'Plan', session: 'Session' }, - }, - { - path: '.flatbread-proof/sessions', - collection: 'Session', - refs: { effort: 'Effort' }, - }, - { - path: '.flatbread-proof/artifacts', - collection: 'Artifact', - refs: { - effort: 'Effort', - session: 'Session', - source_decision: 'Decision', - }, - }, - { - path: '.flatbread-proof/runs', - collection: 'Run', - refs: { session: 'Session', effort: 'Effort' }, - }, - { - path: '.flatbread-proof/agents', - collection: 'Agent', - }, - ], -}); -``` - -Frontmatter fields (e.g. `id`, `status`, `blocking`, `decided_at`, `tool`) would drive filters; body markdown holds narrative. This sketch **pressure-tests** PMF priorities: stable `id` semantics, duplicate detection, missing-ref diagnostics, and typed config for collections. - -## 9. Surfaces To Ship - -1. **MCP server** — tools: list collections, query with existing filter DSL, expand refs, fetch artifact body; primary **agent-tailored** surface for the GraphQL pivot. -2. **Generated TypeScript accessors** — typed queries aligned with codegen ([`packages/codegen`](packages/codegen)). -3. **GraphQL** — keep for humans, Studio, and apps already on Apollo. -4. **Append / deposit API** — narrow writes: create or append artifact rows with validation (no general transactional DB). -5. **Watch mode** — content reload without full process restart ([audit gap](flatbread-flow-pmf-audit.md) on local loop). -6. **Conventions preset** — optional mapping from common paths (`AGENTS.md`, `SKILL.md`, `.cursor/rules`, `.handoff/*`, `.GCC/branches/*`, `.cs/*`) into derived or linked collections without forcing migration day one. - -## 10. Strategic Implications - -- **Query surfaces:** GraphQL becomes explicitly **one adapter** over a single relational model; MCP and TS carry agent workflows. -- **Writes:** First-class but **scoped**—append-only artifact deposits + validation—not OLTP. -- **ICP shift:** From "relational markdown for sites" toward **"multi-session agentic efforts in repos"**—faster-moving buyer and clearer wedge than generic flat-file DB comparisons (per audit). -- **Roadmap elevation:** ID normalization, relation validation, and watch mode rise from hygiene to **product blockers** for this use case. - -## 11. Tensions With The PMF Audit - -Cross-check against [What Not To Build Yet](flatbread-flow-pmf-audit.md) and related warnings. - -| Audit constraint | Relationship to Posture C (Proof) | -| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Do not build hosted CMS, dashboard, or editing UI yet | **Respects.** MCP/CLI/codegen only; no mandated admin UI. | -| Do not compete with full databases on transactions, auth, permissions, high-scale writes | **Respects** if writes stay append-oriented, local, and validation-focused; **stretches** if users demand multi-user locking or roles—then explicitly out of scope. | -| Do not over-invest in many source plugins before local filesystem relational workflow is excellent | **Respects** if Proof ships as one filesystem preset + optional path mappings; **stretches** if many SaaS sources are added prematurely—avoid. | -| Do not keep GraphQL as the only story | **Aligns.** MCP + TS are first-class in this thesis. | -| Do not add complex migration systems before schemas, IDs, validation, exports, watch | **Aligns.** Proof assumes those foundations land first; **reopens** migration only as import from handoff/GCC folders once core is stable. | -| Avoid database replacement framing until write path exists | **Stretches language**—"relational layer" must stay precise: **not** a serverless Postgres; **reopens** the need for a documented, minimal write story before marketing breadth. | - -Section **8** (schema sketch) and **9** (surfaces) should stay synchronized with audit honesty: no promise of generic mutations until shipped. - -## 12. Validation Experiments - -Before roadmap commitment: - -1. **Preset wire-up** — Point Flatbread at an existing agent folder in a real repo (e.g. `.agents/` or documented handoff layout). Can one MCP query return _all blocking decisions for the current effort with plan title_ without custom scripts? -2. **Adversarial schema** — One Proof schema against three layouts: Claude Code-oriented tree, Cursor rules + skills layout, GCC `.GCC/` layout. Where does a single schema break? What mapping layer is minimal? -3. **Token budget** — Compare cold-start context stuffing vs Flatbread-mediated retrieval over a multi-session effort; benchmark against published handoff savings orders (e.g. AgentHandoff's reported range) as a directional bar, not a guarantee. - -## 13. What Not To Build Yet - -- Hosted editing UI or CMS. -- Mandatory vector index inside core (optional plugin later). -- Arbitrary update/delete mutation API on arbitrary fields. -- New source plugins for proprietary SaaS artifact stores before filesystem Proof is excellent. -- Replacing Claude Code, Cursor, or Codex harnesses—Flatbread should **compose**, not compete. - -## 14. Bottom Line - -**Thesis:** Flatbread should own **typed, validated, queryable effort graphs in git**, exposed to agents primarily via **MCP and generated TypeScript**, with GraphQL as a parallel adapter. **Next step:** run the three validation experiments in §12; let results set the minimum mapping layer and write-scope for v1 of the preset. - ---- - -## References (selected) - -- Wu et al., [Git Context Controller](https://arxiv.org/html/2508.00031v2) (GCC). -- Vasilopoulos, [Codified Context: Infrastructure for AI Agents in a Complex Codebase](https://arxiv.org/html/2602.20478v1). -- Lore: [Repurposing Git Commit Messages as a Structured Knowledge Protocol](https://arxiv.org/abs/2603.15566) (arXiv). -- Claude Code [Skills documentation](https://code.claude.com/docs/en/skills). -- [AgentHandoff](https://github.com/aceandro2812/AgentHandoff), [claude-sessions](https://github.com/hex/claude-sessions), [agmem](https://github.com/vivek-tiwari-vt/agmem), [Agentic Beacon](https://github.com/Shadowsong27/agentic-beacon). -- Vault / knowledge MCP examples: [markdown-vault-mcp](https://github.com/pvliesdonk/markdown-vault-mcp), [engraph](https://github.com/devwhodevs/engraph). diff --git a/internal/flatbread-flow-agentic-workflows.md b/internal/flatbread-flow-agentic-workflows.md index 3e87a2c6..1c1a86d0 100644 --- a/internal/flatbread-flow-agentic-workflows.md +++ b/internal/flatbread-flow-agentic-workflows.md @@ -1,6 +1,6 @@ # Flatbread Flow Agentic Workflows -This playbook turns `flatbread-flow-pmf-audit.md` into an execution workflow for agents working on Flatbread. Use it when planning or implementing product changes that affect the relational content model, GraphQL schema, generated TypeScript, CLI, examples, docs, or release process. +This playbook turns the PMF audit into an execution workflow for agents working on Flatbread. Use it when planning or implementing product changes that affect the relational content model, GraphQL schema, generated TypeScript, CLI, examples, docs, or release process. ## Product Direction diff --git a/internal/flatbread-flow-pmf-audit.md b/internal/flatbread-flow-pmf-audit.md deleted file mode 100644 index e0d5c677..00000000 --- a/internal/flatbread-flow-pmf-audit.md +++ /dev/null @@ -1,173 +0,0 @@ -# Flatbread Flow PMF Audit - -Generated from the DAG task runner audit on May 7, 2026. - -> This report records the repository as it was in May 2026. It is background -> research, not current setup instructions. For the current development steps -> and watch behavior, see [Local development loop](./docs/local-dev-loop.md). - -**Buyer-facing comparison rubric** (SQLite, CMS, Contentlayer-like, agent-artifact workflows; issue #144 acceptance-style criteria): [docs/comparison.md](./docs/comparison.md). - -Canvas: `file:///Users/tonyketcham/.cursor/projects/Users-tonyketcham-Code-Github-personal-flatbread/canvases/dag-flatbread-pmf-audit.canvas.tsx` - -## Executive Summary - -Flatbread has the strongest product-market-fit path as a Git-native relational content layer for developer-authored Markdown/YAML and similar flat-file content. It looks much weaker if positioned as a general relational flat-file database, because developers will compare it against SQLite, Prisma/Drizzle, embedded databases, CMSs, Airtable/Notion exports, and local-first data stores. - -The core issue is that the current product flow is GraphQL-first and appears GraphQL-required for the main developer path: schema generation, querying, filtering, relations, runtime server access, and TypeScript codegen all run through GraphQL concepts or artifacts. That can be a wedge for teams that already want a content graph, but it narrows appeal for developers who simply want typed relational data in flat files. - -Recommended positioning: - -> Flatbread is a Git-native relational content layer for TypeScript apps: model collections and relationships over flat files, query them with GraphQL or generated TypeScript APIs, and keep full ownership of your data in Git. - -## Current Flow - -The audited flow is roughly: - -1. Define sources and transformers over local files. -2. Infer or generate collections, fields, and relations. -3. Generate a GraphQL schema. -4. Serve the schema through Apollo/Express or use a provider wrapper. -5. Query data through GraphQL documents or raw GraphQL strings. -6. Optionally run GraphQL Code Generator to emit TypeScript artifacts. - -Evidence of GraphQL centrality: - -- `packages/core/src/generators/schema.ts` builds GraphQL object types, resolvers, and query fields from Flatbread collections. -- `packages/core/src/providers/base.ts` exposes a provider query path around `graphql(...)`. -- `packages/core/src/resolvers/arguments.ts` resolves filters by constructing and executing internal GraphQL queries. -- `packages/flatbread/src/graphql/server.ts` builds and serves an Apollo GraphQL server. -- `packages/codegen/src/generator.ts` uses GraphQL Code Generator over printed schemas and `.graphql` documents. -- `examples/nextjs/generated/graphql.ts` contains `TypedDocumentNode` GraphQL artifacts. -- `examples/nextjs/lib/graphql.ts` and `examples/sveltekit/src/routes/+page.js` call `/graphql` directly. -- `packages/flatbread/README.md`, `packages/source-filesystem/README.md`, and `packages/transformer-markdown/README.md` frame the product around querying content with GraphQL. - -## PMF Gaps - -### 1. GraphQL Is The Product Interface, Not Just An Adapter - -Severity: High - -Flatbread currently asks users to understand GraphQL schema, queries, filters, documents, codegen, and a server endpoint early in the experience. That is fine for GraphQL-positive teams, but it is a major adoption filter for developers whose job is "store relational data in flat files." - -Product implication: Make GraphQL explicit as one interface, not the whole product. Add a generated TypeScript API or object query layer that lets developers consume relational flat-file data without operating a GraphQL sidecar. - -### 2. The Relational Data Model Is Implied More Than Taught - -Severity: High - -The repo has evidence of collections, references, filters, and nested relations, but the first-time mental model is still "files become GraphQL" more than "flat files become typed relational collections." Developers evaluating data tooling need clear primitives: collections, records, IDs, references, cardinality, constraints, validation, and query semantics. - -Product implication: Document relational modeling as the core concept. Make "posts -> authors -> tags" the canonical first win and explain the backing files, generated schema, and query APIs from that model. - -### 3. Write, Mutation, And Data Management Workflows Are Missing - -Severity: High - -Flatbread appears strongest as a read/query layer over local content. For developers who hear "relational data in flat files," the missing pieces are writes, updates, safe edits, bulk import/export, conflict handling, and explicit ownership guarantees. - -Product implication: Either keep positioning focused on read-mostly content graphs, or add a deliberate write/editing story. Avoid sounding like a database replacement until the write path exists. - -### 4. Constraints And Integrity Guarantees Are Not First-Class - -Severity: High - -Relational storage buyers expect duplicate ID detection, missing reference errors, relation shape validation, uniqueness, required fields, and useful diagnostics. The current evidence points to flexible GraphQL/runtime behavior and loose core content typing rather than a strong integrity layer. - -Product implication: Add relation validation and schema validation before expanding the surface area. Flat files become compelling when the product catches broken references before production. - -### 5. The Local-First Dev Loop Is Incomplete - -Severity: Medium-High - -Flatbread is naturally local-file-backed, but the docs indicate runtime content change detection is not supported and requires restart. Codegen has watch behavior, but the content loading, schema rebuild, server, and framework examples do not yet tell one crisp "edit file, see app update" story. - -Product implication: Prioritize a unified watch mode that reloads content, rebuilds schema, regenerates types, and updates examples without manual restarts. - -### 6. Type Safety Arrives Too Late - -Severity: Medium-High - -Generated GraphQL artifacts provide useful TypeScript result types, but config typing, content typing, and ID semantics are weaker. Core content still exposes loose surfaces such as arbitrary keyed content, and GraphQL query args appear to flatten IDs into strings. - -Product implication: Generate or infer types from Flatbread config and content schemas before GraphQL documents enter the picture. Normalize ID handling across files, relations, GraphQL, and generated APIs. - -### 7. Onboarding Is Fragmented - -Severity: Medium - -There is no root `README.md` anchoring the user journey. Guidance is split across `CONTRIBUTING.md`, root `package.json`, package READMEs, and example READMEs. The commands and concepts include `pnpm play`, `pnpm dev`, `npx flatbread init`, `npx flatbread codegen`, `.graphql` documents, codegen plugins, and a separate GraphQL server before the product promise is fully established. - -Product implication: Create one canonical quickstart that starts from a relational flat-file example and reaches a typed query result quickly. - -### 8. Portability Is Under-Explained - -Severity: Medium - -Flat files imply data ownership, but the current product story does not clearly expose import/export, snapshots, CSV/JSON output, schema export, backup, or migration paths. Export mainly happens through GraphQL responses or generated TypeScript artifacts. - -Product implication: If pursuing broader relational data, add explicit import/export tooling. If staying content-focused, document raw files, Git, GraphQL introspection, and generated types as the portability story. - -### 9. Positioning Is Broader Than The Evidence Supports - -Severity: Medium - -The repo evidence is strongest for Markdown/YAML content, framework examples, image/content transformers, GraphQL querying, and TypeScript codegen. It is weaker for a general-purpose relational flat-file data platform. - -Product implication: Avoid database replacement framing. Lead with "content graph in your repo" and "relations without a CMS." - -## Recommended Roadmap - -### Near Term - -- Tighten config typing and reduce loose `any` surfaces where developers define content models. -- Normalize ID handling across internal models, GraphQL arguments, and generated types. -- Add relation validation with clear diagnostics for missing targets, duplicate IDs, invalid shapes, and unsupported cardinality. -- Ship one polished demo where editing Markdown/YAML relations locally updates typed relational queries immediately. -- Rewrite docs around relational modeling patterns before GraphQL API usage. - -### Next - -- Add generated TypeScript accessors alongside GraphQL. -- Add content watch mode across loaders, schema generation, codegen, and examples. -- Provide relation-aware examples for common app shapes: blog authors, product catalog, docs navigation, changelog/releases. -- Add JSON and CSV snapshot export for collections. - -### Later - -- Add framework adapters after the core local filesystem workflow feels excellent. -- Add migration/import guides from hand-rolled Markdown/YAML, Contentlayer-like systems, Airtable exports, Notion exports, and static data folders. -- Add indexing or richer filtering only when real projects expose performance limits. - -## Agent Artifact Opportunity - -Severity: Medium (strategic option; validates existing near-term gaps rather than inventing new unrelated work) - -Agent harnesses emit large markdown artifacts but rarely persist them as a **typed graph** tied to a single effort (feature, spike, or research thread). The 2026 landscape mixes manifests (`AGENTS.md`), handoff folders, memory-as-VCS (e.g. GCC-style trees), and vault MCPs with search—but almost nowhere gets **reference integrity, stable IDs, and relational queries** over those files. - -Flatbread can pivot query surfaces beyond GraphQL-only by positioning as **the relational layer for agent efforts in git**: collections and refs over markdown/YAML, with **MCP and generated TypeScript** as agent-first adapters alongside GraphQL. That use case **raises the priority** of work already called out near term—config typing, ID normalization, relation validation, and watch mode—and stays compatible with “no hosted CMS/UI yet” if writes stay narrow (e.g. append-oriented artifact deposits). - -Full survey, five-layer SOTA map, product postures (including recommended **Proof**), schema sketch, validation experiments, and explicit tensions with this audit’s “What Not To Build Yet” list: **[flatbread-agent-artifact-opportunity.md](./flatbread-agent-artifact-opportunity.md)**. - -## Near-Term Experiments - -- Relational starter benchmark: can a developer model `posts -> authors -> tags` in under 10 minutes and query it safely? -- Watch-mode demo: does editing a flat file update app data without restart or manual codegen? -- Type-safety test: where do TypeScript users still hit weak inference, `any`, or confusing generated types? -- Exit-story test: does one-command `flatbread export json/csv` increase trust in adoption interviews? - -## What Not To Build Yet - -- Do not build a hosted CMS, dashboard, or editing UI yet. -- Do not compete with full databases on transactions, auth, permissions, or high-scale writes. -- Do not over-invest in many source plugins before the local filesystem relational workflow is excellent. -- Do not keep GraphQL as the only story if the ICP is broader than GraphQL-positive content teams. -- Do not add complex migration systems before schemas, IDs, validation, exports, and local watch behavior are settled. - -## Bottom Line - -Flatbread should not currently chase "relational data in flat files" as a broad category. The sharper wedge is: - -> Git-native relational content for TypeScript apps, backed by flat files, with GraphQL and generated types when teams want them. - -The highest-leverage PMF work is to make GraphQL's role explicit, teach the relational content model directly, add validation and type guarantees around file-backed relations, and make the local edit/query loop excellent. diff --git a/internal/flatbread-search-and-memory-research.md b/internal/flatbread-search-and-memory-research.md deleted file mode 100644 index 04dbff85..00000000 --- a/internal/flatbread-search-and-memory-research.md +++ /dev/null @@ -1,708 +0,0 @@ -# Flatbread Search and Memory Research - -A weighing of opportunities, hypotheses of outcome, and an ideal end state for the Flatbread + Proof axis as a search-and-memory substrate. - -> Companion to [`flatbread-agent-artifact-opportunity.md`](flatbread-agent-artifact-opportunity.md) and [`flatbread-flow-pmf-audit.md`](flatbread-flow-pmf-audit.md). Authored via a `/proof` DAG; intermediate dossier names were folded into this report and are not checked into the repo. Evidence for claims is in repo paths cited inline and in **§13 — References** (no ephemeral `file://` paths). - ---- - -## 1. Executive Summary - -The 2026 retrieval frontier has converged on a small set of patterns — structure-aware AST chunking, hybrid dense + sparse retrieval with reciprocal-rank fusion, small Apache-2.0 cross-encoder rerankers, hierarchical (RAPTOR) and graph-aware (GraphRAG / LightRAG / PathRAG) retrieval, Anthropic-style contextual prefixing, and bi-temporal git-native memory. Every one of those patterns spends most of its index budget paying an LLM to extract entities and edges from prose, and every one of them treats the index as a binary blob outside the user's repo. **Flatbread + Proof can occupy a category nobody else can: a typed relational substrate where the user's markdown already carries the gold-label graph (`refs`, wikilinks, headings, folders) and the agent's DAG run already carries another (depends_on, ranks, convergence loops), fused through one schema, queried through GraphQL / MCP / generated TypeScript, with a deterministic git-friendly index.** The thesis of this report is that the search and memory work is not a side quest from the Effort Graph thesis of [`flatbread-agent-artifact-opportunity.md`](flatbread-agent-artifact-opportunity.md) — it is the same substrate, viewed from two ends: humans browsing related content on one side, agents recalling and writing efforts on the other. The recommended trajectory is **Posture B (Effort-Graph + Hybrid Retrieval)**, sequenced so the relational primitives the PMF audit already prioritizes (config typing, ID normalization, validation, watch mode) land first and unlock everything else as natural extensions. - -**Five headlines:** - -- **Markdown's structure is already gold-label graph data**, and treating it as such collapses ~70% of GraphRAG's index cost (`sota-graph-structure.md` §10.5, §14.1; `synthesis-novel.md` N1). The expensive thing the field pays for at index time has, for Flatbread users, already been paid by the author. -- **Hybrid retrieval (BM25 + dense + RRF) plus a small Apache-2.0 reranker is now table stakes**, runnable in pure TypeScript with no daemon (Qwen3-Embedding-0.6B + `bge-reranker-v2-m3` over SQLite + `sqlite-vec` + FTS5 — `sota-dense-sparse-hybrid.md` §8 Tier-1; `sota-embeddable-runtimes.md` §Shortlist). Shipping it sets a license-clean default the entire 12-opportunity catalogue can reuse. -- **The single most acute bug in Proof today is the `UPSTREAM_SNIPPET_CAP=2000` truncation** in [`packages/proof/src/run_dag.ts`](packages/proof/src/run_dag.ts) (`audit-proof-context.md` §1.2–1.3). Replacing the hand-coded `SECTION_DROP_PRIORITY` with content-aware reranking is a small, local edit and the most-cited dossier-wide quality lever (`synthesis-proof.md` O3). -- **An MCP surface (`semantic_search`, `related_to`, `expand_neighborhood`, `summarize_collection`) is the cheapest way to break Flatbread's GraphQL-only positioning** (`flatbread-flow-pmf-audit.md` §1; `synthesis-flatbread.md` F10) without shipping a CMS. It is also the only realistic substrate for Proof (and Cursor / Claude Code / Codex) to share memory. -- **The defensibly novel bet** is to recognize that _both_ the user's repo and the agent's DAG are already graphs and to fuse them as a single typed schema, with the index as deterministic JSONL committed alongside the markdown when teams want it (`synthesis-novel.md` Industry Bet I — "Git Mind"). No incumbent — Letta Context Repositories, Cursor Memories, Mem0, Zep, Microsoft GraphRAG — combines git substrate, DAG-node memory units, relational query, and tool-portable projection in one product. - ---- - -## 2. The Problem - -Flatbread's relational filter DSL is excellent on **declared frontmatter columns and configured `refs`**, and it is structurally blind to **everything inside the markdown body** — heading structure, wikilinks, code fences, callouts, embedding-space neighbors, graph neighborhoods past the explicit `refs`. Proof's parent → child context passing is excellent on **`depends_on` edges**, and is structurally blind to **everything else** — siblings in the same rank, grandparents reached through edges, prior runs, the host repository the agents are _editing_. Both halves of the system fail in the same shape: when the user asks a question whose answer is _in the corpus_ but isn't _in a column_, the system has no recourse. Frontmatter-only retrieval and parent-text-truncation are two faces of the same blindness. - -### 2.1 Frontmatter-only retrieval is structurally insufficient - -The internal Flatbread codebase audit (sections cited here match the audit dossier §2.4–2.5, §3.1, §5) is unambiguous about today's retrieval surface in [`packages/core`](packages/core): - -- The `filter` JSON DSL (`packages/core/src/utils/sift.ts`) is a Mongo-style comparator engine: `eq`, `ne`, `lt/lte/gt/gte`, `in/nin`, `includes/excludes`, `regex`, `wildcard`, `exists`, `strictlyExists`. It runs over an **in-memory `EntryNode` JSON graph**, with `resolveFilter` (`packages/core/src/resolvers/arguments.ts`) executing an internal GraphQL subquery to fetch only the leaf paths a filter mentions, then `sift()`-ing the result. -- Boolean composition is **implicit AND** across flattened leaf conditions (`reduceBooleans('and')` in `packages/core/src/utils/sift.ts`); `$or` and `$nor` are unimplemented in the default sift path even though `reduceBooleans` supports `or` internally. `findMany(ids)` lacks the `filter` argument that `all*` has. `sortBy` only resolves top-level keys (`packages/core/src/resolvers/arguments.ts:162-176`). -- The `transformer-markdown` pipeline ([`packages/transformer-markdown`](packages/transformer-markdown)) emits `_filename`, `_path`, `_slug`, `_content.raw`, and lazy `_content.html` / `_content.excerpt` / `_content.timeToRead`. It does **not** emit a heading hierarchy, wikilinks, code-fence metadata, callouts, or any other AST-derived structural fields. There is no chunking; the entire body is a single string scalar. -- There is no lexical index, no embedding, no reranker, no graph traversal beyond the explicit `refs` wired through `addRelation` in `packages/core/src/generators/schema.ts`. - -The downstream consequences are exactly the ones the dossiers diagnose: - -- **Author-visible body content is invisible to retrieval.** A user can ask "find docs whose outline mentions Postgres tuning" only by writing a `regex` filter against `_content.raw`, which (a) is a brittle string match, (b) routinely runs against _megabyte_ strings because `cloneDeep`-of-collection is a per-resolver pattern (`audit-flatbread-retrieval.md` §9 Q7), and (c) cannot be safely sent from a JSON HTTP client because `sift.regex` expects a live `RegExp` (`packages/core/src/utils/sift.ts:75-76`). -- **Wikilinks are dead text.** The Obsidian vault's signature graph — the linked-mention `[[Note]]` edge — has zero presence in Flatbread's GraphQL schema. The `refs` mechanism only honors fields the user wired in their config; the body's bidirectional graph is uncaptured (`audit-flatbread-retrieval.md` §3.1). -- **"Related content" defaults to tag collisions.** Without embeddings and without body-derived edges, the only "related" signal a Flatbread-backed site has is shared frontmatter values. For garden-style wikis and prose-heavy blogs that is a near-total miss; for tag-disciplined developer documentation it works for the tag's intent and nothing else. -- **Agents cannot ask "what is in here?" without grepping**. Cursor's published numbers report **+12.5% accuracy** when semantic search supplements grep on 1,000+-file repos (`sota-agent-memory.md` §2.8); Anthropic Contextual Retrieval reduces top-20 retrieval failures by **35–67%** (`sota-dense-sparse-hybrid.md` §6). Flatbread today provides neither, so any agent tool that wants to ground in markdown rediscovers the corpus on each invocation. - -The PMF audit treats this as a near-term hygiene matter ([`flatbread-flow-pmf-audit.md`](flatbread-flow-pmf-audit.md) §1 GraphQL-as-product, §3 missing writes, §4 missing constraints, §5 watch mode). The retrieval gap is more than hygiene: when a competing product can answer "find blocking decisions for effort X about retry semantics" with one query, Flatbread's frontmatter-only filter looks like a half-finished prototype regardless of how clean its relational primitives are. - -### 2.2 Parent-text truncation is the same bug, on the agent side - -The internal Proof audit (same methodology doc; sections §1.1–1.5, §2, §8, §10 in the audit dossier) names the analogous problem in [`packages/proof/src`](packages/proof/src): - -- Each LLM task's `assistant` stream is appended to a `BoundedTextBuffer` capped at `STREAM_CAP = 4000` chars (`packages/proof/src/run_dag.ts:1124-1135`). The `resultText` field that downstream tasks see is the buffer's render — early prose is dropped with a truncation banner. -- When a child task assembles its prompt, `buildUpstreamContext` (`packages/proof/src/run_dag.ts:1606-1628`) loops over each `depends_on` parent and includes **at most `UPSTREAM_SNIPPET_CAP = 2000` chars per parent** through `truncateUpstreamSnippet`. The truncator is _section-aware_ — it splits on `## Headings` and drops sections in a fixed `SECTION_DROP_PRIORITY` order (`Current contract` → `Validation plan` → `Human checkpoints` → `Migration impact` → `Proposed contract`) — but the priority list is **hand-coded for one task shape** and has zero awareness of _what the child actually wants to know_. When the priority list runs out, it falls back to a hard slice. -- There is **no embedding, reranker, episodic store, cross-rank retrieval, or repo-aware retrieval** anywhere in the runner. The only structured artifacts are the `--findings-dir` sidecars (themselves a cache of the same capped `resultText`) and the optional `--full-output-dir` uncapped dumps that downstream tasks never read. Across runs there is no episodic memory unless the operator wires `--state-path` and reuses it by hand. - -The audit's named pain points map onto the same retrieval failures the markdown side suffers from (`audit-proof-context.md` §10): - -1. **Duplicated discovery** — siblings in the same rank cannot see each other's partial conclusions because `Promise.all` makes them concurrent and `buildUpstreamContext` only reads `depends_on`. Three subagents independently grep the same files. -2. **Contradictory downstream merges** — a merge task only receives capped snippets from immediate parents; conflicting rationales from earlier ranks are truncated away. -3. **Lost rationale** — `STREAM_CAP` + `UPSTREAM_SNIPPET_CAP` drop reasoning steps; children inherit conclusions without the _why_. -4. **Stale or empty failure context** — failed parents surface `(failed: …)` only; no automatic richer error telemetry in prompts. -5. **Reviewer blind spots** — convergence reads specific headings (`Blockers`, `High-severity findings`); unstructured insights elsewhere never trigger `--converge-on` loops. - -### 2.3 Why the two are the same problem - -The shared diagnosis is not "retrieval is missing" — Flatbread has a query layer; Proof has prompt stitching — it is that **both sides treat the corpus as opaque text past a fixed boundary** (the frontmatter, the snippet cap) and have no protocol for asking "which slice of the body is relevant _to this question_?" The answer that the rest of the field has converged on is some combination of structure-aware chunking + hybrid retrieval + reranking + graph expansion + (optionally) hierarchical summary trees. The unique observation for the Flatbread + Proof axis is that **the structure that drives chunking and the graph that drives expansion already exist in the source — they just aren't materialized as queryable columns yet** (`synthesis-novel.md` §0; `sota-graph-structure.md` §14.1). Once they are, the same primitive serves "related posts on a docs site" and "what did we decide about idempotency in the previous Proof run" with one schema and one query language. - ---- - -## 3. State of the Art - -The 2024–2026 retrieval/memory literature consolidates into four families with distinct primitives: (a) **dense / sparse / hybrid retrieval over chunks** with cross-encoder rerankers; (b) **structural and graph-based retrieval** that exploits document hierarchy and explicit edges; (c) **agent memory** systems with extract / consolidate / forget loops; and (d) **embeddable runtimes** that determine what can actually ship inside a TypeScript-first product. Below is the condensed taxonomy with one comparison table per family. Numbers are quoted only when the upstream dossiers cite them; license callouts matter because Flatbread defaults must avoid CC-BY-NC weights (`sota-dense-sparse-hybrid.md` §8 Tier-3). - -### 3.1 Dense, sparse, and hybrid retrieval - -The dossier `sota-dense-sparse-hybrid.md` is the canonical reference and the source of every number below. - -The single-vector embedding world fragmented sharply between mid-2024 and late 2025. Three forces reshaped the leaderboard: LLM-backbone embedders (Mistral-7B, Qwen2/3, Gemma3) push MTEB averages above 70; **Matryoshka Representation Learning** lets the same vector serve at 256 / 512 / 1024 / 2048 dims; instruction-tuned and MoE variants narrow the gap between 0.5B and 7B models. Late-interaction (ColBERT-class) keeps one vector per token and scores via MaxSim, beating single-vector cosine on long-tail queries at 30–100× storage cost. Learned-sparse models (SPLADE family, Qdrant's BM42, BGE-M3's sparse output) bring transformer-derived term weights into classical inverted indexes. **Hybrid lexical + dense beats either alone on BEIR by 3–8 nDCG@10** (`sota-dense-sparse-hybrid.md` §4); **Reciprocal Rank Fusion (RRF) with `k=60` is the default of every major engine** (Azure AI Search, Elasticsearch, Weaviate, Qdrant). Cross-encoder rerankers are the largest single quality lever after retrieval — Anthropic's Contextual Retrieval reports a reranker reduces top-20 retrieval failure by an additional **~32 points** on top of contextual BM25 + embeddings (`sota-dense-sparse-hybrid.md` §5). - -Chunking is where most retrieval failures _originate_. The 2024 wave gave us four high-leverage strategies: **structure-aware markdown** chunking via `mdast` AST (the unsung hero for any markdown corpus); **late chunking** (Jina, Sep 2024 — embed the whole doc with a long-context model, then mean-pool over chunk-shaped slices, +5–10% nDCG@10 on chunk-needle tasks); **Anthropic Contextual Retrieval** (prepend a 50–100-token LLM-generated locator before embedding; **−35% top-20 retrieval failures, −49% with reranking, −67% with reranking + BM25**); and **propositional / Dense X** chunking (rewrite paragraphs into atomic propositions; +9 Recall@5). The cleanest pre-retrieval tricks are **HyDE** (hypothetical-document embeddings, +4.2% nDCG@10 in the Rocchio-weighted variant), **multi-query / RAG-Fusion** (paraphrase, retrieve, RRF), **step-back prompting**, and **query routing** (classify into `{factoid, prose, code, multi-hop, nav}` and dispatch to the specialist retriever). - -#### Comparison table — dense / sparse / hybrid components - -| Category | Pick | License | JS/TS feasible? | Headline number | Source | -| ------------------------- | ----------------------------------------------------------- | ------------------- | ----------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------- | -| Dense embedder, on-device | **Qwen3-Embedding-0.6B** (1024-dim, 32k ctx, MRL) | Apache 2.0 | Yes — `transformers.js` v3 + WebGPU | MTEB multilingual avg ~64.3, beats BGE-M3 at fraction of size | `sota-dense-sparse-hybrid.md` §1 | -| Dense embedder, server | **Voyage-3-large** API | Commercial | API only | MTEB ≈ 68.2; binary 512-dim ~200× storage win | `sota-dense-sparse-hybrid.md` §1 | -| Three-modes-one-pass | **BGE-M3** (568M, 1024-dim, 8192 ctx) | MIT | Yes — `fastembed-js` | One forward pass = dense + sparse + ColBERT vectors; BEIR ~48.8 dense, ~51.8 hybrid | `sota-dense-sparse-hybrid.md` §1 | -| Sparse / lexical floor | **BM25 over `tsvector`** / **SQLite FTS5** | Public domain / OSS | Yes | Zero new infra; ships in the DB | `sota-dense-sparse-hybrid.md` §3 | -| Learned sparse pragmatic | **BM42** (90 MB transformer attentions) | Apache 2.0 | Yes — `onnxruntime-node` | "Experimental"; sometimes loses to plain BM25 with good tokenizer | `sota-dense-sparse-hybrid.md` §3 | -| Hybrid fusion default | **RRF k=60** in SQL | n/a | Pure SQL CTE | Score-agnostic; same default as every major engine | `sota-dense-sparse-hybrid.md` §4 | -| Reranker default | **`bge-reranker-v2-m3`** (278M ONNX) | Apache 2.0 | Yes — `onnxruntime-node` | BEIR ~51.8; 30–100 ms per 20 candidates | `sota-dense-sparse-hybrid.md` §5 | -| Reranker premium | **`mxbai-rerank-base-v2`** (0.5B ONNX) | Apache 2.0 | Yes | BEIR ~55; +3–5 nDCG over bge-v2-m3 | `sota-dense-sparse-hybrid.md` §5 | -| Reranker hosted | **Voyage rerank-2.5-lite** (instruction-following, 32k ctx) | Commercial | API only | +7.16% over Cohere Rerank v3.5; $0.020/1M tok | `sota-dense-sparse-hybrid.md` §5 | -| Chunking default | **Structure-aware mdast** (`remark` + `chunkdown`) | MIT | Yes — JS-native | Markdown's own structure is the best signal | `sota-dense-sparse-hybrid.md` §6 | -| Index-time augmentation | **Anthropic Contextual Retrieval** (prefix + prompt cache) | n/a (recipe) | Yes — any LLM | −35 / −49 / −67% retrieval failures (with reranker / +BM25) | `sota-dense-sparse-hybrid.md` §6 | -| Late interaction (opt-in) | **`mxbai-edge-colbert-v0-17m`** in `fast-plaid-web` (WASM) | Apache 2.0 | Yes — WASM | 17M-param ColBERT; ~6.2 MB index, sub-second cold load | `sota-dense-sparse-hybrid.md` §2 | - -Avoid in defaults: **NV-Embed-v2** (CC-BY-NC), **SPLADE-v3** (CC-BY-NC-SA), **Jina Reranker v2 weights** (CC-BY-NC) (`sota-dense-sparse-hybrid.md` §8 Tier-3). - -### 3.2 Structural and graph retrieval - -The `sota-graph-structure.md` dossier organizes the field into three complementary families (`sota-graph-structure.md` §0): - -1. **Hierarchical summarization** — RAPTOR-style recursive trees that give the LLM a _zoomable_ abstraction ladder rather than a flat list of leaves. -2. **LLM-extracted entity / relation graphs** — Microsoft GraphRAG, LightRAG, HiRAG, Fast GraphRAG, PathRAG. They materialize a graph from prose, then partition (Leiden community detection) or prune (relational paths) at query time. -3. **Adaptive / self-reflective retrieval** — Self-RAG, Corrective RAG (CRAG), Tree-of-Clarifications. Retrieval becomes a _decision_ the model makes per segment, with reflection tokens or evaluator heads gating the loop. - -The high-leverage observation, repeated across the dossier, is that **the expensive step in every graph-RAG paper — "use an LLM to extract entities and edges from prose" — has already been done by the markdown author when they wrote frontmatter `refs`, `[[wikilinks]]`, headings, and folder structure** (`sota-graph-structure.md` §0, §10.5, §14.1). The $50–$200 / 1M-tokens index cost dominated by `extract_graph` and `create_community_reports` in Microsoft GraphRAG (`sota-graph-structure.md` §3) is recoverable for _zero_ on a vault that already declares its graph; LLM extraction need only fill in the _prose-only residue_. PathRAG over the existing graph operates at **no extra index cost** and outperforms GraphRAG / LightRAG / NaiveRAG on six datasets × five metrics (comprehensiveness, diversity, logicality, relevance, coherence), with the biggest deltas on logicality and coherence — exactly what one expects from path-form prompting vs neighbor-soup prompting (`sota-graph-structure.md` §6). - -#### Comparison table — graph and structural retrieval - -| Method | Index cost | Update story | Reported delta vs flat RAG | License | JS/TS path | -| ---------------------------------------------------------- | ----------------------------------------- | -------------------------- | ---------------------------------------------------------------------- | ---------- | -------------------------------- | -| **RAPTOR** | Medium (recursive LLM summarization) | Rebuild on append | +20% absolute on QuALITY (GPT-4); strong on NarrativeQA, QASPER | MIT | Easy port (~400 LoC) | -| **Microsoft GraphRAG** | High (LLM extraction + community reports) | Batch | Dominates flat RAG on global summarization; +25 pts on 2WikiMultiHopQA | MIT | GraphRAG.js (community) | -| **LightRAG** | Medium | **Incremental** | 60–85% win-rate on QFS; weaker than GraphRAG on multi-hop | MIT | `@graphrag-js/light` | -| **HiRAG** | Medium-high | Batch | +2–8 pts over GraphRAG/LightRAG/RAPTOR | MIT | Small port | -| **Fast GraphRAG** | **Low** (6× cheaper than MS) | Incremental | 27× faster, 40% more accurate vs MS GraphRAG (per repo bench) | MIT | `@graphrag-js/fast` | -| **PathRAG** | Low (no extra index cost) | Same as base | Beats GraphRAG/LightRAG on 6 datasets × 5 metrics | research | Small port (~500 LoC) | -| **GNN-RAG** | High (GNN training) | Batch | +8.9–15.5 F1 on multi-hop KGQA (WebQSP/CWQ) | research | Python sidecar | -| **Tree-of-Clarifications** | Per-query LLM cost | n/a | SOTA on ASQA Disambig-F1/ROUGE | research | Trivial port | -| **Self-RAG** | Training cost | n/a | Beats ChatGPT + RA Llama-2-Chat on QA / fact-verify / long-form | MIT | Reflection-token loop is generic | -| **CRAG** | T5 evaluator | n/a | Significant on PopQA/Bio/PubQA/ARC | research | T5 head + decompose-recompose | -| **Cognee** | Medium (LLM cognify) | Incremental | Up to 92.5% internal retrieval | Apache 2.0 | Python only | -| **Obsidian MCPs** (engraph, vault-search, knowledge-graph) | Low (no LLM extraction) | Incremental (file watcher) | n/a (different evaluation) | Mostly MIT | TS-native | - -The Obsidian MCP cluster (`sota-graph-structure.md` §9) is the closest existing pattern to what Flatbread wants to ship: **hybrid retrieval (BM25 + embeddings + RRF), graph expansion (BFS over wikilinks ± backlinks ± tags), optional cross-encoder rerank, local-first**. Replace `[[wikilink]]` resolution with Flatbread's `refs` resolution and you have a working substrate. - -A systematic re-evaluation of the GraphRAG family ([Han et al., arXiv:2502.11371](https://arxiv.org/abs/2502.11371)) is worth quoting honestly: **GraphRAG underperforms vanilla RAG on many real-world single-hop tasks**. The win is concentrated on multi-hop and global-summarization queries. The corollary for Flatbread: ship hybrid retrieval as the default; layer graph expansion / RAPTOR / community reports as opt-in for the workloads they actually win on. - -### 3.3 Agent memory - -The `sota-agent-memory.md` dossier organizes 13 systems along three axes (`sota-agent-memory.md` §1.1–1.3): - -- **By cognitive role** — episodic (events with timestamps), semantic (durable facts), procedural (how-to recipes), working (current context). -- **By representation** — token-level / contextual (markdown / JSON files), vector / latent (embeddings), graph / structured (entity-relationship triples or KG nodes), parametric (fine-tuned weights, out of scope). -- **By management lifecycle** — _construction_ (extract, summarize, embed) → _update_ (`ADD/UPDATE/DELETE/NOOP`, evolution, supersession, commit) → _query_ (semantic, graph, time-window, importance) → _forgetting_ (Ebbinghaus decay, recency penalties, age-weighted pruning, bi-temporal supersession). - -The same dossier separates **general agent-memory frameworks** (MemGPT/Letta, A-MEM, Mem0, Zep/Graphiti, LangMem, OpenAI/Anthropic platform memory, Cognee, MemoryOS, Generative Agents, Reflexion, SAGE, Selfmem) from **coding-harness retrieval** (Cursor's embedding + symbol-graph index, Claude Code's `CLAUDE.md` + auto-memory + Skills, Codex's `AGENTS.md` chain, Aider's tree-sitter repo-map with PageRank, OpenHands's keyword-triggered microagents, Cline's Plan/Act + Memory Bank). The bridge between them is a young cluster of **git-native memory papers** — Codified Context, Git Context Controller (GCC), Lore, agmem, Letta Context Repositories — that take the position the git repository should _be_ the memory database. - -#### Comparison table — agent-memory systems - -| System | Core abstraction | Storage | Best benchmark | License | TS deployability | DAG fit | -| ----------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | ----------------------------------- | -------------------------------------------------------- | -| **MemGPT / Letta** | Tiered "OS" memory blocks; (2026) git-backed Context Repos | Postgres + filesystem; git worktrees per subagent | DMR 93.4% | Apache 2.0 | First-class TS SDK + Docker | Strong — shared blocks + worktree merging | -| **A-MEM** | Zettelkasten notes with auto-linking & evolution | ChromaDB (ref); pluggable | NeurIPS 2025 — beats RAG/MemGPT/Mem0 on 6 models | Reference: non-commercial; TS port: MIT | Python first; community TS port | Medium | -| **Mem0** | Two-phase extract/update with `ADD/UPDATE/DELETE/NOOP` | Vector (Qdrant/pgvector) ± graph (Neo4j) | LoCoMo 66.9%, +26% over OpenAI Memory; 91% lower p95 | Apache 2.0 | First-class `npm i mem0ai` | Weak — namespaces only; no branching | -| **Zep / Graphiti** | Bi-temporal knowledge graph | Neo4j / FalkorDB | LongMemEval +18.5%; DMR 94.8% | Apache 2.0 | Python core; community TS SDK | Medium | -| **LangMem + LangGraph Store** | Semantic / episodic / procedural over `BaseStore` | Postgres / SQLite / in-mem | n/a (framework) | MIT | Python primary; LangGraph.js for TS | **Strong on DAG** — Checkpointer = branching/time-travel | -| **OpenAI Memory** | Curated user-fact text + chat-summary | Proprietary | LoCoMo 52.9% | Closed | Consumer feature | None | -| **Anthropic Memory Tool + Skills** | File-based memory + progressive-disclosure procedural | Developer-owned | n/a | Tool: API; Skills spec: open | First-class via Claude API | Medium | -| **Cursor Rules + Memories** | Markdown rules + per-project memory | Local + Turbopuffer index | +12.5% over grep on internal codebase QA | Closed | n/a (IDE feature) | None | -| **Cline Memory Bank** | Six-file markdown convention | Local files in `memory-bank/` | n/a | MIT | TS extension | Weak | -| **Cognee** | KG + vector hybrid with ontology | Postgres / Neo4j / Chroma | 92.5% internal retrieval | Apache 2.0 | Python core; MIT TS Vercel SDK | Medium | -| **MemoryOS** | OS-tiered short / mid / long memory | Reference impl | LoCoMo F1 +49.11% on GPT-4o-mini | Open (academic) | None | Weak | -| **Generative Agents** | Memory stream + reflection | Reference impl | (qualitative; Smallville sim) | Open | None | Weak | -| **Reflexion** | Episodic reflection buffer | Reference impl | HumanEval pass@1 91% | MIT | Python | n/a | -| **Git Context Controller (GCC)** | COMMIT / BRANCH / MERGE / CONTEXT git-shaped primitives | `.GCC/` directory + git | **>80% SWE-Bench Verified** (+13% over long-context); 48% SWE-Bench Lite; self-replication 40.7% vs 11.7% baseline | open | Python | **High by design** | -| **Lore** | Commit-trailer memory | git only (no infra) | n/a | open | TS CLI | Strong | -| **Letta Context Repositories (Feb 2026)** | Memory as git repo; git worktrees per subagent | git + Letta | n/a (industrial validation) | Apache 2.0 | TS SDK | High | - -Two benchmarks are worth treating with care. **LoCoMo** (Mem0's home turf) shows Mem0 at 66.9% vs OpenAI Memory at 52.9%; Zep's published rebuttal ([Zep blog "Lies, Damn Lies, Statistics"](https://blog.getzep.com/lies-damn-lies-statistics-is-mem0-really-sota-in-agent-memory/)) shows Zep at **63.8–71.2%** on **LongMemEval** (GPT-4o) vs Mem0 at 49.0%, and Mem0 has not published official LongMemEval numbers (`sota-agent-memory.md` §2.3 caveat, §6.1–6.2). Treat single-benchmark dominance claims with skepticism. The honest baseline reading: **hybrid memory beats long-context baselines by ~10–18 pp at 90% lower latency and ~90% token savings** in any well-tuned setup; specific framework deltas are within noise of each other on the public benchmarks the field actually shares. - -### 3.4 Embeddable runtimes (what can ship today) - -The `sota-embeddable-runtimes.md` dossier inventories every git-native, zero-infra-by-default retrieval stack suitable for shipping inside a Node.js / TypeScript developer tool. The taxonomy is split between **vector stores** (sqlite-vec, sqlite-vss, libSQL, PGlite + pgvector, LanceDB, Vectra, Orama, hnswlib-node, USearch, Faiss-node, Qdrant, Weaviate embedded, Chroma, Milvus Lite), **lexical engines** (Tantivy, lunr, MiniSearch, FlexSearch, Tinysearch, Pagefind, SQLite FTS5), and **embedding / reranker inference** (`@huggingface/transformers`, `fastembed-js`, `onnxruntime-node`, `node-llama-cpp`, Ollama). - -#### Comparison table — embeddable runtimes - -| System | Language / runtime | TS bindings | On-disk format | Hybrid (in-process) | License | Git posture for `/.flatbread/index` | -| ------------------------------------------------- | ------------------ | ------------------------------------------------- | -------------------------------------- | -------------------------------------------------- | --------------------------- | ------------------------------------------------- | -| **Orama** | Pure JS | First-class `@orama/orama` | In-mem; JSON / MessagePack persistence | **Yes — native BM25 + vector + RRF** | Apache 2.0 | OK as JSON for tiny; gitignore at scale | -| **SQLite + sqlite-vec + FTS5** | C SQLite extension | `sqlite-vec` npm + `better-sqlite3` | Single `.sqlite` file | Yes (sqlite-vec for vec, FTS5 for lex; RRF in SQL) | Apache 2.0 / public domain | gitignore + deterministic rebuild | -| **PGlite + pgvector** | WASM Postgres | `@electric-sql/pglite` + `extensions: { vector }` | PG data dir (binary) | Yes (HNSW + tsvector) | Apache 2.0 + pgvector | Regenerate from migrations; don't commit data dir | -| **LanceDB** | Rust + Arrow | `@lancedb/lancedb` native addon | Lance columnar fragments | Not lexical-native | Apache 2.0 | gitignore directory | -| **Vectra** | TypeScript | First-class `vectra` | JSON / Protobuf folder | BYO hybrid | MIT | OK small JSON | -| **hnswlib-node** | C++ | N-API addon | Binary `.bin` | None lexical | Apache 2.0 | gitignore `.bin` | -| **USearch** | C++ / SIMD | Official JS bindings | mmap-friendly graph | None | Apache 2.0 | gitignore | -| **Qdrant server** | Rust | `@qdrant/js-client-rest` | Segment files | Hybrid via dense + sparse; RRF in Query API | Apache 2.0 | **Fails zero-infra default** — sidecar required | -| **Tantivy** | Rust | `tantivy` npm WASM / native | Segment dirs | Lexical only | MIT | Regenerate index in CI | -| **MiniSearch / lunr / FlexSearch** | Pure JS | First-class | JSON serialize | Lexical only | MIT / Apache 2.0 | Tiny OK; large rebuild | -| **Pagefind / Stork / Tinysearch** | Rust (CLI / WASM) | Static asset loaders | `.st` / `/pagefind` dirs | Lexical only | MIT / Apache 2.0 | Static-site-friendly build artifacts | -| **`@huggingface/transformers` (transformers.js)** | npm | First-class | ONNX models in HF cache | n/a (inference) | Apache 2.0 (lib); per-model | gitignore cache | -| **`fastembed-js`** | npm | First-class | ONNX cache | n/a (inference) | MIT | gitignore cache | -| **`onnxruntime-node`** | npm | First-class | `.onnx` weights | n/a (inference) | MIT | gitignore weights | - -The dossier's bottom line: for **Flatbread / Proof defaults, stay in TS**: **Orama** _or_ **SQLite + sqlite-vec + FTS5** covers most RAG shapes; treat derived blobs under `.flatbread/index/` as **regenerated outputs** (pair with committed manifests where teams want diffable retrieval inputs); keep models in the user cache or explicit allowed downloads (`sota-embeddable-runtimes.md` Bottom line). The opt-in "heavy" tier is **LanceDB** or **PGlite + pgvector** for larger vectors; **Qdrant** as an external server for hybrid + ColBERT multivectors; **Voyage / Cohere** as cloud APIs when an HTTP call is acceptable. - -Cold-start expectations on a developer laptop for **10k chunks** (`sota-embeddable-runtimes.md` Cold-start table, May 2026 community reporting): `transformers.js` CPU tiny model **~0.5–2 h**; `transformers.js` WebGPU **~5–20 min**; `fastembed-js` ORT CPU small BF16/INT8 **~10–40 min**; `node-llama-cpp` on M-series / CUDA **minutes–hour**; cloud API **minutes** (network + rate limits). Always validate with a 5× mini-run extrapolation on the target machine. - ---- - -## 4. The Gap - -The 2026 SOTA delivers many things. It does not deliver these five things together — and a Flatbread + Proof axis is uniquely shaped to deliver all five. - -### 4.1 Typed relational queries that compose with semantic similarity - -Vector stores (Qdrant, Weaviate, LanceDB, pgvector) treat filters as separate inputs to vector queries: you tell the engine "find me 100 nearest, then drop the ones that don't match this predicate." There is no expression where similarity is a comparator at the same level as `eq` / `gt` / `in`. The closest existing thing is **engine-native hybrid** (Qdrant Query API's `prefetch` composition, Weaviate's `relativeScoreFusion`), but the user is still operating two query languages: the JSON filter and the vector spec. Markdown-aware engines (Obsidian MCPs, vault-search) have hybrid search but no relational schema — `header_path[1] = 'API' AND tags includes 'auth'` isn't a thing because there is no schema. - -Flatbread already has the JSON filter DSL, schema generation from collections, and per-node `EntryNode` JSON shape (`audit-flatbread-retrieval.md` §2.4–2.6). Adding `near` and `text` as comparator ops in `packages/core/src/utils/sift.ts`, alongside `eq` / `gt` / `regex`, makes similarity a peer of any other predicate (`synthesis-novel.md` N4). No incumbent ships _this_: a query language where `where { effort: { eq: "eff-payments-v2" }, blocking: { eq: true }, body: { near: "retry semantics" } }` is one expression that intersects relational, lexical, and semantic candidate sets in a single SQL-like resolver. The PMF audit lists "richer filter input types" as near-term work (`flatbread-flow-pmf-audit.md` §6 type safety, §1 GraphQL-as-product) — search composition is the highest-leverage instance of that work. - -### 4.2 Index-as-source-of-truth that lives in git - -Every embedded vector store the dossier surveys (`sota-embeddable-runtimes.md` §1) treats the index as a binary artifact: SQLite virtual-table pages, Faiss `.bin`, Lance fragments, PG data dirs, ONNX caches. The git-friendliness synthesis is unambiguous: "**Never commit raw vector graphs**" — the index is meant to be regenerated. That advice is correct given today's runtimes but it forecloses an opportunity: a class of teams _want_ the index in git for branchability, blame, code review, and audit. Letta Context Repositories validate the broader thesis ("memory is a git repo"); GCC (`sota-agent-memory.md` §7.2) defines `COMMIT/BRANCH/MERGE/CONTEXT` primitives that map naturally onto a relational substrate; Lore (`sota-agent-memory.md` §7.3) puts decision context into commit trailers. Nobody has shipped **deterministic, line-addressable JSONL where each chunk's vector and BM25 row is a single record sorted by content hash** so that `git diff .flatbread/index/` shows what changed in the agent's mind when markdown was edited (`synthesis-novel.md` N3). - -The substrate is uniquely Flatbread-shaped because chunk IDs are deterministic from `(collection, path, frontmatter, body-slice)`, and Proof DAG nodes already cache by input hash. Combined, the index becomes a _pure function of the markdown plus pinned model_ — exactly the property that lets `git bisect` work over retrieval regressions and `git merge` deduplicate memory across forks (`synthesis-novel.md` N8). - -### 4.3 DAG fan-out as the unit of memory - -Letta Context Repositories (Feb 2026) use `git worktree` per _subagent_ and merge memory back through standard git conflict resolution (`sota-agent-memory.md` §7.5). That's the closest existing pattern, and the unit of memory is still the agent. For a DAG harness — Proof — the natural unit is **the DAG node**: each node has its own memory ref, edges in the DAG correspond to merges, fan-in of N parents creates an N-way merge commit. The agent that executes a fan-in node sees the _merged memory only_, never the in-flight versions. Almost no one is shipping this (`sota-agent-memory.md` §9.3 #2; `synthesis-novel.md` N2). It maps directly onto Proof's existing rank-batched scheduler (`packages/proof/src/dag.ts:425-463` Kahn-topological layering) and `dispatchTask` post-hooks. - -The corollary in Flatbread terms is that the **Effort Graph** schema sketched in [`flatbread-agent-artifact-opportunity.md`](flatbread-agent-artifact-opportunity.md) §6/§8 — `Effort → Plan, Decision, Session, Artifact, Run` — has a 1:1 correspondence with a Proof DAG run's typed structure (`RawTask`, `RankBatch`, `TaskState`). Proof can write its DAG state as Flatbread rows on completion (`synthesis-novel.md` N2 — "DAG-as-Effort"); the next Proof run queries those rows through MCP / GraphQL just like the user's notes. **No competing harness writes DAG state into a typed relational store the user's repo also queries.** - -### 4.4 Bi-temporal correctness with git as the time axis - -Zep's bi-temporal model (`sota-agent-memory.md` §2.4) tracks **valid time** (when the fact was true in the world) and **transaction time** (when the system learned it). It needs Neo4j to do it. With git as the substrate, `valid_at` and `invalid_at` are just commits — no separate timestamp infrastructure required. Combined with churn-aware decay (decay memory by _how many commits have rewritten the linked file_ since the memory was written, not by hours elapsed — `synthesis-novel.md` N10), the agent gets the cleanest synthesis of Zep's KG with a git substrate that any product currently ships. - -The dossier explicitly names this as an unshipped gap (`sota-agent-memory.md` §9.3 #6): "decay memory by churn distance in the graph, not by hours. Nobody is doing this." The combination is only possible when the memory rows are typed, the source of truth is the git tree, and the runner can compute `git log ` cheaply. Flatbread + Proof is the only stack that satisfies all three. - -### 4.5 Tool-portable procedural memory compiled from a typed source - -Cursor Memories, Anthropic Skills, AGENTS.md, Cline Memory Bank, `CLAUDE.md` — every procedural-memory format is hand-maintained today (`sota-agent-memory.md` §2.7–2.9, §4.1–4.6). Cursor's Memories are per-project and closed; switching to Claude Code loses them. The dossier's recommendation (`sota-agent-memory.md` §9.3 #7) is to "treat Skills/AGENTS.md as compiled artifacts of the memory store" — emit them, version them in git, regenerate them from the canonical schema. No incumbent ships a _compiler_ from a typed relational source to all the harness-specific procedural formats. Flatbread + Proof are uniquely positioned: Flatbread owns the schema; Proof owns the writer; both are TypeScript-native and can run as a Proof DAG node on commit (`synthesis-novel.md` N12). - -The competitive observation is that **compiling to harness formats is composition, not competition.** Flatbread becomes the upstream source of truth; Cursor / Claude Code / Codex stay as downstream views. A user who pivots between IDEs keeps a consistent "agent mind" because Flatbread is its source. - -### 4.6 What this gap implies, in one sentence - -The thesis of this report is that **the Flatbread + Proof axis is the only stack where (a) the user's repo is already a graph, (b) the agent's run is already a graph, (c) a single TypeScript-native, license-clean retrieval runtime can ship as default, and (d) the index can live in git as a deterministic, reviewable JSONL artifact when teams want it.** Each of the other gap points (typed-relational + similarity composition, DAG-as-memory unit, bi-temporal git-as-time, compiled procedural memory) follows from those four facts. - ---- - -## 5. Opportunity Catalog - -This catalog merges eleven Proof-track opportunities (`synthesis-proof.md` O1–O11), twelve Flatbread-track opportunities (`synthesis-flatbread.md` F1–F12), and twelve intersection novel bets (`synthesis-novel.md` N1–N12). Each row is a hypothesis-sized item; §5.1–5.3 unpack prose, trade-offs, and tests. SOTA roots point to Mem0/Zep/Letta-class memory, hybrid BM25+dense+RRF stacks, PathRAG/GraphRAG motifs, Obsidian MCP patterns, and embeddable TS runtimes cited in the upstream dossiers. - -| ID | Title | Track | SOTA Roots | Effort | Risk | Outcome Hypothesis | PMF Tension | -| --- | ---------------------------------------------- | ---------- | --------------------------------------------------------------------------------------- | -------------------- | -------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| O1 | Episodic disk store between runs | Proof | Mem0 extract/update; Letta archival; SQLite+FTS5+sqlite-vec shortlist | Medium | Medium | Second-run tokens down; fewer rediscovery loops; recall gated on embedder quality | Aligns if opt-in path; stretches if on by default without privacy story | -| O2 | Central Flatbread repo retrieval for subagents | Proof | Cursor hybrid index + Aider repo map; LightRAG incremental; contextual retrieval recipe | Invasive | High | Tool-call tokens down; repo task quality up; cold-start/cache policy decides UX | Stretches coupling Proof↔Flatbread; aligns if behind RepoRetriever interface | -| O3 | Rerank parent output vs 2k truncation | Proof | bge-reranker-v2-m3; Anthropic contextual chunk semantics | Small–Med | Low–Med | Child quality up on long parents; latency per assembly | Aligns; pure quality fix on existing seam | -| O4 | DAG as queryable KG + semantic near edges | Proof | GraphRAG local/global; PathRAG paths; Generative Agents ranking | Med–Invasive | Med | Wide-rank dedup; better reviewer context; noisy soft edges | Stretches graph UX surfacing; needs strict rerank gates | -| O5 | Findings sidecars + oracle rows as memory | Proof | MIRIAD structured QA; Reflexion lessons | Small | Low | Regression recall up; structured headings beat raw streams | Aligns; schema convention already load-bearing | -| O6 | Contextual prefix + optional ColBERT lane | Proof | Anthropic contextual retrieval; fast-plaid-web edge ColBERT | Medium | Med | Extra retrieval failure reduction vs prefixless stack | Stretches index-time LLM cost; keep Tier-2 profile | -| O7 | RAPTOR-lite over STREAM_CAP parents | Proof | RAPTOR tree; heading-bounded variant | Medium | Med | Long-parent rationale preserved; shallow tree to limit drift | Aligns as optional; watch summary hallucination guardrails | -| O8 | Rank-N retrieve non-parent prior tasks | Proof | PathRAG pruning; soft DAG consult edges | Invasive | High | Cross-cutting merge quality; budget + determinism hazards | Stretches prompt determinism story until runtime pinned | -| O9 | A-MEM-style evolve linked episodes | Proof | A-MEM evolution; Zep supersession | Med–Invasive | High–Med | Long-horizon quality; rewrite corruption class | Violates if unscoped mutations; mitigate bi-temporal fields | -| O10 | Compile AGENTS.md / Skills from store | Proof | Skills spec; AGENTS.md chain; consolidator workers | Medium | Med | Procedural portability; wrong rule propagation | Stretches trust; ship propose-then-merge gate | -| O11 | TS embedder+reranker+store runtime | Proof | Qwen3-emb + ORT; Tier-1 dense-sparse dossier | Medium | Med | Enables O1–O4 without Python; model governance | Aligns when defaults stay Apache-2; cold-start honesty | -| F1 | mdast chunking policy in transformer | Flatbread | Structure-aware chunking default; vault MCP grain | Medium | Med | Stable chunk IDs; fewer broken-code splits; unlocks all indexes | Aligns; content shaping not CMS | -| F2 | Body symbols as GraphQL fields | Flatbread | Wikilink graph as gold labels; header_path metadata | Medium | Med | Relational queries over links/headings before vectors | Stretches if arrays bloat memory; normalize targets | -| F3 | Optional vectors + relatedTo | Flatbread | Qwen3 class embedders; sqlite-vec/Orama shortlist | Med–Large | Med | Semantic related + agent recall; model ops burden | Aligns as plugin; PMF warns against mandatory vector core | -| F4 | Hybrid filter ∧ BM25 ∧ dense + RRF | Flatbread | Engine RRF k=60; pgvector+tsvector pattern | Large | Med | Fixes paraphrase misses under relational guards | Stretches roadmap order; flag experimental index | -| F5 | Second-stage reranker hook | Flatbread | Cross-encoder gains after fusion | Medium | Med | Top-k precision for humans + packs | Keep default off for ten-minute starter demos | -| F6 | Graph walks refs ∪ wikilinks | Flatbread | PathRAG; vault BFS tools; LightRAG dual-level | Medium | Med | Multi-hop inspection vs vector soup | Aligns file-derived regenerable posture | -| F7 | RAPTOR-lite summaries collection | Flatbread | Heading-tree summaries; optional communities | Large | Med | Global questions without leaf spam | Stretches if sold as CMS; derived artifacts only | -| F8 | Contextual prefix indexer profile | Flatbread | Anthropic contextual BM25/embed recipe | Med–Large | Med | Ambiguous chunk recall | Tier-2; costs at scale | -| F9 | deterministic manifests + sidecars | Flatbread | Gitignore binaries; JSONL manifests per dossier | Medium | Low | CI catches drift; rebuild discipline | Aligns exports/portability narrative | -| F10 | MCP semantic_search + graph tools | Flatbread | Effort Graph §9; vault MCP precedent | Med–Large | Med | Agents avoid raw GraphQL; shared memory ABI | Strong align with audit MCP pivot | -| F11 | Filter DSL OR/findMany/sortBy/regex | Flatbread | Audit completeness gaps | Medium | Med | Agent queries smaller; safer regex story | Aligns near-term PMF foundations | -| F12 | ColBERT/BGE-M3 premium lane | Flatbread | Late-interaction dossier; multivector cost | Invasive | High | API-doc needle gains | Violates if rushed default; enterprise profile only | -| N1 | Declared edges + residue LLM extract | Novel–Both | GraphRAG cost math; PathRAG over existing graph | Ambitious | Med | Slash GraphRAG index $; human promotes suggestions | Stretches write UX for promotions | -| N2 | DAG runs author Effort Graph rows | Novel–Both | Letta context repos; GCC primitives; handoff savings | Ambitious | Med–High | Cross-run decisions reusable; trust boundary on writes | Medium-high if scope creeps beyond effort dir | -| N3 | Line-diffable JSONL index | Novel–Both | Embeddable git posture critique | Controlled | Low | Reviewable retrieval diffs; optional commit | Aligns export/audit story | -| N4 | filter ∧ near() ∧ text() composition | Novel–Both | Hybrid engines lack composed DSL | Ambitious | Med | Single query merges relational + ANN + FTS | Depends on index sidecar maturity | -| N5 | Auto-link + bounded summary rewrite | Novel–Both | A-MEM evolution on typed graph | Ambitious | High | Sharper Zettel graph; controlled field scope | High if touching author body—use `_proof_*` only | -| N6 | Default contextual at write | Novel–Both | Anthropic contextual retrieval | Ambitious | Med | Large recall jump; offline fallbacks required | Medium default-on pipeline vs PMF simplicity | -| N7 | Unified MCP for user + agent | Novel–Both | MCP thesis; memory-as-tool | Controlled–Ambitious | Med | Cross-harness continuity | Aligns recommended surfaces | -| N8 | Trailer + content-address federation | Novel–Both | Lore trailers; git merge semantics | Moonshot | High | Distributed agent memory sans hub | Low–med; avoid hosted hub | -| N9 | Reverse retrieval + provenance rank | Novel–Both | MIRIAD; Aider PageRank motif | Controlled\* | Med | Recall + trust ranking once graph dense | Aligns read-side signals | -| N10 | Churn decay not wall clock | Novel–Both | Agent memory §9.3 gap callout | Controlled | Med | Current-truth precision on hectic repos | Pure read-side—aligns | -| N11 | Self-RAG/CRAG/PathRAG as presets | Novel–Both | Adaptive RAG family = DAG | Ambitious | Med | Research-grade reproducibility | Proof-only feature surface | -| N12 | Compile harness facing artifacts | Novel–Both | Skills/AGENTS.md compiler thesis | Ambitious | Med | Tool switching without manual manifests | Vendor perception risk—frame upstream | - -### 5.1 Proof Track Opportunities - -#### O1 — Episodic memory store - -Disk-backed episodic rows (sqlite + optional jsonl shadow) written at `dispatchTask` and recalled before `agent.send` give Proof cross-run continuity the audit marks missing **Pros:** Single-file storage; additive blocks; Mem0-class token savings on recalled context **Cons:** Embedder cold start; privacy of transcripts; recall quality hinges on embeddings **Hypothesis:** Turning on read/write memory cuts second-run rediscovery tokens materially and trims convergence iterations when failed-oracle episodes replay. - -#### O2 — Flatbread-centralized repo retrieval - -Build or reuse a Flatbread hybrid index once per run; inject ranked repo chunks into prompt assembly and optionally expose the same endpoint to subagent tools **Pros:** Matches harness reports on semantic+grep gains; deduplicates sibling exploration **Cons:** Index build latency; schema coupling; bad retrieval adds tokens **Hypothesis:** With BM25+dense+RRF and cache keys on commit SHA, repo-grounded ranks beat ad-hoc grep rates on >500-file workspaces. - -#### O3 — Parent-output reranking - -Replace fixed `SECTION_DROP_PRIORITY` packing with chunkwise scoring against the child prompt using a cross-encoder or dense fallback **Pros:** Localized change; addresses the 2k cap bottleneck immediately **Cons:** Per-child latency; needs diversification when parents repeat **Hypothesis:** Reranked packs lift child output and convergence pass rates on parents exceeding the cap without net token inflation. - -#### O4 — DAG knowledge graph - -Materialize tasks as nodes with depends_on, rank, and embedding links so non-ancestor tasks can be retrieved when relevant **Pros:** Directly targets duplicated sibling work and reviewer blind spots **Cons:** Depends on O11/O1; soft semantic edges need rerank budgets **Hypothesis:** Graph-context blocks reduce redundant tool calls in wide ranks and shorten converge iterations on cross-cutting files. - -#### O5 — Sidecars and oracles as canonical episodes - -Promote `findings_sidecar` sections and oracle `## Pass:false` rows into the episodic store, preferring structured fields over truncated buffers **Pros:** High-signal distilled records; oracle failures are objective anchors **Cons:** Requires heading discipline; unstructured tasks need fallback extraction **Hypothesis:** Recall precision jumps on regression and rerun classes versus embedding raw `resultText` slices. - -#### O6 — Contextual + late-interaction assembly - -Add cached contextual prefixes for ancestor chunks and optional PLAID ColBERT for small corpora **Pros:** Stacks Anthropic-class failure reductions where prefixes apply **Cons:** Index-time LLM spend; ColBERT storage for huge repos **Hypothesis:** Layered on O3/O1 yields incremental retrieval failure drops on structured parent outputs. - -#### O7 — RAPTOR over long parents - -When streams exceed `STREAM_CAP`, build a shallow heading-aligned summary tree from `full-output` artifacts for retrieval into children **Pros:** Preserves rationale otherwise lost to scrolling caps **Cons:** Extra summarization cost; must pair verbatim leaves **Hypothesis:** Reviewers and downstream merges receive stable reasoning traces, reducing contradictory reruns. - -#### O8 — Cross-rank soft retrieval - -Allow budgeted pulls from non-parent earlier tasks via embedding similarity with logged consult edges **Pros:** Addresses merge tasks missing rationale outside immediate parents **Cons:** Nondeterminism; prompt bloat if budgets slip **Hypothesis:** Cross-cutting merges improve when soft pulls are rerank-gated and embedder versions pinned. - -#### O9 — Evolving linked memories - -A-MEM-style link proposals and superseding rewrites with bi-temporal metadata **Pros:** Notes improve with iterations instead of append-only noise **Cons:** Token-heavy rewrite passes; license caution on reference A-MEM code **Hypothesis:** Later-run quality gains appear only after integrity and rewrite gates are trustworthy. - -#### O10 — Procedural artifact compiler - -Emit `AGENTS.md` / Skills / rules files from consolidated episodes with human approval defaults **Pros:** Procedural memory rides across Cursor/Claude/Codex **Cons:** Bad consolidation poisons future runs **Hypothesis:** Approved compilations lower repeat onboarding tokens on stable repos. - -#### O11 — Unified retrieval runtime - -One module picks Apache-2 embedder, ONNX reranker, and sqlite vector/FTS backing for all memory features **Pros:** Single dependency story; license-clean defaults **Cons:** Download sizes; cold-start honesty **Hypothesis:** Without this spine, higher opportunities stall; with it, features compose behind flags. - -### 5.2 Flatbread Track Opportunities - -#### F1 — AST-aware chunking - -Emit deterministic chunks from mdast with heading paths, fence-safe boundaries, and stable chunk ids **Pros:** Unlocks semantic, lexical, and citation surfaces; aligns with vault MCP practice **Cons:** Policy changes invalidate embeddings **Hypothesis:** Structure-aware units cut irrelevant snippets versus whole-file `regex` filters. - -#### F2 — Symbolic body fields - -Surface headings, wikilinks, code fences, and callouts as typed arrays for `sift` **Pros:** Graph-like queries without vectors **Cons:** Large nodes; needs canonical link targets **Hypothesis:** Most Obsidian-style questions answer with relations before embeddings ship. - -#### F3 — Semantic index + relatedTo - -Optional chunk embeddings with `relatedTo`/`semanticSearch` joining back to EntryNode ids **Pros:** Semantic related posts and agent recall **Cons:** Model downloads and staleness **Hypothesis:** Tag-sparse sites gain relevance; keep optional to respect PMF warning on mandatory vectors. - -#### F4 — Hybrid retrieval stage - -Narrow relational ids, run BM25 and dense lanes, fuse with RRF, then slice **Pros:** Anthropic-class hybrid gains inside Flatbread **Cons:** Resolver complexity; explainability work **Hypothesis:** Users stop missing answers that differ lexically from frontmatter. - -#### F5 — Reranker middleware - -Pluggable cross-encoder after fusion for top-N candidates **Pros:** Largest precision jump after hybrid **Cons:** Latency **Hypothesis:** UI cards and agent packs show fewer false positives at ranks 1–3. - -#### F6 — Graph expansion resolver - -k-hop walks over refs, extracted wikilinks, and heading containment with PathRAG-style pruning **Pros:** Coherent multi-hop evidence paths **Cons:** Explosion without pruning **Hypothesis:** Effort-level questions cite inspectable paths, improving trust. - -#### F7 — Hierarchical summaries - -RAPTOR-lite rollups over heading trees or ref-clusters as derived nodes **Pros:** Global asks without scanning every leaf **Cons:** LLM cost; label summaries non-authoritative **Hypothesis:** Agents get zoom-level context for long collections. - -#### F8 — Contextual indexer profile - -Indexer adds short locators before embed/BM25 per Anthropic recipe **Pros:** Big recall win on ambiguous sections **Cons:** Token spend at index **Hypothesis:** Pairing F8 with F5 matches enterprise RAG quality without abandoning git-first artifacts. - -#### F9 — Index artifacts + verify CLI - -chunks/edges jsonl plus derived sqlite/orama binaries; **proposed (not shipped):** a future `flatbread index verify` would hash manifests against sources for CI — today the `flatbread` CLI only exposes `start`, `init`, and `codegen` ([`packages/flatbread/src/cli/index.ts`](packages/flatbread/src/cli/index.ts)). **Pros:** CI drift detection; clone size control **Hypothesis:** Support load shifts from mystique to actionable rebuild commands. - -#### F10 — MCP toolpack - -`semantic_search`, `related_to`, `expand_neighborhood`, `summarize_collection` calling the same resolvers as GraphQL **Pros:** Solves GraphQL-as-only-interface pain; agent-native interop **Cons:** Versioning second surface **Hypothesis:** Proof and IDE agents adopt memory faster with tools than ad-hoc GraphQL strings. - -#### F11 — Filter completeness - -`$or`, `findMany+filter`, nested `sortBy`, safe server-side regex coercion **Pros:** Smaller agent queries; fewer footguns **Cons:** ReDoS vigilance **Hypothesis:** Drops abandoned evals blocked by expressiveness gaps today. - -#### F12 — Late-interaction tier - -BGE-M3 multivector or edge ColBERT for terminology-heavy corpora **Pros:** Needle-in-haystack gains **Cons:** 30–100× storage **Hypothesis:** Wins only on API-like corpora; default remains single-vector. - -### 5.3 Novel + Industry-Shifting Bets - -#### N1 — GraphRAG without extraction tax (**AMBITIOUS**) - -Use declared refs and wikilinks as gold graph; LLM schema extraction only on link-empty prose chunks with promotion workflow **Pros:** Cuts GraphRAG index spend; quality from typed edges **Cons:** Entity drift; promotion UX absent today **Hypothesis:** Multi-hop recall matches expensive GraphRAG on linked vaults at a fraction of index cost. - -#### N2 — DAG-as-Effort authoring (**AMBITIOUS**) - -Proof writes Effort/Plan/Decision/Session/Artifact/Run markdown rows consumable next run via Flatbread queries **Pros:** Git-d durable memory; maps harness types 1:1 **Cons:** Write trust boundary; schema evolution **Hypothesis:** Repeat runs shave wall time when prior decisions inject automatically. - -#### N3 — Deterministic JSONL memory index (**CONTROLLED**) - -Vectors and sparse stats as sorted jsonl keyed by content hashes for optional commit **Pros:** `git diff` retrieval behavior; bisect regressions **Cons:** Repo size if committed naïvely **Hypothesis:** Teams that opt-in get review comments on embedding deltas within weeks. - -#### N4 — Composed near/text filters (**AMBITIOUS**) - -Extend `sift` with vector and FTS comparators intersecting ordinary predicates **Pros:** Expressive typed queries no vector DB exposes **Cons:** Tight coupling to sidecar availability **Hypothesis:** Combined filters beat two-phase filter-then-search scripts on effort-scoped questions. - -#### N5 — Typed auto-link evolution (**AMBITIOUS**) - -Hybrid declared-ref and embedding links update bounded `_proof_summary` fields with Zep-like validity **Cons:** Cost; user consent on generated fields **Hypothesis:** Precision@5 on institutional memory improves after dozens of linked runs. - -#### N6 — Contextual-by-default writes (**AMBITIOUS**) - -Generate prefixes on Flatbread chunks and Proof-authored rows before embedding **Pros:** Anthropic-scale failure reduction baked in **Cons:** Violates zero-LLM-index defaults unless local fallback **Hypothesis:** Pass@k on decision retrieval approaches hosted RAG baselines in-repo. - -#### N7 — Memory-as-MCP (**CONTROLLED / strategically AMBITIOUS**) - -Six-tool MCP surface doubles as user search and agent memory API **Pros:** One adapter story across harnesses **Cons:** Surface creep if tools proliferate **Hypothesis:** Third-party harnesses standardize on the Flatbread MCP bundle within a year if shipped lean. - -#### N8 — Trailer-based federation (**MOONSHOT**) - -Lore-style trailers plus content-addressed rows merge memory across forks **Pros:** No central memory SaaS; git-native distribution **Cons:** Integrity skew between trailers and files **Hypothesis:** OSS ecosystems measurably improve agent answers after pulling upstream memory trailers. - -#### N9 — Reverse queries + provenance rank (**CONTROLLED composition**) - -Precompute doc-specific queries and boost nodes cited across sessions **Pros:** MIRIAD + PageRank-style trust without Cursor hosting **Cons:** Storage doubles for query embeddings **Hypothesis:** Recall@10 and precision@5 climb once the Effort graph exceeds ~100 rows. - -#### N10 — Churn decay (**CONTROLLED**) - -Rank decay uses commits touching linked files, not wall clock **Pros:** Coding-native salience **Cons:** Cosmetic churn noise **Hypothesis:** “Current truth” queries beat hourly half-life baselines on active repos. - -#### N11 — Adaptive RAG presets (**AMBITIOUS**) - -Package Self-RAG / CRAG / PathRAG / ToC as Proof DAG recipe expansions **Pros:** Research reproducibility; composable evals **Cons:** API design between declarative and code **Hypothesis:** Paper ablations ship as hundred-line DAG specs instead of one-off forks. - -#### N12 — Harness artifact compiler (**AMBITIOUS**) - -Project Effort graph to Skills, AGENTS.md, `.cursor/rules` deterministically **Pros:** Single source of truth across IDEs **Cons:** Round-trip complexity later **Hypothesis:** TS repos start checking in compiler output once the graph is credible. - -## 6. Three Posture Comparisons - -### 6.A Conservative Indexer Add-on - -**Target user:** Teams that want better “find related doc” and safer body queries without reframing Flatbread as a memory product. **Surfaces shipped:** `transformer-markdown` emits chunks + symbolic fields (F1/F2); optional lexical index (MiniSearch/SQLite FTS) without mandatory vectors; GraphQL-only or thin codegen; no MCP requirement on day one. **Strengths:** Smallest displacement of today’s GraphQL/transformer stack; respects PMF “indexing later”; avoids Proof coupling. **Risks:** Stops short of agent memory parity; hybrid + rerank lag leaves quality on the table; wide-rank Proof pain persists. - -### 6.B Effort-Graph + Hybrid Retrieval (recommended) - -**Target user:** Maintainer-led repos running Proof DAGs and sites that already model efforts in markdown. **Surfaces:** F1–F4 + F9–F11 landed alongside Near Term PMF items; `@flatbread/mcp` read tools (F10); Proof ships O11 + O3 + opt-in O1/O2 writing into the same index contract; Effort graph preset matches `flatbread-agent-artifact-opportunity.md` posture C spine. **Strengths:** Fuses typed relational filters with BM25 + dense + RRF + rerank; MCP breaks GraphQL-centrism; Proof adopts shared runtime instead of bespoke truncation hacks. **Risks:** Operational complexity (cache, models); roadmap tension until validation and watch land; needs disciplined feature flags. - -### 6.C Industry-Shifting Memory Substrate - -**Target user:** Organizations betting git is the agent database (`synthesis-novel.md` Industry Bet I). **Surfaces:** N2/N3/N7/N8/N12 compositions—DAG-authored rows, diffable jsonl indexes, trailer federation, compiled harness artifacts; contextual-by-default (N6) and filter composition (N4); adaptive-RAG presets (N11). **Strengths:** Category-defensible if execution matches; cross-tool continuity; auditability via git. **Risks:** Collides with PMF “not yet” list without staged gates; write trust, model governance, and support burden spike; premature moonshots starve foundations. - -**Recommendation:** Converge on **Posture B**. The syntheses agree v1 should pair **license-clean hybrid retrieval + rerank** with **chunk/index discipline** and **MCP**, sequencing Proof’s minimum credible pack (runtime + rerank + episodic read default-off) after Flatbread’s structural emitters so both stacks share one embedding story instead of diverging forks. - -## 7. Ideal Product State - -**North Star:** A single typed substrate—markdown rows + Proof DAG artifacts—where humans query relations and similarity in one expression, agents pull the same answers through MCP or generated TypeScript, and deterministic indexes can be regenerated or even reviewed in git because chunk ids and model pins are explicit. - -**Data model:** Collections follow the Effort graph sketch (Effort → Plan, Decision, Session, Artifact, Run) plus the user’s content collections; each `EntryNode` gains optional `chunks[]` children with stable ids, `headingPath`, outbound link arrays, and join keys back to parents. Proof run records land in the same schema via append-only writers, never mutating author body text except namespaced `_proof_*` fields agreed in policy. - -**Query surfaces:** GraphQL remains the introspectable contract for apps; MCP exposes tool-shaped facades over the identical resolver stack; codegen grows typed accessors (document nodes + thin SDK) so agents rarely hand-author GraphQL strings. - -**Index format:** Source markdown stays canonical. **Tier A:** committed `chunks.jsonl` / `edges.jsonl` manifests for CI and small repos. **Tier B (proposed default at scale):** derived `sqlite` with FTS5 + `sqlite-vec` (or Orama snapshot) under `.flatbread/index/`, rebuilt by a **`flatbread index build` command that does not exist yet** — the shipped CLI is still `start` / `init` / `codegen` only ([`packages/flatbread/src/cli/index.ts`](packages/flatbread/src/cli/index.ts)); implement build/verify as part of `@flatbread/index` + CLI extension work, then record manifest hashes for CI. Teams may gitignore Tier B binaries or commit them depending on policy. Optional **Tier C:** team policy commits quantized vectors per N3 when audit demands byte-level review. - -**Retrieval pipeline (prose):** Resolvers first **narrow** by relational `filter` (tenant, effort, status, link predicates), push candidate ids into parallel **lexical** and **dense ANN** lanes capped at top‑100 each, **fuse** with RRF (k=60), optionally **rerank** top‑50 with `bge-reranker-v2-m3`, then **expand** along declared refs and extracted wikilinks using PathRAG-style pruning + hop/token budgets before packaging citations. Contextual prefixes and late-interaction lanes are indexer profiles, not separate products. - -**Write surfaces:** Proof `dispatchTask` and convergence hooks append Effort-shaped markdown, episodic sqlite/jsonl, and findings sidecars; consolidators may propose procedural files under human merge control. Flatbread validation runs before rows enter the canonical tree. - -**Package layout:** Existing `packages/core`, `transformer-markdown`, `codegen`, `source-filesystem` stay authoritative; add **`@flatbread/index`** (chunk manifests + build/verify), **`@flatbread/embed`** (model loaders), **`@flatbread/mcp`** (stdio server), **`@flatbread/memory`** (retrieval composition utilities shared with Proof). Proof consumes them via `packages/proof/src/retrieval/*` instead of duplicating hybrid logic. - -```mermaid -flowchart LR - subgraph sources["Sources"] - MD["Markdown / YAML in git"] - PR["Proof run outputs"] - end - subgraph transform["Transform + schema"] - TR["Transformer + Effort writers"] - CH["Chunks + symbols + refs graph"] - end - subgraph index["Index tier"] - MX["Manifests JSONL"] - DB["SQLite FTS5 + vec / Orama snapshot"] - end - subgraph query["Query adapters"] - GQ["GraphQL resolvers"] - MC["MCP tools"] - TS["Generated TS accessors"] - end - subgraph agents["Consumers"] - AG["IDE agents / Proof DAG / apps"] - end - MD --> TR - PR --> TR - TR --> CH - CH --> MX - CH --> DB - MX --> GQ - DB --> GQ - GQ --> MC - GQ --> TS - MC --> AG - TS --> AG -``` - -## 8. Phased Path - -### V0 — Foundation - -- Land normalized IDs, relation validation, and stricter Flatbread config typing called out in the PMF audit so chunk ids, refs, and wikilink targets resolve to one canonical keyspace. -- Ship structure-aware chunk + symbol emission behind a transformer flag (F1/F2) with golden tests across GFM/MDX edges. -- **Proposed:** add `flatbread index verify` (not in the CLI yet) to hash manifests against source files even before vectors ship — same `@flatbread/index` / CLI milestone as `flatbread index build`. -- Proof ships **O11 stub + O3 behind a flag** using the same embed/rank interface but defaulting to legacy truncation until benchmarks pass. -- Document license-clean default models (Qwen3-Embedding + ONNX reranker) and download-on-first-use policy. - -_Depends:_ none beyond current monorepo baselines; blocks every later retrieval milestone. - -### V1 — Minimum credible - -- Expose hybrid retrieval (F4) + optional sidecar store (F3) with relational-narrow-first semantics; add reranker hook (F5) default-off for starter flows. -- Release **`@flatbread/mcp`** read tools wrapping semantic + related + neighborhood operations (F10) backed by the same resolver code as GraphQL. -- Proof enables **O1 read/write** modes, **O5** sidecar ingestion, and **O2** “reuse index” path scoped to a repo cache keyed by commit metadata; ship A/B toggles for reranked upstream context. -- Generated TypeScript accessors cover the new operations list so agents skip raw GraphQL composition for common tasks. -- Watch mode milestone (per audit) reloads content + schema + MCP server state without full manual restart for demos. - -_Depends:_ V0 ID validation and chunk contracts; without them graph expansion and hybrid filters silently miss edges. - -### V2 — Industry-shifting - -- Optional committed / jsonl vector stores (N3) with team policy for audit-grade diffs; churn-aware ranking (N10) and provenance boosts (N9) once Effort graph row counts justify it. -- DAG-as-Effort writers (N2) with scoped directories, bi-temporal metadata, and trailer tooling (N8) piloted on OSS maintainers; contextual indexer profile (F8/N6) guarded by cost caps. -- Graph-aware Proof retrieval (O4/O8) and adaptive presets (N11) graduate from flags to supported recipes; procedural compilers (O10/N12) remain propose→approve. -- Premium late-interaction tier (F12 / O6 ColBERT lane) for selected API-heavy corpora. - -_Depends:_ stable V1 hybrid+MCP+Proof memory path; premature V2 without validation recreates the PMF audit’s “complex pipelines before exports/watch” failure mode. - -## 9. Validation Experiments - -1. **Hybrid retrieval lift on real Flatbread corpora** — **Hypothesis:** BM25 + dense + RRF beats frontmatter-only filters on paraphrased queries. **Setup:** Freeze two collections (docs + decisions), build sqlite+FTS5+vec index with Apache-2 embedder; craft 30 held-out natural-language queries with labeled chunk ids. **Measurement:** Recall@k, MRR, plus latency p95 on laptop CPU. **Success:** ≥20% relative Recall@10 gain vs baseline `all*` + `regex` proxy without regressing relational filters. - -2. **Proof parent rerank vs legacy truncation** — **Hypothesis:** O3 reduces incorrect or contradictory child outputs when parents exceed `UPSTREAM_SNIPPET_CAP`. **Setup:** Sample DAGs with long parent artifacts; A/B `legacy` vs `cross-encoder` packing with fixed token budget. **Measurement:** LLM-judge rubric + oracle pass rate + convergence iteration count. **Success:** Non-decreasing `## Pass:true` rate with ≥½-point average judge gain or −0.25 mean iterations. - -3. **MCP vs GraphQL agent throughput** — **Hypothesis:** F10 lowers agent integration time and token overhead for multi-hop questions (tasks complete faster with fewer tool round trips). **Setup:** Give Codex/Cursor harness identical scenarios; one arm uses hand-written GraphQL, other MCP tools. **Measurement:** Wall clock, tokens to first correct citation, human time to author tooling. **Success:** MCP arm wins median wall clock by ≥15% or halves authoring minutes without hurting citation accuracy. - -4. **Effort graph + churn decay ranking** — **Hypothesis:** N10 ordering beats naive recency for “current truth” prompts after ref graph exists. **Setup:** Simulate git histories rewriting a linked module; inject synthetic Decision rows referencing it. **Measurement:** Precision@5 for “what is true now” queries vs time-decay baseline. **Success:** ≥+8 pp precision improvement once ≥10 rewrite commits applied (directional per novel bet claim). - -5. **Index reproducibility drill** — **Hypothesis:** F9/N3 manifests catch silent drift between machines. **Setup:** Two laptops rebuild the same commit with pinned models; compare manifests + sqlite fingerprints. **Measurement:** Byte/row diff rate before/after introducing a deliberate paragraph edit. **Success:** Zero unexplained diffs when inputs match; CI fails loudly on mismatch. - -6. **Scoped Proof writes trust audit** — **Hypothesis:** N2/O10 can land without violating PMF “narrow writes” if confined to `.proof/efforts` + proposed procedural files. **Setup:** Red-team prompts attempting path escape, overwrite of author body, and unscoped deletes. **Measurement:** Integrity tester results + operator survey on comfort. **Success:** All attacks blocked by validation; reviewers mark workflow acceptable with opt-in flags. - -## 10. Tensions With The PMF Audit - -Cross-check against [What Not To Build Yet](flatbread-flow-pmf-audit.md) and the tensions table in [`flatbread-agent-artifact-opportunity.md`](flatbread-agent-artifact-opportunity.md) §11—here scoped to the **ideal product state** in §7. - -| Audit constraint | Relationship to ideal product state (§7) | -| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Do not build hosted CMS, dashboard, or editing UI yet | The ideal state stays CLI/MCP/codegen-first; authoring remains markdown-in-git; any “summary node” is a derived artifact, not a hosted editor. | -| Do not compete with full databases on transactions, auth, permissions, high-scale writes | Ideal writes stay append-oriented Effort deposits and Proof sidecars; no global mutation API; hybrid stores are derived indexes, not OLTP backends. | -| Do not over-invest in many source plugins before local filesystem relational workflow is excellent | Ideal path deepens filesystem + Proof outputs first; `@flatbread/source-git-trailers` / SaaS ingest wait until V1 integrity + watch are proven. | -| Do not keep GraphQL as the only story | Explicitly satisfied: MCP + generated TS are first-class adapters feeding the same resolver core as GraphQL. | -| Do not add complex migration systems before schemas, IDs, validation, exports, watch | Ideal sequencing puts V0 ID/validation + manifest export (JSONL) before hybrid/MCP launch; migration tooling only after `flatbread export`/watch are trustworthy. | -| Avoid database replacement framing until write path exists | Positioning remains “relational content + derived search indexes”; sqlite/Orama are cache layers with rebuild commands, not a marketed Postgres killer. | - -## 11. What Not To Build Yet - -Mirrors [`flatbread-agent-artifact-opportunity.md`](flatbread-agent-artifact-opportunity.md) §13 for the retrieval + memory arc: - -- Hosted editing UI or CMS for memory artifacts. -- Mandatory vector index inside core—keep embeddings an optional `@flatbread/embed` / index profile. -- Arbitrary update/delete mutation API on arbitrary collection fields. -- New source plugins for proprietary SaaS artifact stores before filesystem Effort Graph + validation are excellent. -- Replacing Claude Code, Cursor, or Codex—ship **composition** (`AGENTS.md` / Skills projection) instead. - -## 12. Bottom Line - -Flatbread’s moat is not “another vector database”—it is **typed markdown + refs + agent DAG shape** feeding one hybrid retrieval stack that humans and agents query the same way. Posture **B** sequences the PMF foundations (IDs, validation, chunk honesty, watch) ahead of optional vectors, pairs Proof’s rerank-first memory fixes with Flatbread’s MCP escape hatch, and defers moonshots like trailer federation until git-native Effort rows prove trustworthy. **First experiment to run:** execute §9 Experiment **1** (hybrid retrieval lift on a real collection) with pinned Qwen3-Embedding + sqlite+FTS5+RRF to quantify precision gains before wiring Proof’s O2 repo context to the same index builder. - -## 13. References - -**In-repo strategy docs** - -- [flatbread-agent-artifact-opportunity.md](flatbread-agent-artifact-opportunity.md) -- [flatbread-flow-pmf-audit.md](flatbread-flow-pmf-audit.md) - -**External URLs appearing in upstream dossiers (deduped, A–Z)** - -- [http://arxiv.org/abs/2312.06648v3](http://arxiv.org/abs/2312.06648v3) -- [https://aclanthology.org/2022.sigir-short.93/](https://aclanthology.org/2022.sigir-short.93/) -- [https://aclanthology.org/2025.coling-main.295/](https://aclanthology.org/2025.coling-main.295/) -- [https://aclanthology.org/2025.emnlp-main.1318/](https://aclanthology.org/2025.emnlp-main.1318/) -- [https://anthropic.com/engineering/contextual-retrieval](https://anthropic.com/engineering/contextual-retrieval) -- [https://arxiv.org/abs/2112.01488v3](https://arxiv.org/abs/2112.01488v3) -- [https://arxiv.org/abs/2212.10496](https://arxiv.org/abs/2212.10496) -- [https://arxiv.org/abs/2310.08560](https://arxiv.org/abs/2310.08560) -- [https://arxiv.org/abs/2310.11511](https://arxiv.org/abs/2310.11511) -- [https://arxiv.org/abs/2310.14696](https://arxiv.org/abs/2310.14696) -- [https://arxiv.org/abs/2401.15884](https://arxiv.org/abs/2401.15884) -- [https://arxiv.org/abs/2401.18059](https://arxiv.org/abs/2401.18059) -- [https://arxiv.org/abs/2402.03216v4](https://arxiv.org/abs/2402.03216v4) -- [https://arxiv.org/abs/2405.20139](https://arxiv.org/abs/2405.20139) -- [https://arxiv.org/abs/2407.01449v2](https://arxiv.org/abs/2407.01449v2) -- [https://arxiv.org/abs/2409.04701](https://arxiv.org/abs/2409.04701) -- [https://arxiv.org/abs/2410.05779](https://arxiv.org/abs/2410.05779) -- [https://arxiv.org/abs/2412.19048v2](https://arxiv.org/abs/2412.19048v2) -- [https://arxiv.org/abs/2502.07972v2](https://arxiv.org/abs/2502.07972v2) -- [https://arxiv.org/abs/2502.09304](https://arxiv.org/abs/2502.09304) -- [https://arxiv.org/abs/2502.11371](https://arxiv.org/abs/2502.11371) -- [https://arxiv.org/abs/2502.14902](https://arxiv.org/abs/2502.14902) -- [https://arxiv.org/abs/2503.10150](https://arxiv.org/abs/2503.10150) -- [https://arxiv.org/abs/2506.05176v3](https://arxiv.org/abs/2506.05176v3) -- [https://arxiv.org/abs/2603.15566](https://arxiv.org/abs/2603.15566) -- [https://arxiv.org/html/2403.06789v1](https://arxiv.org/html/2403.06789v1) -- [https://arxiv.org/html/2409.04701v3](https://arxiv.org/html/2409.04701v3) -- [https://arxiv.org/html/2409.10173](https://arxiv.org/html/2409.10173) -- [https://arxiv.org/html/2508.00031v2](https://arxiv.org/html/2508.00031v2) -- [https://arxiv.org/html/2602.20478v1](https://arxiv.org/html/2602.20478v1) -- [https://arxiv.org/pdf/2205.00975](https://arxiv.org/pdf/2205.00975) -- [https://arxiv.org/pdf/2210.11934](https://arxiv.org/pdf/2210.11934) -- [https://arxiv.org/pdf/2402.09906](https://arxiv.org/pdf/2402.09906) -- [https://arxiv.org/pdf/2511.19349](https://arxiv.org/pdf/2511.19349) -- [https://blog.getzep.com/lies-damn-lies-statistics-is-mem0-really-sota-in-agent-memory/](https://blog.getzep.com/lies-damn-lies-statistics-is-mem0-really-sota-in-agent-memory/) -- [https://blog.voyageai.com/2025/01/07/voyage-3-large/](https://blog.voyageai.com/2025/01/07/voyage-3-large/) -- [https://blog.voyageai.com/2025/08/11/rerank-2-5/](https://blog.voyageai.com/2025/08/11/rerank-2-5/) -- [https://code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) -- [https://console.anthropic.com/docs/en/agents-and-tools/tool-use/memory-tool](https://console.anthropic.com/docs/en/agents-and-tools/tool-use/memory-tool) -- [https://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf](https://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf) -- [https://cs.uwaterloo.ca/~jimmylin/publications/Ma_etal_SIGIR2022.pdf](https://cs.uwaterloo.ca/~jimmylin/publications/Ma_etal_SIGIR2022.pdf) -- [https://cursor.com/docs/context/memories](https://cursor.com/docs/context/memories) -- [https://cursor.com/docs/context/rules](https://cursor.com/docs/context/rules) -- [https://docs.anthropic.com/en/docs/claude-code/memory](https://docs.anthropic.com/en/docs/claude-code/memory) -- [https://docs.cline.bot/core-workflows/plan-and-act](https://docs.cline.bot/core-workflows/plan-and-act) -- [https://docs.cline.bot/features/memory-bank](https://docs.cline.bot/features/memory-bank) -- [https://docs.cohere.com/changelog/rerank-v3.5](https://docs.cohere.com/changelog/rerank-v3.5) -- [https://docs.cohere.com/v2/changelog/embed-multimodal-v4](https://docs.cohere.com/v2/changelog/embed-multimodal-v4) -- [https://docs.cursor.sh/context/codebase-indexing](https://docs.cursor.sh/context/codebase-indexing) -- [https://docs.langchain.com/oss/python/integrations/splitters/markdown_header_metadata_splitter](https://docs.langchain.com/oss/python/integrations/splitters/markdown_header_metadata_splitter) -- [https://docs.letta.com](https://docs.letta.com) -- [https://docs.llamaindex.ai/en/stable/examples/property_graph/](https://docs.llamaindex.ai/en/stable/examples/property_graph/) -- [https://docs.voyageai.com/docs/pricing](https://docs.voyageai.com/docs/pricing) -- [https://github.com/aaronsb/obsidian-mcp-plugin](https://github.com/aaronsb/obsidian-mcp-plugin) -- [https://github.com/aceandro2812/AgentHandoff](https://github.com/aceandro2812/AgentHandoff) -- [https://github.com/agiresearch/A-mem](https://github.com/agiresearch/A-mem) -- [https://github.com/amanasmuei/amem](https://github.com/amanasmuei/amem) -- [https://github.com/andrewbergsma/knowledge-mcp](https://github.com/andrewbergsma/knowledge-mcp) -- [https://github.com/asukhodko/chunkana](https://github.com/asukhodko/chunkana) -- [https://github.com/BradenStitt/gitmem](https://github.com/BradenStitt/gitmem) -- [https://github.com/BUPT-GAMMA/PathRAG](https://github.com/BUPT-GAMMA/PathRAG) -- [https://github.com/bynarek/graphrag-js](https://github.com/bynarek/graphrag-js) -- [https://github.com/celstnblacc/obsidian-semantic-mcp](https://github.com/celstnblacc/obsidian-semantic-mcp) -- [https://github.com/circlemind-ai/fast-graphrag](https://github.com/circlemind-ai/fast-graphrag) -- [https://github.com/cmavro/GNN-RAG](https://github.com/cmavro/GNN-RAG) -- [https://github.com/dev-boz/gitmem](https://github.com/dev-boz/gitmem) -- [https://github.com/devwhodevs/engraph](https://github.com/devwhodevs/engraph) -- [https://github.com/eddiearc/long-running-harness](https://github.com/eddiearc/long-running-harness) -- [https://github.com/eman-hc/vault-semantic-mcp](https://github.com/eman-hc/vault-semantic-mcp) -- [https://github.com/FlatbreadLabs/flatbread](https://github.com/FlatbreadLabs/flatbread) -- [https://github.com/flowing-abyss/obsidian-hybrid-search](https://github.com/flowing-abyss/obsidian-hybrid-search) -- [https://github.com/gankim/tree-of-clarifications](https://github.com/gankim/tree-of-clarifications) -- [https://github.com/getzep/graphiti](https://github.com/getzep/graphiti) -- [https://github.com/gusye1234/nano-graphrag](https://github.com/gusye1234/nano-graphrag) -- [https://github.com/hex/claude-sessions](https://github.com/hex/claude-sessions) -- [https://github.com/hhy-huang/HiRAG](https://github.com/hhy-huang/HiRAG) -- [https://github.com/HKUDS/LightRAG](https://github.com/HKUDS/LightRAG) -- [https://github.com/Ian-stetsenko/lore-protocol](https://github.com/Ian-stetsenko/lore-protocol) -- [https://github.com/import-myself/Membench](https://github.com/import-myself/Membench) -- [https://github.com/joe32140/fast-plaid-web](https://github.com/joe32140/fast-plaid-web) -- [https://github.com/langchain-ai/langmem](https://github.com/langchain-ai/langmem) -- [https://github.com/letta-ai/letta](https://github.com/letta-ai/letta) -- [https://github.com/lightonai/next-plaid](https://github.com/lightonai/next-plaid) -- [https://github.com/Lincyaw/vault-mcp](https://github.com/Lincyaw/vault-mcp) -- [https://github.com/mastra-ai/mastra/pull/6595](https://github.com/mastra-ai/mastra/pull/6595) -- [https://github.com/mem0ai/mem0](https://github.com/mem0ai/mem0) -- [https://github.com/microsoft/graphrag](https://github.com/microsoft/graphrag) -- [https://github.com/msdanyg/smart-connections-mcp](https://github.com/msdanyg/smart-connections-mcp) -- [https://github.com/mzazon/vault-search](https://github.com/mzazon/vault-search) -- [https://github.com/neo4j/neo4j-graphrag-python](https://github.com/neo4j/neo4j-graphrag-python) -- [https://github.com/noahshinn/reflexion](https://github.com/noahshinn/reflexion) -- [https://github.com/obra/knowledge-graph](https://github.com/obra/knowledge-graph) -- [https://github.com/parthsarthi03/RAPTOR](https://github.com/parthsarthi03/RAPTOR) -- [https://github.com/pvliesdonk/markdown-vault-mcp](https://github.com/pvliesdonk/markdown-vault-mcp) -- [https://github.com/Shadowsong27/agentic-beacon](https://github.com/Shadowsong27/agentic-beacon) -- [https://github.com/snap-research/locomo](https://github.com/snap-research/locomo) -- [https://github.com/sweir1/obsidian-brain](https://github.com/sweir1/obsidian-brain) -- [https://github.com/syntax-tree/mdast](https://github.com/syntax-tree/mdast) -- [https://github.com/theworldofagents/GCC](https://github.com/theworldofagents/GCC) -- [https://github.com/topoteretes/cognee](https://github.com/topoteretes/cognee) -- [https://github.com/vivek-tiwari-vt/agmem](https://github.com/vivek-tiwari-vt/agmem) -- [https://github.com/willfanguy/obsidian-vault-mcp](https://github.com/willfanguy/obsidian-vault-mcp) -- [https://github.com/WujiangXu/AgenticMemory](https://github.com/WujiangXu/AgenticMemory) -- [https://github.com/xiaowu0162/longmemeval](https://github.com/xiaowu0162/longmemeval) -- [https://github.com/zirkelc/chunkdown](https://github.com/zirkelc/chunkdown) -- [https://graphrag.bynarek.com/](https://graphrag.bynarek.com/) -- [https://help.getzep.com/graphiti/concepts/temporal-model](https://help.getzep.com/graphiti/concepts/temporal-model) -- [https://huggingface.co/Alibaba-NLP/gte-Qwen2-7B-instruct](https://huggingface.co/Alibaba-NLP/gte-Qwen2-7B-instruct) -- [https://huggingface.co/BAAI/bge-m3](https://huggingface.co/BAAI/bge-m3) -- [https://huggingface.co/BAAI/bge-reranker-v2-m3](https://huggingface.co/BAAI/bge-reranker-v2-m3) -- [https://huggingface.co/GritLM/GritLM-7B](https://huggingface.co/GritLM/GritLM-7B) -- [https://huggingface.co/mixedbread-ai/mxbai-rerank-large-v2](https://huggingface.co/mixedbread-ai/mxbai-rerank-large-v2) -- [https://huggingface.co/nomic-ai/nomic-embed-text-v2-moe](https://huggingface.co/nomic-ai/nomic-embed-text-v2-moe) -- [https://huggingface.co/NovaSearch/stella_en_1.5B_v5](https://huggingface.co/NovaSearch/stella_en_1.5B_v5) -- [https://huggingface.co/nvidia/NV-Embed-v2](https://huggingface.co/nvidia/NV-Embed-v2) -- [https://huggingface.co/Snowflake/snowflake-arctic-embed-l-v2.0](https://huggingface.co/Snowflake/snowflake-arctic-embed-l-v2.0) -- [https://huggingface.co/vidore](https://huggingface.co/vidore) -- [https://jina.ai/news/jina-reranker-v2-for-agentic-rag-ultra-fast-multilingual-function-calling-and-code-search](https://jina.ai/news/jina-reranker-v2-for-agentic-rag-ultra-fast-multilingual-function-calling-and-code-search) -- [https://langchain-ai.github.io/langmem/concepts/conceptual_guide](https://langchain-ai.github.io/langmem/concepts/conceptual_guide) -- [https://link.springer.com/article/10.1007/s10489-025-06885-5](https://link.springer.com/article/10.1007/s10489-025-06885-5) -- [https://lore-protocol.com/](https://lore-protocol.com/) -- [https://med-miriad.github.io/](https://med-miriad.github.io/) -- [https://mem0.ai/research-3](https://mem0.ai/research-3) -- [https://mixedbread.com/blog/mxbai-rerank-v2](https://mixedbread.com/blog/mxbai-rerank-v2) -- [https://openai.com/blog/memory-and-new-controls-for-chatgpt](https://openai.com/blog/memory-and-new-controls-for-chatgpt) -- [https://pypi.org/project/agmem/](https://pypi.org/project/agmem/) -- [https://qdrant.tech/articles/bm42/](https://qdrant.tech/articles/bm42/) -- [https://qwenlm.github.io/blog/qwen3-embedding/](https://qwenlm.github.io/blog/qwen3-embedding/) -- [https://selfrag.github.io/](https://selfrag.github.io/) -- [https://semiherdogan.medium.com/handoff-a-better-way-to-run-autonomous-development-loops-00e97e62d470](https://semiherdogan.medium.com/handoff-a-better-way-to-run-autonomous-development-loops-00e97e62d470) -- [https://snap-research.github.io/locomo/](https://snap-research.github.io/locomo/) -- [https://snowflake.com/en/engineering-blog/snowflake-arctic-embed-2-multilingual](https://snowflake.com/en/engineering-blog/snowflake-arctic-embed-2-multilingual) -- [https://velite.js.org/](https://velite.js.org/) -- [https://www.agents.md/](https://www.agents.md/) -- [https://www.answer.ai/posts/2024-08-02-jacolbert-v25.html](https://www.answer.ai/posts/2024-08-02-jacolbert-v25.html) -- [https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) -- [https://www.codesota.com/benchmarks/mteb](https://www.codesota.com/benchmarks/mteb) -- [https://www.langchain.com/blog/deconstructing-rag](https://www.langchain.com/blog/deconstructing-rag) -- [https://www.letta.com/blog/context-repositories](https://www.letta.com/blog/context-repositories) -- [https://www.microsoft.com/en-us/research/publication/from-local-to-global-a-graph-rag-approach-to-query-focused-summarization/](https://www.microsoft.com/en-us/research/publication/from-local-to-global-a-graph-rag-approach-to-query-focused-summarization/) -- [https://www.tigerdata.com/blog/hybrid-search-postgres-you-probably-should](https://www.tigerdata.com/blog/hybrid-search-postgres-you-probably-should) -- [https://xiaowu0162.github.io/long-mem-eval/](https://xiaowu0162.github.io/long-mem-eval/) From 954c17d9c4d888ed3919b686d416f26793421817 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 23 Aug 2026 09:06:05 +0000 Subject: [PATCH 6/6] docs: supersede stale comparison-page watch finding Write a Finding that the comparison page now matches shipped watch and configured-ref validation, then supersede the old rubric claim. Addresses review on #265. Change-Id: Ide3d5bd592a8fe51c109503fb3ef38131b592b44 Co-authored-by: Erika Ruth Witt --- ...-shipped-watch-and-va--bkat8y0abty4pvcz.md | 23 +++++++++++++++++++ ...ped-validation-and-wa--p04gd8xfknwvz2pe.md | 2 ++ 2 files changed, 25 insertions(+) create mode 100644 .flatbread-proof/findings/fnd-comparison-page-now-matches-shipped-watch-and-va--bkat8y0abty4pvcz.md diff --git a/.flatbread-proof/findings/fnd-comparison-page-now-matches-shipped-watch-and-va--bkat8y0abty4pvcz.md b/.flatbread-proof/findings/fnd-comparison-page-now-matches-shipped-watch-and-va--bkat8y0abty4pvcz.md new file mode 100644 index 00000000..157fe2ed --- /dev/null +++ b/.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. diff --git a/.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md b/.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md index c64fadbd..4973199e 100644 --- a/.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md +++ b/.flatbread-proof/findings/fnd-pmf-rubric-understates-shipped-validation-and-wa--p04gd8xfknwvz2pe.md @@ -7,6 +7,8 @@ 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