An open pattern

Knowledge as Code

By , PAICE.work PBC · Published · Updated · v1.0 · CC BY 4.0

Build evidence-backed reference sites for people and agents from Git-tracked Markdown. One typed source produces searchable HTML, a JSON API, discovery files, and an optional local MCP interface, with deterministic checks that flag stale or incomplete knowledge.

Get started View on GitHub → See it in production →

What it is

This implementation combines six established practices into a small, durable reference generator.

1 Plain-text canonical

Human-readable, version-controlled files. No database. No vendor lock-in. What you commit is the source of truth.

2 Drift-aware

Deterministic checks flag old review dates and incomplete relationships so maintainers know what needs human review.

3 Multi-output

One source compiles to HTML, JSON APIs, discovery files, and SEO pages. A separate local MCP runtime reads the same source.

4 Zero-dependency

The core builds with Node.js built-ins only. There is no package-install step or transitive runtime dependency tree to maintain.

5 Git-native

Git is the collaboration layer, the audit trail, and the deployment trigger. No additional CMS or workflow tool required.

6 Ontology-driven

Vendor-neutral taxonomies map to specific implementations. Swap the data; the structure — and the consumers — keep working.

Why it matters

Structured references often repeat the same claims across a website, API, search index, and agent interface. Knowledge-as-Code keeps those outputs connected to one typed source and reports stale review dates or incomplete relationships before maintainers publish again.

For devtool builders & DevRel

Capability matrices, plan comparisons, compatibility tables, and changelogs share one review queue. Deterministic checks flag stale dates and broken relationships before the same structured data reaches the site, API, and agents.

For AI & agent builders

Agents need queryable, well-typed, citation-friendly knowledge. A KaC project emits a JSON API alongside its HTML and includes a separate read-only MCP runtime over the same source.

For open-source maintainers

No platform to outlive your project. No service to pay for. A KaC knowledge base is a normal repo: forkable, archivable, auditable, and durable long after whichever hosting vendor you picked pivots or shuts down.

A reference implementation

AITool.watch is a maintained registry of AI capabilities, implementations, and products — built entirely on the Knowledge as Code pattern. It tracks 18 capabilities across 66 implementations spanning ChatGPT, Claude, Gemini, Copilot, Grok, and Perplexity.

Live example

aitool.watch

Capability-first taxonomy. Each entry carries "What counts" and "what doesn't count" boundaries, plan-tier requirements, and launch dates. The site, JSON API, and MCP server all regenerate from a folder of markdown files every time someone merges a PR.

Browse the live site →

It sits alongside sibling specs like Graceful Boundaries (machine-readable error responses) and Skill Provenance (portable version identity for agent skills) — all open patterns in the same family.

See the pattern in action

Most people don't understand Knowledge as Code until they see both halves at once — the built site a visitor experiences, and the plain markdown files a contributor edits. The trick is that they live at the same URL.

/demo/ The built site

A complete Knowledge as Code site generated from the example data in this very repo. Homepage, entity detail pages, a coverage matrix, a comparison tool, a JSON API, an RSS feed, and an MCP server — all from 7 markdown files.

Open the live demo →

.md The source markdown

This is what a contributor writes. YAML frontmatter for metadata, Markdown prose for the body. Git diffs are human-readable. No database, no CMS, no migrations.

Click a markdown file above, then open the matching page in the demo. The left-hand column is the input. The right-hand column is the output. Everything in between is a single node scripts/build.js command.

Maintainer-operated implementations

Three production reference sites maintained by the same teams that maintain this generator. They prove internal utility and provide worked examples; they are not presented as independent adoption.

aitool.watch

A plain-English reference for AI capabilities, plans, constraints, and implementations across ChatGPT, Claude, Gemini, Copilot, Grok, and Perplexity.

everyailaw.com

A global reference to AI regulation, obligations, and compliance deadlines for GRC, CISO, CAIO, and legal teams.

 22 meeting tools 9 facilitation primitives

VirtualClassroom.watch

Virtual classroom and meeting software mapped to facilitation primitives, with timeline and compatibility matrix.

Get started

Clone the generator once, then run its zero-dependency initializer to create a clean project containing only the engine, worked example, MCP runtime, and deployment workflows. 

# 1. Clone the generator
git clone https://github.com/snapsynapse/knowledge-as-code-template.git
cd knowledge-as-code-template

# 2. Create a clean, guided project
node scripts/init.js ../my-knowledge-base
cd ../my-knowledge-base

# 3. Build the site + JSON API (no npm install required)
node scripts/build.js

# 4. Validate cross-references any time
node scripts/validate.js
  • 01
    Define your ontology. Edit project.yml to describe the entities your domain cares about — primary anchors, containers, authorities, and mappings.
  • 02
    Add data as markdown. Drop one file per entity into data/examples/ with YAML frontmatter. Cross-references resolve by id.
  • 03
    Build and publish. node scripts/build.js emits static HTML, JSON, and discovery files under docs/. Enable GitHub Pages with GitHub Actions, then push to main.
  • 04
    Review reported drift. The included verifier flags old review dates and incomplete mappings. Maintainers still check the underlying evidence before updating verification dates.
  • 05
    (Optional) Publish as an MCP server. Make your knowledge base installable as npx -y your-package for any MCP-aware agent client. PUBLISH-MCP.md walks through the package.json prep, npm publish, and Official MCP Registry submission — with the gotchas captured from three real PAICE legal graph publishes.
Get the generator Read the full write-up → Assistant guide →