diff --git a/.flatbread-proof/citations/cit-github-search-api-topic-counts-24-august-2026--m9s9pj2v1d5fad3p.md b/.flatbread-proof/citations/cit-github-search-api-topic-counts-24-august-2026--m9s9pj2v1d5fad3p.md new file mode 100644 index 00000000..6511c52a --- /dev/null +++ b/.flatbread-proof/citations/cit-github-search-api-topic-counts-24-august-2026--m9s9pj2v1d5fad3p.md @@ -0,0 +1,9 @@ +--- +id: cit-github-search-api-topic-counts-24-august-2026--m9s9pj2v1d5fad3p +effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz +title: 'GitHub Search API topic counts, 24 August 2026' +role: evidence +created_at: '2026-08-24T01:46:44.637Z' +--- + +https://docs.github.com/en/rest/search/search#search-repositories — GET /search/repositories?q=topic:&sort=stars. Counts and top-starred repos captured 2026-08-24 from this cloud-agent run against public GitHub. diff --git a/.flatbread-proof/decisions/dec-use-twelve-github-topics-that-mix-demand-with-ra--67c632y486se7a9b.md b/.flatbread-proof/decisions/dec-use-twelve-github-topics-that-mix-demand-with-ra--67c632y486se7a9b.md new file mode 100644 index 00000000..b0219460 --- /dev/null +++ b/.flatbread-proof/decisions/dec-use-twelve-github-topics-that-mix-demand-with-ra--67c632y486se7a9b.md @@ -0,0 +1,43 @@ +--- +id: dec-use-twelve-github-topics-that-mix-demand-with-ra--67c632y486se7a9b +effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz +title: Use twelve GitHub topics that mix demand with rankable niches +state: accepted +created_at: '2026-08-24T01:46:47.307Z' +derives_from: + - fnd-github-topic-pages-only-rank-flatbread-in-small--0p910vppn6z2nd3m +--- + +Keep the GitHub About blurb **Context alignment, version controlled.** Put that same line on the README. Cut the live topic list from 20 implementation labels to 12 niches where Flatbread either already ranks, would rank at 64 stars, or is an honest demand filter for agent memory and file-based content. + +Canonical list, About-sidebar order, stored in `.github/topics.json`: + +1. `agent-memory` +2. `coding-agents` +3. `context-engineering` +4. `project-memory` +5. `context-management` +6. `agent-context` +7. `llm-memory` +8. `git-native` +9. `markdown-cms` +10. `git-cms` +11. `file-based-cms` +12. `docs-as-code` + +Lead seven name the fragmented-context problem for coding agents. Trailing five name the Git/file publishing path (`markdown-cms` is already 1st of 13; `git-cms` is already 4th of 17; `file-based-cms` would be 2nd of 14). + +Drop `ai-agents`, `markdown`, `javascript`, `typescript`, `nodejs`, `nextjs`, `yaml` (oceans), `graphql` / `graphql-codegen` (one read interface), `headless-cms` and `knowledge-graph` (true phrases, unwinnable pages), `agent-skills` (a skill is a channel, not the product), `local-first` / `knowledge-base` / `static-content` (wrong communities), and `mcp` / `rag` / `claude-code` (untrue). + +GitHub does not read `.github/topics.json`. A repo admin applies it with `gh api -X PUT repos/FlatbreadLabs/flatbread/topics --input .github/topics.json`. npm `keywords` on the public `flatbread` package mirror the twelve, plus `markdown` and `knowledge-graph` for npm search. + +## Alternatives considered + +- **Handoff ten:** `ai-agents`, `agent-memory`, `agent-context`, `coding-agents`, `knowledge-graph`, `context-management`, `git-native`, `markdown`, `git-cms`, `headless-cms`. Rejected as-is: it drops `markdown-cms` (already 1st), skips `context-engineering` and `project-memory` / `file-based-cms` (rankable or high-demand), and keeps oceans `ai-agents` / `markdown` plus unwinnable `headless-cms` / `knowledge-graph`. +- **Keep all 20 current topics.** Rejected: GitHub caps at 20, so every ocean crowds out a niche we can actually win. +- **Only rankable tags** (`markdown-cms`, `git-cms`, `git-native`, `file-based-cms`, `agent-context`, `project-memory`). Rejected: people searching `agent-memory` never see the repo. +- **Change the tagline** to a longer two-path slogan. Rejected: the short line already names the problem; the README table explains the two paths. + +## Reversal criteria + +Revisit when stars cross a few hundred (demand-topic pages become reachable), when a new surface ships and a tag becomes true (MCP, hosted search), or when `markdown-cms` / `git-cms` stop matching how searchers name the publishing path. diff --git a/.flatbread-proof/findings/fnd-github-topic-pages-only-rank-flatbread-in-small--0p910vppn6z2nd3m.md b/.flatbread-proof/findings/fnd-github-topic-pages-only-rank-flatbread-in-small--0p910vppn6z2nd3m.md new file mode 100644 index 00000000..bd27d361 --- /dev/null +++ b/.flatbread-proof/findings/fnd-github-topic-pages-only-rank-flatbread-in-small--0p910vppn6z2nd3m.md @@ -0,0 +1,43 @@ +--- +id: fnd-github-topic-pages-only-rank-flatbread-in-small--0p910vppn6z2nd3m +effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz +title: GitHub topic pages only rank Flatbread in small niches +kind: measurement +created_at: '2026-08-24T01:46:46.012Z' +cites: + - cit-github-search-api-topic-counts-24-august-2026--m9s9pj2v1d5fad3p +--- + +GitHub topic pages sort by stars. FlatbreadLabs/flatbread had 64 stars on 24 August 2026. The live repo had 20 topics, many of them implementation labels (javascript, nodejs, graphql, nextjs). + +Search method: GitHub REST `GET /search/repositories?q=topic:&sort=stars`. + +Current ranks where Flatbread is already tagged: + +- markdown-cms: 13 repos, Flatbread is 1st (next is 50 stars). +- git-cms: 17 repos, Flatbread is 4th after nuxt/content (3661), plentico/plenti (1076), sitepins/sitepins (154). +- git-native: 59 repos, Flatbread is 6th. + +Niches not currently tagged where 64 stars would still show: + +- file-based-cms: 14 repos; current 2nd has 35 stars, so Flatbread would be 2nd. +- project-memory: 154 repos; top repo has 497 stars; 64 stars should make the first page. +- agent-context: 77 repos; after pingcap/tidb (a 40k-star noise tag) the next repos are 1370, 469, 188, 107, 83, 72, 59. 64 stars should show. + +Demand topics people search, but we will not rank yet: + +- agent-memory: 2958 repos, top ~71k stars. +- coding-agents: 3244 repos, top ~90k stars. +- context-engineering: 2773 repos, top is a Java guide wearing the tag (~158k). +- context-management: 1321 repos, top ~89k stars. +- llm-memory: 451 repos, top ~15k stars. +- docs-as-code: 368 repos, top ~3.7k stars. +- headless-cms: 1667 repos, Strapi 73k. Real CMS traffic, no rank chance at 64 stars. + +Oceans that hide a 64-star repo: ai-agents 77078, markdown 37339, javascript 670087, typescript 413824, nodejs 333467, nextjs 178931. + +Empty vanity tags (single-digit repo counts, no searchers): context-alignment, durable-memory, markdown-database. + +Dishonest until we ship the surface: mcp (65155), rag (42198), graph-rag (349), claude-code (63170). + +This is a measurement of discovery supply and current rank, not of product fit alone. diff --git a/.github/topics.json b/.github/topics.json new file mode 100644 index 00000000..aded1a3d --- /dev/null +++ b/.github/topics.json @@ -0,0 +1,16 @@ +{ + "names": [ + "agent-memory", + "coding-agents", + "context-engineering", + "project-memory", + "context-management", + "agent-context", + "llm-memory", + "git-native", + "markdown-cms", + "git-cms", + "file-based-cms", + "docs-as-code" + ] +} diff --git a/docs/comparison.md b/docs/comparison.md index b5dbd4e6..2b4e90b9 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -7,6 +7,10 @@ so you can decide whether it fits your project. project into data your app can read. GraphQL and codegen are common ways to read that data, but they are not the product itself. +Public tagline: **Context alignment, version controlled.** See +[Flatbread positioning](./positioning.md) for the GitHub About blurb and +the topic list used for discovery. + ## How to use this table Each column describes a group of tools, not every product in that group. diff --git a/docs/positioning.md b/docs/positioning.md index 4b04ae42..7cc69b2f 100644 --- a/docs/positioning.md +++ b/docs/positioning.md @@ -42,6 +42,72 @@ 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. +## Public tagline and GitHub topics + +**Tagline:** Context alignment, version controlled. + +That line is the GitHub About blurb. It names the problem — people, agents, and +the record of _why_ drifting apart — and the store (Git). It does not name +GraphQL, CMS, or Markdown. Keep it. The README and this page explain the two +paths; the About field should stay short. + +### Canonical GitHub topics + +GitHub shows at most 20 topics. Topic pages sort by stars. Flatbread had 64 +stars on 24 August 2026, so it only ranks on small, specific topics. Oceans +such as `javascript` or `ai-agents` hide the repo. Tiny, honest niches already +show it near the top. + +The live list lives in [`.github/topics.json`](../.github/topics.json). That +file is the payload for GitHub's topics API. A repo admin applies it after +this change lands on `main`: + +```bash +gh api -X PUT repos/FlatbreadLabs/flatbread/topics --input .github/topics.json +``` + +Order is the About sidebar order: agent memory first, then Git/file content. + +| Topic | Why it is here | 24 Aug 2026 snapshot | +| --------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `agent-memory` | Name of the Proof path. People filter for this. | 2,958 repos. Top of the page is 70k-star work. We will not rank it yet. | +| `coding-agents` | Who the lead path is for. | 3,244 repos. Same: demand tag, not a ranking bet. | +| `context-engineering` | The 2026 name for designing what an agent sees. Flatbread is a versioned context source. | 2,773 repos. High search interest; Java tutorials also wear this tag. | +| `project-memory` | Exact pain: memory that belongs to the repo, not a chat. | 154 repos. Top repo has 497 stars. 64 stars should land on the first page. | +| `context-management` | Operational name for stopping context drift. | 1,321 repos. Demand tag. | +| `agent-context` | Closest topic to the tagline. | 77 repos. After noise tags (TiDB), the next repos are 1.3k stars and down. 64 stars should show. | +| `llm-memory` | Research and memory-library searchers use this, not `agent-memory`. | 451 repos. Demand tag; first page is 15k-star work. | +| `git-native` | How the store works, without saying "GitHub". | 59 repos. Flatbread is already 6th (64 stars). | +| `markdown-cms` | File-based publishing path, Markdown-shaped. | 13 repos. Flatbread is already 1st. | +| `git-cms` | Git-backed content for sites and docs. | 17 repos. Flatbread is already 4th, after Nuxt Content and Plenti. | +| `file-based-cms` | Common search phrase for Contentlayer-class tools. | 14 repos. 64 stars would be 2nd (current 2nd has 35 stars). | +| `docs-as-code` | Docs and internal-tool path, smaller than `headless-cms`. | 368 repos. First page starts at 3.7k stars; still the honest docs niche. | + +### Dropped topics + +The repo previously used 20 topics, many of them implementation labels. + +| Topic | Why it is out | +| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ai-agents`, `markdown`, `javascript`, `typescript`, `nodejs`, `nextjs`, `yaml` | Oceans. 37k–670k repos. A 64-star project never appears. README search still matches those words. | +| `graphql`, `graphql-codegen` | One read interface, not the product. | +| `headless-cms` | Real CMS search traffic, but Strapi (73k stars) owns the page. `git-cms` / `markdown-cms` / `file-based-cms` are the niches we can win. | +| `knowledge-graph` | Proof is a Git-tracked graph of records. The topic page is Neo4j, RAG, and PKM giants (100k-star range). Keep the phrase in prose; do not compete there. | +| `knowledge-base`, `local-first`, `static-content` | Adjacent communities (wikis, CRDTs, SSGs) that are not this product. | +| `agent-skills` | The Proof skill is a distribution channel. This repo is not a skill pack. | +| `mcp`, `rag`, `graph-rag`, `claude-code` | Dishonest until we ship those surfaces. Hitchhiking on `claude-code` (63k repos) would also pin us to one host. | + +### What this is not + +Do not add empty vanity tags such as `context-alignment` or `durable-memory` +(single-digit repo counts, no searchers). Do not add `git-based-cms`: Decap CMS +already owns that 41-repo page, and `git-cms` covers the same idea with a +better current rank. + +Revisit the list when star count crosses a few hundred (demand-topic pages +become reachable) or when a new surface ships (MCP, hosted search) and a new +tag becomes true. + **What Flatbread does not do:** - It is not a hosted CMS, dashboard, or writing UI. diff --git a/packages/flatbread/README.md b/packages/flatbread/README.md index 912a6a85..90c08229 100644 --- a/packages/flatbread/README.md +++ b/packages/flatbread/README.md @@ -4,6 +4,8 @@

Flatbread

+

Context alignment, version controlled.

+

pipeline status @@ -16,9 +18,12 @@

-Flatbread turns files in Git into a typed relational graph. Each Markdown or -YAML file becomes a record in a named collection, and `refs` in -`flatbread.config.js` link records to each other by ID. Your files stay the +Flatbread keeps shared project context in Git so humans and coding agents +stay aligned on long-running work. The same files are a typed relational +graph that a site, docs set, or app can query. + +Each Markdown or YAML file becomes a record in a named collection, and `refs` +in `flatbread.config.js` link records to each other by ID. Your files stay the source of truth, with normal Git branches, reviews, and history. GraphQL is one read interface over that graph, not the whole product: apps can also read it through generated TypeScript, and coding agents read it through bounded diff --git a/packages/flatbread/package.json b/packages/flatbread/package.json index d3d07791..a606ea81 100644 --- a/packages/flatbread/package.json +++ b/packages/flatbread/package.json @@ -2,6 +2,22 @@ "name": "flatbread", "version": "1.1.0", "description": "Git-native memory for coding agents and relational content for TypeScript apps. Files in your repo become a typed graph you read over GraphQL, generated TypeScript, or the CLI.", + "keywords": [ + "agent-memory", + "coding-agents", + "context-engineering", + "project-memory", + "context-management", + "agent-context", + "llm-memory", + "git-native", + "markdown-cms", + "git-cms", + "file-based-cms", + "docs-as-code", + "markdown", + "knowledge-graph" + ], "type": "module", "scripts": { "build": "tsup", diff --git a/scripts/github-topics.test.js b/scripts/github-topics.test.js new file mode 100644 index 00000000..94464079 --- /dev/null +++ b/scripts/github-topics.test.js @@ -0,0 +1,46 @@ +import test from 'ava'; +import { readFileSync } from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); + +function readRepo(rel) { + return readFileSync(path.join(root, rel), 'utf8'); +} + +const TOPIC_NAME = /^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$/; +const APPLY_PAYLOAD = JSON.parse(readRepo('.github/topics.json')); + +test('GitHub topics payload is a names list GitHub will accept', (t) => { + t.deepEqual(Object.keys(APPLY_PAYLOAD).sort(), ['names']); + t.true(Array.isArray(APPLY_PAYLOAD.names)); + t.true(APPLY_PAYLOAD.names.length >= 8); + t.true(APPLY_PAYLOAD.names.length <= 20); + t.is(new Set(APPLY_PAYLOAD.names).size, APPLY_PAYLOAD.names.length); + + for (const name of APPLY_PAYLOAD.names) { + t.regex(name, TOPIC_NAME); + t.false(name.includes('--')); + } +}); + +test('positioning docs, README tagline, and npm keywords use the same topic set', (t) => { + const positioning = readRepo('docs/positioning.md'); + const readme = readRepo('packages/flatbread/README.md'); + const pkg = JSON.parse(readRepo('packages/flatbread/package.json')); + + t.true(readme.includes('Context alignment, version controlled.')); + t.true(Array.isArray(pkg.keywords)); + + for (const name of APPLY_PAYLOAD.names) { + t.true( + positioning.includes('`' + name + '`'), + `docs/positioning.md must name ${name}` + ); + t.true( + pkg.keywords.includes(name), + `flatbread keywords must include ${name}` + ); + } +});