companygraph.io
The site for CompanyGraph — an open-source meta-model for operating a company: the structure its knowledge takes, as a graph of Markdown files, so people and agents can both rely on it.
Live: https://companygraph.io
One repository serves the whole domain. It was two — the talks had their own — and the split cost more than it saved: the talks index copies this site's shell, header and footer, so every nav change had to land in both repositories in the same breath, with no CI on either side able to see the seam. They were merged, history and all, in August 2026.
| Path | |
|---|
/ | The landing page: what CompanyGraph is, and CompanyGraph's own model, drawn on the stage. |
/talks/ | The talks index. |
/talks/intro/ | The introduction — English and German, narrated, with a PDF in each language. |
/talks/obsidian-plugin/ | CompanyGraph explains its own Obsidian plugin, pane by pane, with an animated window beside each feature — English and German, narrated, with a PDF in each language. |
/talks/levels/ | CompanyGraph — From one command to fully integrated: the five levels a company's model can reach, from one command to a model the site, the server and the editor all read — English and German, narrated, with a PDF in each language. |
/talks/what-stays/ | CompanyGraph — What stays when the model changes: code, a System One model, a System Two model and a person, which of the five things called a model are fixed and which are replaceable, six practices and the credits — English and German, narrated, with a PDF in each language. |
/talks/core-and-packs/ | CompanyGraph — One core, and the words your company adds: what core gives every company, what a pack adds and which to take, and where a company's own words go — English and German, narrated, with a PDF in each language. |
/talks/software-pack/ | CompanyGraph — Domain-driven design, as pages you can check: a bounded context, its language, an aggregate, an event, the context map and a feature design as pages, where the pack departs from its sources and how it joins core — English and German, narrated, with a PDF in each language. |
/talks/organization-pack/ | CompanyGraph — Two lines through one company: a group and its kind, a job beside a seat, the disciplinary and the professional line, a team across units, staff, order, openings and who directs an agent as pages, resting on our model and the example company — English and German, narrated, with a PDF in each language. |
/talks/landscape-pack/ | CompanyGraph — Your landscape, in ArchiMate’s words: a system and its kind, what it connects to and holds, and the services it exposes as pages, mapped to ArchiMate 4 in both directions, where the pack departs and how it joins core — English and German, narrated, with a PDF in each language. |
/talks/requirements-pack/ | CompanyGraph — What someone wants, and what a product is held to: a use case with its stakeholders, guarantees, scenario and extensions, a requirement with its kind, modality and fit criterion, the rule it carries in, where the pack departs, how it joins core, and the three pictures the MCP server draws of a use case — English and German, narrated, with a PDF in each language. |
/cli/ | The command line: one command opens a menu that makes a model, checks it, moves it to a newer release and installs the Obsidian plugin, and each entry is also a subcommand. First in the nav, by the owner's decision. |
/processes/ | CompanyGraph's processes and the seats they name: one board per process, generated from company.json by the design package's render/processes, each opening on the process's owner. |
/principles/ | CompanyGraph's vision and values, generated from its own model, company.json, by the design package's render/principles. |
/surfaces/ | Where CompanyGraph's model is published and what makes each place, generated from company.json by the design package's render/surfaces. |
/model/ | The model's own vocabulary, drawn as the graph of what references what — one schema per type. |
/example/ | One instance of the model, drawn as the graph its own files form — generated, never written by hand. |
/billing/ | What would cost money, if anything ever does. |
/privacy/ | What this site collects, which is nothing. |
The repository is named companygraph.github.io because that makes it the organization's GitHub Pages site, which is what puts it on the custom domain in CNAME. Renaming it or removing CNAME takes the whole domain down, talks included.
A repository named talks in this organization would claim companygraph.io/talks/ the moment its Pages were enabled — shadowing the folder in this repository, which is how the old split had to be unwound. Do not recreate one.
Contents
index.html, cli/, billing/, privacy/ — the prose pages, each its own markup and prose,
linking tokens.css, page.css and page.js for the chrome and tokens they share with every
other page in the family. The landing page also carries a stage, described with the stage
pages below, and a vision and values region build/pages.mjs writes from company.json with
@robertblust/design/render/home.talks/index.html — the talks index, carrying this site's chrome so a visitor crossing into
it meets no seam.talks/intro/ — the deck: index.html, linking tokens.css and deck.css and loading
deck.js the same way a prose page loads its three, audio/{en,de}/ — one narrated clip per
slide and language — both PDFs, and tts/generate.py, which reads the deck's speaker notes as
the single source for what is spoken. Its share card is rendered by the root export-og.mjs,
with the other three. Nothing here requires the deck to open from file:// any more — it is
normally read served, like every other page — though it still does, checked rather than
assumed.talks/obsidian-plugin/ — the second deck, built the same way, plus scenes.js: the
animated Obsidian windows beside each feature, drawn in the site's tokens. A scene runs while
its slide is shown and paints one still frame under reduced motion and in a browser driven by
a script, which is what the PDFs, the share card and the verify suite see.talks/levels/ — the third deck, built the same way, with a scenes.js that animates its
terminal and server windows and the ladder slide 08 climbs, under the same still-frame rule.talks/what-stays/ — the fourth deck, built from the third, with a scenes.js that types its
two terminals and lights the flow on slide 09, under the same still-frame rule.talks/core-and-packs/ — the fifth deck, built from the fourth, with a scenes.js that types slide 07's terminal, under the same still-frame rule.talks/software-pack/ — the sixth deck, built from the fifth, with a scenes.js that types slide 09's terminal and steps slide 11's tabs through the pictures the MCP server draws, under the same still-frame rule.talks/organization-pack/ — the seventh deck, built from the sixth, with a scenes.js that steps slide 12's tabs through the pictures the MCP server draws, under the same still-frame rule; its chips open the example company where our model has nothing to show.
The mark
An outlined square holding a filled one, with a line out to a second filled square: the model's two kinds of edge, drawn once. Containment — an entity that owns collections is a folder holding its own file — is the outlined square around the filled one. Reference — by canonical name, to something nothing owns — is the line out to the square beside it. Nothing else is in the glyph; a mark that needs a third element to make its point is not this one.
logo.svg and favicon.svg are the mark at the two sizes it has to survive.
Running it
No build step.
npm install # once, for Playwright
npm run serve # → http://localhost:8000
npm run verify # renders every page and asserts the DOM
npm run og:check # do the share cards still show their pages?
npm run test:og # the card check's own tests (node --test, no deps)
npm run og # re-renders every share card after a visual change
npm run build # writes example.json, model.json and company.json from their pins
npm run build:check # fails if any artifact has drifted from its pin's commit
npm run pages # renders each page's JSON-LD graph from its artifact
npm run pages:check # fails if any graph has drifted from its artifact
npm run sitemap # date each sitemap URL from its page's last commit — run before committing a page
npm run sitemap:check # are those dates still what git says?
npm run pdf # both language PDFs
example.json and model.json are committed files, and moving the pin means npm run build then npm run pages.
og:check needs no server and no browser — it re-derives each card's recipe and compares it with the og.sha committed beside it, which is why CI runs it before npm ci. npm run og does need one: the shared exporter in @robertblust/design serves this repository's root on a free port and renders every card, the deck's included, from that address, because a stage page's card has to fetch its data the same way a visitor's browser would. Commit each og.png with its og.sha, in the commit that moved the page.
verify needs a server already running in another terminal. It also runs against the live site — BASE=https://companygraph.io npm run verify — which is worth doing after a deploy, and is how a bug was once found that could not appear locally: a check rewrote the share card's URL onto location.origin, which is only correct when the repository is the root of its host.
Most checks read the page as it first renders, which is English. translates is the one that clicks: it presses DE, requires the German to be there and the English to be gone, then presses EN and requires the page to come back exactly as it was. It runs last among the shared checks because it is the only one that changes what the others read. It was written here and now lives in @robertblust/design with the other shared checks, so blust.ch and guestgraph.io run the same code; what stays here is each page's spec.
It was written by breaking the page three ways and watching it catch each: the toggle's click listener deleted, an <h1>'s data-de misspelled, and applyLang stopped from setting document.documentElement.lang. Before it existed, all three printed all checks pass.
sameOrigin guards the privacy page's central claim — that nothing is fetched from anywhere else. A font link or an analytics tag is a request, not markup, so no other check here can see one.
What this site deliberately does not say
No type count and no type list — those live in companygraph/meta-model, which ships them in the same commit as the thing they describe. No status and no roadmap — those are on the organization profile, where meta-model itself points for them. A pack is named only once it has shipped, and then only as what exists; software has. Nothing identifying the companies the model was extracted from.
/billing/ is the one place a commercial model is stated, and it states one that is not running: consulting, time and material, no rate, nobody to ask, and it may never happen at all. The absent contact is deliberate — adding one turns a described model into an offer. Nothing anywhere may imply a hosted product, a license fee, a seat count or a paid edition of the model; those are the four things the billing page rejects by name.
See AGENTS.md for why each of those constraints exists, and what has already gone wrong when a page like this one didn't hold them.
License
CC BY 4.0 for everything written here: the pages, the talks and their narration, the share cards, and the scripts that build and check them. Use it, quote it, build on it; credit it. Four kinds of file are not written here and keep their own licenses, each in a text beside it: the faces under fonts/, d3.v7.min.js, mermaid.min.js and the GitHub mark inlined in chat.js come from @robertblust/design, whose NOTICE names each one. The license grants no right to a name or a mark: CompanyGraph and its mark stay the project's.
