Knowledge-as-Code Template

A template for building structured, version-controlled knowledge bases with an ontology-first approach. Edit a config file, add markdown data, get a full HTML site + JSON API.

Knowledge as Code is a pattern created for PAICE.work PBC. It applies software engineering practices to knowledge management: plain text, Git-native, zero-dependency, ontology-driven, multi-output from a single source.

Live Examples

• AI Tool Watch — AI model capabilities across 12 products
• Every AI Law — global AI regulatory landscape
• Meeting Standards Reference — meeting facilitation standards

Quick Start

1. Use this template -- click "Use this template" on GitHub, or clone locally
2. Edit project.yml -- define your domain entities, groups, colors, and site identity
3. Replace example data -- see Replacing example data below
4. Build -- node scripts/build.js (or npm run build)
5. Deploy -- push to GitHub, Pages deploys automatically

What You Get

• Static HTML site — homepage, list pages, detail pages, coverage matrix, timeline, comparison tool
• JSON API — programmatic access at docs/api/v1/
• Bridge pages — SEO-targeted pages like "Does X require Y?"
• Dark/light theme — with persistence
• Client-side search — lazy-loaded, keyboard-navigable
• Sortable tables — click any column header to sort
• MCP server — AI agent access to your knowledge base
• Discovery files — llms.txt, agents.json, RSS for machine consumption
• Zero dependencies — Node.js built-ins only

Project Structure

project.yml          # Domain configuration (edit this first)
data/
  examples/          # Example data (replace with your own)
    primary/         # Stable anchor entities (e.g., requirements, obligations)
    container/       # Grouping entities (e.g., frameworks, regulations)
    authority/       # Source entities (e.g., organizations, regulators)
    mapping/         # index.yml connecting containers to primaries
scripts/
  build.js           # Config-driven site generator
  validate.js        # Cross-reference validator
docs/                # Generated output (do not edit)

The Ontology

Every knowledge-as-code project has four entity roles:

Authority → Container → Provision → Primary

Role	What it is	Example domains
Primary	Stable anchors that don't change when sources change	Requirements, Obligations, Capabilities, Controls
Container	Grouping entities that contain provisions	Regulations, Frameworks, Products, Standards
Authority	Source entities that produce containers	Regulators, Vendors, Standards bodies
Secondary	Mapping entities connecting containers to primaries	Provisions, Implementations, Mappings

Primaries are stable; containers are unstable. When a framework is amended, its provisions change, but the underlying requirements persist.

Configuration

All domain-specific settings live in project.yml:

• Entity names — what to call each entity type (e.g., "Requirement" vs "Obligation")
• Groups — categories for primary entities, with dark/light mode colors
• Statuses — lifecycle states for containers, with colors
• Navigation — site nav items
• Bridge pages — which SEO pages to generate
• Theme — accent colors

Replacing example data

The template ships with example data in data/examples/ (ISO 27001, NIST CSF). To replace it with your own domain:

1. Update project.yml -- rename entity types, groups, statuses, and colors to match your domain. The directory names under entities.*.directory control where the build script looks for files.

2. Delete example files -- remove the contents of data/examples/requirements/, data/examples/frameworks/, data/examples/organizations/, and data/examples/mapping/index.yml.

3. Create your data files -- add markdown files following the format documented in data/_schema.md. Each entity type has specific frontmatter requirements and body structure.

4. Update the mapping file -- create entries in data/examples/mapping/index.yml that connect your containers to your primaries.

5. Validate and build:

   node scripts/validate.js   # Check cross-references
   node scripts/build.js      # Generate the site

The build script looks for data in data/examples/ first, then data/. You can rename data/examples/ to data/ if you prefer a flatter structure.

Commands

node scripts/build.js      # Build the site (or: npm run build)
node scripts/validate.js   # Validate cross-references (or: npm run validate)
node scripts/verify.js     # Check entity freshness (or: npm run verify)

Architecture

• File-over-App — data in markdown files, not a database
• Zero dependencies — no npm install, no supply chain risk
• Bespoke static generation — the build script is the specification
• GitOps — Git is the single source of truth

AI Agent Support

Every Knowledge-as-Code site includes machine-readable discovery files:

• MCP Server -- mcp-server.js provides read-only access to all entities via Model Context Protocol
• llms.txt -- Generated at docs/llms.txt with entity model, API endpoints, and entity listings
• agents.json -- Machine-readable metadata at docs/agents.json for agent discovery
• RSS feed -- Recent updates at docs/index.xml
• JSON API -- Programmatic access at docs/api/v1/

Using the MCP server

The MCP server exposes your knowledge base as tools that AI agents can call. Tool names are dynamically generated from your project.yml entity configuration.

Add to Claude Code (or any MCP-compatible client) via mcp.json:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "node",
      "args": ["mcp-server.js"],
      "description": "Read-only access to the knowledge base"
    }
  }
}

Test it directly:

node mcp-server.js

The server reads project.yml at startup and exposes tools for listing and retrieving each entity type. For example, with the default config you get tools like list_requirements, get_requirement, list_frameworks, get_framework, etc. The exact tool names depend on your entity configuration.

Verification

Knowledge as Code includes a verification scaffold for detecting stale data:

• Add last_verified: YYYY-MM-DD to entity frontmatter
• Run node scripts/verify.js to check for staleness
• Configure threshold in project.yml under verification.staleness_days
• See VERIFICATION.md for details on adding AI-assisted verification

Ecosystem

Knowledge as Code is part of a broader set of open standards:

• Graceful Boundaries — How services communicate operational limits to humans and agents
• Skill Provenance — Version identity that travels with agent skill bundles
• Siteline — AI agent readiness scanner for websites
• Knowledge as Code — The pattern definition and community hub

The Pattern

Knowledge as Code has six defining properties:

1. Plain text canonical — knowledge in human-readable, version-controlled files
2. Self-healing — automated verification detects when knowledge drifts from reality
3. Multi-output — one source produces every format needed (HTML, JSON API, MCP, SEO pages)
4. Zero-dependency — no external packages; nothing breaks when you come back in a year
5. Git-native — Git is the collaboration layer, audit trail, and deployment trigger
6. Ontology-driven — a vendor-neutral taxonomy maps to domain-specific implementations

Read the full pattern definition at knowledge-as-code.com.

Attribution

Knowledge as Code is a PAICE.work project. See ATTRIBUTION.md for details.

Deploying

When you use this template, update the following:

1. Edit project.yml with your domain entities, colors, and site identity
2. Replace example data in data/examples/ with your own
3. Update docs/CNAME with your custom domain (or remove it)
4. Push to GitHub — Pages deploys automatically via the included workflow

About

Knowledge as Code is a PAICE.work project. PAICE.work PBC is a public benefit corporation building infrastructure for productive collaboration between humans and autonomous agents. Structured, version-controlled, agent-accessible knowledge is a foundation for that collaboration.

License

MIT