release: prepare Flatbread 1.0

.agents/skills/effort-graph/release.json

@@ -1,6 +1,6 @@
 {
   "format": 1,
-  "flatbreadVersion": "1.0.0-alpha.22",
-  "effortGraphVersion": "0.1.0-alpha.0",
-  "gitTag": "v1.0.0-alpha.22"
+  "flatbreadVersion": "1.0.0",
+  "effortGraphVersion": "1.0.0",
+  "gitTag": "v1.0.0"
 }

.flatbread-efforts/decisions/dec-keep-effort-graph-secondary-with-a-primary-wedge--estattvqnhffm2dc.md

@@ -2,10 +2,12 @@
 id: dec-keep-effort-graph-secondary-with-a-primary-wedge--estattvqnhffm2dc
 effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002
 title: Keep Effort Graph secondary with a primary-wedge gate
-state: accepted
+state: superseded
 created_at: '2026-07-18T19:43:02.802Z'
 derives_from:
   - fnd-filtered-retrieval-is-94-percent-smaller--qpvz4vch5hygye20
+superseded_by:
+  - dec-lead-flatbread-1-0-with-effort-graph-agent-memor--nhxsqm8sd43s2avx
 ---
 
 Keep the graph as a strong candidate secondary vertical rather than displacing

.flatbread-efforts/decisions/dec-lead-flatbread-1-0-with-effort-graph-agent-memor--nhxsqm8sd43s2avx.md

@@ -0,0 +1,21 @@
+---
+id: dec-lead-flatbread-1-0-with-effort-graph-agent-memor--nhxsqm8sd43s2avx
+effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002
+title: Lead Flatbread 1.0 with Effort Graph agent memory
+state: accepted
+created_at: '2026-07-29T10:43:48.897Z'
+supersedes:
+  - dec-keep-effort-graph-secondary-with-a-primary-wedge--estattvqnhffm2dc
+---
+
+## Context
+
+Flatbread 1.0 is the first stable npm release. The release brief asks the public docs and package copy to lead with the utility already shipped through Effort Graph, while keeping Flatbread useful for general static relational content.
+
+## Decision
+
+Lead Flatbread 1.0 positioning with Effort Graph as Git-native memory for coding agents. Present static relational content for sites, docs, and internal tools as a first-class general use. Keep GraphQL and generated TypeScript as read interfaces over the graph, not the product identity.
+
+## Consequences
+
+The root README, npm descriptions, positioning guide, and release notes use this hierarchy. The release does not add a hosted CMS, semantic search, general writes, or a new runtime contract. Proof remains workflow tooling rather than the memory product. Revisit this lead only when user evidence shows another use case explains Flatbread more clearly.

CHANGELOG.md

@@ -0,0 +1,98 @@
+# Changelog
+
+Notes for the Flatbread release train. Some packages also keep their own
+changelog; this file covers the repository as a whole.
+
+## 1.0.0
+
+First stable release. The alpha train ended at `flatbread@1.0.0-alpha.22`.
+
+Twelve packages make up the 1.0 release set. They all ship at `1.0.0` and move
+in lockstep from here. One version number across the set, so you no longer have
+to work out which alpha of one package matches which alpha of another.
+
+Nine were already on npm as alphas and go to `1.0.0` from there:
+
+`flatbread`, `@flatbread/core`, `@flatbread/config`, `@flatbread/codegen`,
+`@flatbread/resolver-svimg`, `@flatbread/source-filesystem`,
+`@flatbread/transformer-markdown`, `@flatbread/transformer-yaml`, and
+`@flatbread/utils`.
+
+Three reach npm for the first time in this release:
+
+- `@flatbread/effort-graph` writes and reads agent memory records.
+- `@flatbread/explorer` serves the single-page app for browsing a content graph.
+- `@flatbread/proof` runs a task DAG of Cursor subagents.
+
+### Packaging
+
+- Every package declares `engines.node: ">=20.19"`. The old floors were
+  `^14.13.1 || >=16.0.0`, `>=18`, and in several packages nothing at all. Node
+  18, and Node 20 before 20.19, are no longer supported.
+- `@flatbread/config` declares `@flatbread/core` as a runtime dependency. It
+  was a devDependency, which worked inside this monorepo and nowhere else.
+- `@flatbread/core` no longer emits type declarations a packed install cannot
+  resolve. Its `.d.ts` files reached into the private paths
+  `graphql/jsutils/Maybe` and `graphql/jsutils/ObjMap`; they now use public
+  GraphQL types, and `FlatbreadProvider.query()` declares its return as
+  GraphQL's public `ExecutionResult`. `vfile@5.3.4` moves from devDependencies
+  to dependencies, because the public types name `VFile`.
+- `@flatbread/codegen` widens its peer range on `@flatbread/config` and
+  `@flatbread/core` from `workspace:*` to `workspace:^`, so it publishes a
+  caret range instead of an exact pin.
+- `flatbread` drops five runtime dependencies that no code imported:
+  `apollo-server-core`, `apollo-server-express`, `express-graphql`,
+  `remark-github`, and `serialize-javascript`. `picomatch` moves to
+  devDependencies; only a test uses it. Versions move too: `@apollo/server` to
+  5.5.1, the pinned `graphql` to 16.14.2, and `@flatbread/core`'s `lodash-es`
+  to 4.18.1.
+- `@flatbread/codegen` moves its four GraphQL Code Generator packages (`cli`,
+  `typescript`, `typescript-operations`, and `typed-document-node`) onto
+  supported major lines, and `@flatbread/config` moves its pinned `esbuild`
+  from 0.15.1 to 0.25.0. Nothing you get out changes: the same schema still
+  generates byte-identical files.
+- `@flatbread/proof` stops shipping `src` and `scripts`, tests and all, in its
+  npm tarball. The bins and `dist` still ship, which is all the package needs
+  to run.
+- `@flatbread/resolver-svimg` points its `repository`, `homepage`, and `bugs`
+  links at `FlatbreadLabs/flatbread`. They still named the old
+  `tonyketcham/flatbread` fork.
+- Every package carries a description that says what that package does.
+
+### Known dependency limits
+
+A clean install of all twelve packages reports seven `npm audit` entries that
+npm marks as having no fix available; the main `flatbread` install and its
+nine-package set report none, so the two packages below do not affect it.
+
+- `@flatbread/proof` inherits three moderate and high entries from
+  `@cursor/sdk`, which depends on `@connectrpc/connect-node@1.x` and through it
+  `undici@5.x`. No current or later `@cursor/sdk` release clears them, and the
+  later releases require Node 22.13 or newer.
+- `@flatbread/resolver-svimg` inherits four high entries from its required peer
+  `svimg`, which depends on `sharp`. The latest `svimg@4` still pins `sharp`
+  below the patched 0.35 line, and it changes the import API this resolver
+  uses.
+
+### Docs
+
+- The READMEs and `docs/positioning.md` now lead with the Effort Graph: an
+  agent's Efforts, Issues, Findings, Decisions, Constraints, Risks, Citations,
+  and Blobs written as Markdown records in your repository. The reasoning gets
+  committed and reviewed like the code.
+- Relational content for sites, docs, and internal tools stays a first-class
+  second path on the same engine, and GraphQL is described as one read
+  interface over the graph rather than as the product.
+- Removed the banner that called the whole project experimental. The narrower
+  qualifiers still hold: the generated TypeScript read API is a prototype, and
+  its selection-string escape hatch is experimental.
+- The `@flatbread/effort-graph` README no longer claims Git ignores the journal
+  for you. It names the default `.flatbread-efforts` root, lists the two
+  `.gitignore` lines you must add, and points at
+  `flatbread effort bootstrap --verify`, which exits nonzero when setup is
+  incomplete.
+
+There is no migration guide. Of the changes above, the Node floor is the one
+that can break an install. For anything else that moved since
+`1.0.0-alpha.22`, read the Git history; the alpha train did not keep
+per-release notes.

CONTRIBUTING.md

@@ -93,6 +93,20 @@ There are two steps:
 1. Bump versions where there are changes
 2. Publish the changed packages
 
+### One-time note for 1.0
+
+The 1.0 release put every published package on `1.0.0` at once, rather than
+letting each package carry its own alpha number. `pnpm bump` still works the
+same way: it preselects the packages that changed plus their workspace
+dependents. Only bump every package together again when a release calls for it.
+
+`packages/effort-graph/skills/effort-graph/release.json` records the version an
+end user installs. Edit that file, not the copy in `.agents/`. Then run
+`pnpm skills:sync` to refresh the `.agents/` copy and `pnpm skills:pack-check`,
+which fails unless `flatbreadVersion` and `effortGraphVersion` match the current
+`package.json` versions and `gitTag` equals `v<flatbreadVersion>`. `pnpm verify`
+runs both checks.
+
 ### 1) Bump versions only where there are changes
 
 Use the interactive bump script:
@@ -189,7 +203,8 @@ Details:
   deleted after publication.
 
 End users install the skill from that release tag and install the matching
-`flatbread` version:
+`flatbread` version. Replace `X` with the released version — `1.0.0` for the
+first stable release, so the tag is `v1.0.0`:
 
 ```bash
 npx skills add https://github.com/FlatbreadLabs/flatbread/tree/vX/packages/effort-graph/skills/effort-graph --skill effort-graph

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Flatbread contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/positioning.md

@@ -6,15 +6,38 @@ To compare Flatbread with databases, CMSs, and other file-based tools, see
 [Comparing Flatbread with other tools](./pmf-decision-rubric.md). For keeping
 and moving your data, see [data ownership](./data-ownership.md).
 
-Turn files in Git into typed, related content for your TypeScript app. A
-Flatbread project has collections, records, and `refs` that link records.
-Generated types and [GraphQL](https://graphql.org/) operations are common ways
-for an app to read that data; they do not define what Flatbread is.
+Flatbread turns files in Git into a typed relational graph. A project has
+collections, records, and `refs` that link records. Generated types and
+[GraphQL](https://graphql.org/) operations are common ways for an app to read
+that graph; they do not define what Flatbread is.
 
 **Flatbread** reads content from your repository and file system. Plugins
 control how it reads files and turns them into data.
 
-**Who it is for:** Teams building TypeScript sites, internal tools, and starter
+## The lead use case: memory for coding agents
+
+The [Effort Graph](../packages/effort-graph/README.md) is a Flatbread content
+model for what a coding agent works out along the way. An agent records an
+Effort and then writes Issues, Findings, Decisions, Constraints, Risks,
+Citations, and Blobs against it. Each record is a markdown file under
+`.flatbread-efforts/`, so it is committed, diffed, reviewed, and reverted like
+source. Writes go through `flatbread effort write`; reads come back as bounded
+digests from `flatbread effort list`, `records`, `relations`,
+`blocking-decisions`, and `get`.
+
+That solves a plain problem: an agent that closes its session forgets why it
+chose what it chose. Putting the reasoning in the repository keeps it next to
+the code it explains, and keeps it readable by a person.
+
+## The general case: relational content
+
+Everything above is one content model on a general engine. The same
+collections, `refs`, filters, and generated types back sites, docs, and
+internal tools. Posts point at authors; authors point at each other. Model your
+own collections and you get the same typed graph.
+
+**Who it is for:** People building coding agents that need memory a human can
+review in Git, and teams building TypeScript sites, internal tools, and starter
 projects that want versioned, reviewable content and links between entries
 without setting up a CMS database.
 
@@ -23,13 +46,15 @@ without setting up a CMS database.
 - It is not a hosted CMS, dashboard, or writing UI.
 - It is not a general-purpose GraphQL platform or database. Transactions,
   detailed access control, and many concurrent writers are outside its scope.
-- [`flatbread start --watch`](./local-dev-loop.md) reloads valid content and
-  config changes. Changes to Flatbread packages still need their own rebuild or
+- It does not reload its own packages.
+  [`flatbread start --watch`](./local-dev-loop.md) picks up valid content and
+  config changes, but a change to a Flatbread package needs a rebuild and a
   restart.
 
-**GraphQL:** In the default setup, GraphQL reads data that Flatbread has already
-loaded (`schema → operations → codegen`). Start with files and configuration,
-then choose how your app reads the data. The
+**GraphQL:** GraphQL is one read interface over the graph. In the default setup
+it reads data that Flatbread has already loaded, following
+`schema → operations → codegen`. Start with files and configuration, then
+choose how your app reads the data. The
 [Quickstart](../packages/flatbread/README.md#quickstart-posts-authors-and-tags)
 shows posts, authors, and tags from files through generated types.