Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/conventions.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ on:
pull_request:
jobs:
conventions:
uses: robertblust/conventions/.github/workflows/check.yml@v1.53.0
uses: robertblust/conventions/.github/workflows/check.yml@v1.55.0
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!-- conventions · v1.53.0 -->
<!-- conventions · v1.55.0 -->
Shared conventions of the robertblust, guestgraph and companygraph organizations live in `conventions/`, vendored from robertblust/conventions at the release `conventions.json` names. Read them before writing or committing anything here.

- `conventions/WRITING.md` — how we write: one voice, three registers, English and German.
Expand Down
2 changes: 1 addition & 1 deletion conventions.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{ "repo": "robertblust/conventions", "tag": "v1.53.0", "exclude": ["target", ".specify", ".claude", "docs/superpowers"], "format-exclude": ["target", ".specify", ".claude"] }
{ "repo": "robertblust/conventions", "tag": "v1.55.0", "exclude": ["target", ".specify", ".claude", "docs/superpowers"], "format-exclude": ["target", ".specify", ".claude"] }
2 changes: 1 addition & 1 deletion conventions/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
<!-- conventions · v1.53.0 -->
<!-- conventions · v1.55.0 -->
Shared conventions of the robertblust, guestgraph and companygraph organizations live in `conventions/`, vendored from robertblust/conventions at the release `conventions.json` names. Read them before writing or committing anything here.

- `conventions/WRITING.md` — how we write: one voice, three registers, English and German.
Expand Down
2 changes: 2 additions & 0 deletions conventions/GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,8 @@ The German cells are inline code because the prose check reads no language and a
| GitHub issue | GitHub issue | `GitHub-Issue` | GitHub's name for an issue. Neuter, `das GitHub-Issue`, plural `die GitHub-Issues`. |
| MCP | MCP | `MCP` | The protocol an agent reads a model over. A name, English in both languages, and it compounds with a hyphen. |
| MCP server | MCP server | `MCP-Server` | The server that answers over MCP; `companygraph/mcp-server` is the package. Masculine, `der MCP-Server`. |
| chat host | host | `Chat-Host` | One deployment of the chat server, which a page running the chat on two clouds lets a reader choose with `/backend`. Masculine, `der Chat-Host`, genitive `des Chat-Hosts`. |
| Switzerland North | Switzerland North | `Azure-Region Schweiz Nord` | Microsoft Azure's Swiss region, where the Azure copies of the servers run. Named as Azure's region, because no place is called Schweiz Nord and a bare `Schweiz Nord` read as a half-translated name; the owner chose it on 2026-11-07. |
| MCP Registry | MCP Registry | `MCP Registry` | The public index a server is published to. A proper name, English in both languages, and feminine: `in der MCP Registry`, never `im`. No page carried German for it before, which is why the gender is recorded here rather than left to the next sentence. |
| AI agent | AI agent | `KI-Agent` | The reader a model serves beside a person. Masculine, `der KI-Agent`, plural `die KI-Agenten`, the form blust.ch's ideas page already uses. |
| AI Act | AI Act | `AI Act` | The EU's regulation on artificial intelligence, whose Article 50 asks a chat to say that an AI answers. A name, English in both languages, as `MCP` and `core` are, so a reader matches the German page to the English one; masculine, `der AI Act`. Not `KI-Verordnung`, the German press's term, set aside on 2026-10-11 so both pages carry the one name. |
Expand Down
10 changes: 5 additions & 5 deletions conventions/REPOSITORIES.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Three organizations, one family. `robertblust` holds the person and the shared m
| robertblust/robertblust.github.io | blust.ch | blust.ch, the profile page and its talks | main | ~/git/robertblust/robertblust.github.io |
| robertblust/mental-model | Robert Blust — Mental Model | Robert Blust described in CompanyGraph, the reference instance | main | ~/git/robertblust/mental-model |
| robertblust/field-notes | Robert Blust — Field Notes | problems that took real work to understand, one file each | main | ~/git/robertblust/field-notes |
| robertblust/mcp-blust-ch | mcp.blust.ch | mcp.blust.ch, the reference instance served over MCP from a pinned commit of the model | main | ~/git/robertblust/mcp-blust-ch |
| robertblust/mcp-blust-ch | mcp.blust.ch | mcp.blust.ch, the reference instance served over MCP from a pinned commit of the model, and the chat over it | main | ~/git/robertblust/mcp-blust-ch |
| robertblust/id-blust-ch | id.blust.ch | id.blust.ch, the identity service the three chats sign readers in at: ZITADEL on Cloud Run and what it holds | main | ~/git/robertblust/id-blust-ch |
| guestgraph/guestgraph.github.io | guestgraph.io | guestgraph.io, the landing page, the model pages drawn from GuestGraph's instance, the API and the intro talk | main | ~/git/guestgraph/guestgraph.github.io |
| guestgraph/engine | GuestGraph — Engine | identity resolution, guest graph and REST API, the open core | main | ~/git/guestgraph/engine |
Expand All @@ -22,8 +22,8 @@ Three organizations, one family. `robertblust` holds the person and the shared m
| companygraph/meta-model | CompanyGraph — Meta Model | the meta-model: core vocabulary, packs and the conventions that make a graph of Markdown checkable | main | ~/git/companygraph/meta-model |
| companygraph/mental-model | CompanyGraph — Mental Model | CompanyGraph described in the vocabulary it publishes, the second instance | main | ~/git/companygraph/mental-model |
| companygraph/mcp-server | CompanyGraph — MCP Server | a read-only MCP server for any instance: the model's facts, queryable by an agent from one pinned commit | main | ~/git/companygraph/mcp-server |
| companygraph/mcp-companygraph-io | mcp.companygraph.io | mcp.companygraph.io, CompanyGraph's own instance served over MCP from a pinned commit of the model | main | ~/git/companygraph/mcp-companygraph-io |
| companygraph/mcp-azure-companygraph-io | mcp.azure.companygraph.io | mcp.azure.companygraph.io, CompanyGraph's own instance served over MCP from a pinned commit of the model, on Azure: the first deployment of the server there | main | ~/git/companygraph/mcp-azure-companygraph-io |
| companygraph/mcp-companygraph-io | mcp.companygraph.io | mcp.companygraph.io, CompanyGraph's own instance served over MCP on Google Cloud from a pinned commit of the model, and the chat over it | main | ~/git/companygraph/mcp-companygraph-io |
| companygraph/mcp-azure-companygraph-io | mcp.azure.companygraph.io | mcp.azure.companygraph.io, CompanyGraph's own instance served over MCP on Azure from a pinned commit of the model, and the chat over it: the first deployment of both there | main | ~/git/companygraph/mcp-azure-companygraph-io |
| companygraph/chat-server | CompanyGraph — Chat Server | a chat over any instance's MCP host: a visitor's question answered from what the host's tools say, on a site's page, holding no model of its own | main | ~/git/companygraph/chat-server |
| companygraph/obsidian-plugin | CompanyGraph — Obsidian Plugin | an Obsidian plugin for any instance: the meta-model's checks while a file is edited, and completion for what its schemas declare | main | ~/git/companygraph/obsidian-plugin |
| companygraph/.github | CompanyGraph — Organization | the organization profile GitHub shows, and nothing else | main | ~/git/companygraph/.github |
Expand All @@ -34,7 +34,7 @@ What is listed here is the family; what is not listed is outside it. An agent wo

## What pins what

The three sites pin `robertblust/design` by tag in `package.json`, and `npm run design` writes the fenced copies. blust.ch pins `robertblust/mental-model`, companygraph.io pins `companygraph/meta-model` and `companygraph/mental-model`, and guestgraph.io pins `guestgraph/mental-model`, each by commit in `source.json`, and each builds its model pages from that commit. All three sites also depend on `companygraph/meta-model` by tag in `package.json` for the instance parser, and take `companygraph/mcp-server` by tag there too. guestgraph.io pins `guestgraph/engine` and `guestgraph/connector-apaleo` by commit in `api-sources.json`, and builds its API pages from the OpenAPI specification each commit holds. The three instances, `robertblust/mental-model`, `companygraph/mental-model` and `guestgraph/mental-model`, each vendor meta-model's `core/` at the release that `core.version` names in their own `.companygraph/manifest.json`. The engine and the connector each vendor `guestgraph/service-conventions` at the tag in `service-conventions.json`, and the connector pins the contracts it implements, which live under the engine's `specs/`, by commit in `src/main/resources/api/sources.json`. The MCP server depends on `companygraph/meta-model` by tag in `package.json` for the same parser; each of its four deployments pins an instance by commit in `source.json`, mcp.blust.ch `robertblust/mental-model`, mcp.companygraph.io and mcp.azure.companygraph.io `companygraph/mental-model` and mcp.guestgraph.io `guestgraph/mental-model`, and the server and `robertblust/design` by tag in `package.json`, and builds and deploys with the parts the server ships under `deploy/`. The chat server takes `companygraph/mcp-server` by tag in `package.json` as a development dependency and is a client of whichever MCP host a deployment names, and three of them, mcp.blust.ch, mcp.companygraph.io and mcp.guestgraph.io, pin it and `robertblust/design` by tag in `chat/package.json` and deploys it beside the host from the parts it ships under `deploy/`, so a re-pin of the host is a change the chat sees without one of its own. The identity service, `robertblust/id-blust-ch`, pins no member: it takes ZITADEL by image tag in `infra/run.tf`, and each of the three deployments with a chat names it in `chat/chat.json` as the issuer its chat verifies a signed-in reader against, a dependency at run time and not a pin. The Obsidian plugin depends on `companygraph/meta-model` by tag in `package.json` for the parser and the checks, and bundles them into what it releases. Every member pins this repository by tag in `conventions.json`.
The three sites pin `robertblust/design` by tag in `package.json`, and `npm run design` writes the fenced copies. blust.ch pins `robertblust/mental-model`, companygraph.io pins `companygraph/meta-model` and `companygraph/mental-model`, and guestgraph.io pins `guestgraph/mental-model`, each by commit in `source.json`, and each builds its model pages from that commit. All three sites also depend on `companygraph/meta-model` by tag in `package.json` for the instance parser, and take `companygraph/mcp-server` by tag there too. guestgraph.io pins `guestgraph/engine` and `guestgraph/connector-apaleo` by commit in `api-sources.json`, and builds its API pages from the OpenAPI specification each commit holds. The three instances, `robertblust/mental-model`, `companygraph/mental-model` and `guestgraph/mental-model`, each vendor meta-model's `core/` at the release that `core.version` names in their own `.companygraph/manifest.json`. The engine and the connector each vendor `guestgraph/service-conventions` at the tag in `service-conventions.json`, and the connector pins the contracts it implements, which live under the engine's `specs/`, by commit in `src/main/resources/api/sources.json`. The MCP server depends on `companygraph/meta-model` by tag in `package.json` for the same parser; each of its four deployments pins an instance by commit in `source.json`, mcp.blust.ch `robertblust/mental-model`, mcp.companygraph.io and mcp.azure.companygraph.io `companygraph/mental-model` and mcp.guestgraph.io `guestgraph/mental-model`, and the server and `robertblust/design` by tag in `package.json`, and builds and deploys with the parts the server ships under `deploy/`. The chat server takes `companygraph/mcp-server` by tag in `package.json` as a development dependency and is a client of whichever MCP host a deployment names, and each of the four deployments pins it and `robertblust/design` by tag in `chat/package.json` and deploys it beside the host from the parts it ships under `deploy/`, so a re-pin of the host is a change the chat sees without one of its own. The identity service, `robertblust/id-blust-ch`, pins no member: it takes ZITADEL by image tag in `infra/run.tf`, and the three deployments on Google name it in `chat/chat.json` as the issuer its chat verifies a signed-in reader against, a dependency at run time and not a pin. The Obsidian plugin depends on `companygraph/meta-model` by tag in `package.json` for the parser and the checks, and bundles them into what it releases. Every member pins this repository by tag in `conventions.json`.

The same pins, drawn: an arrow runs from the member that pins to the repository it pins, and its label says how. Each node is named as its repository is, under its organization.

Expand Down Expand Up @@ -80,7 +80,7 @@ flowchart TB
engine & connector -->|tag| svc
connector -->|commit| engine
mcpblust & mcpcg & mcpgg -->|tag| mcpsrv & chat
mcpaz -->|tag| mcpsrv
mcpaz -->|tag| mcpsrv & chat
mcpblust -->|commit| rbmm
mcpcg & mcpaz -->|commit| cgmm
mcpgg -->|commit| ggmm
Expand Down
8 changes: 4 additions & 4 deletions conventions/manifest.json
Original file line number Diff line number Diff line change
@@ -1,18 +1,18 @@
{
"repo": "robertblust/conventions",
"tag": "v1.53.0",
"tag": "v1.55.0",
"files": {
"conventions/WRITING.md": "sha256:51d9a902ec3038392160df07f86aba98d34db1d4dbfaa5f4a647590eaccfb390",
"conventions/WORKING.md": "sha256:3a7a6b4ab1bd23f2407fc6ada2dd0512710a49d233fa7c3342951f6fc526ab23",
"conventions/REPOSITORIES.md": "sha256:a47784200b049713b8cbf7ba6d0ff77e3634fe425a3800bc186f6867c5f83bd5",
"conventions/REPOSITORIES.md": "sha256:75ffac1aaf2523ba7d8fcd1175d6a63b7a42516883ef4a7af5dde52c564bee85",
"conventions/PINS.md": "sha256:68df67ae820a8673d3130582aa829d4283176d3c8ec0a69adda3132a1a755b93",
"conventions/WRITER.md": "sha256:bc3b92683130b75993f824f0e34073d4344846c91be2009fd90c39099fd4fd48",
"conventions/TRANSLATOR.md": "sha256:3a3d2d0916d7230cbc760bced1be249b11cc516956fb41ad010b3216f23024ba",
"conventions/GLOSSARY.md": "sha256:f29b2a31e171f9666e70e3c0ab3290876fcd90846f99c86a12a6ac56c16acdf1",
"conventions/GLOSSARY.md": "sha256:a9cce07a55a12dd86bb9a3f39c4841e2927e99d687ad4c14c083a26b3d0f8dc1",
"conventions/GERMAN.md": "sha256:6a0ab79fd52f93d1361aceb83a1771ce6448124d5ea707af3d71baf9efe35e11",
"conventions/EDITOR.md": "sha256:e65d0b2893ac841faefede9b873f7e33c1fd7b02bedf97d37d5362c0e83c08ea",
"conventions/BACKREADER.md": "sha256:36b12d4bee8e4fe190469e2f550d50d8a7f6dcab6bec573da17eb1c165c417cd",
"conventions/AGENTS.md": "sha256:363921dd5a6da62f1db28e7110ce552df39cbc7c6aadf5141c93adc465ee4885",
"conventions/AGENTS.md": "sha256:5e7731a873120c47d6b6b711d100b915bcc61ae4a71864ac522d563b94888dc4",
"conventions/conventions-sync": "sha256:a190ff79c2d8d3f6f6d9a597e9f261654f2419d30e2ac43abf6c64ebe2c47ed9",
"conventions/conventions-check": "sha256:4a633cc53579f4577939702350c439bbb58ebed4ccbf6736d94c01e5fc160147",
"conventions/conventions-format": "sha256:2911a0d30dda1bc0f621522a9538b3e39704eee03458e65ba320eccbf39b5c7f",
Expand Down
Loading