Complete template for public sharing

snapsynapse · claude · snapsynapse · commit a1aef7ae581a · 2026-04-03T19:41:58.000-05:00
Documentation:
- New data/_schema.md: full file format reference for all entity types,
  covering frontmatter fields, body structure, provision parsing format,
  and mapping file syntax
- README: added data replacement guide, expanded MCP server docs, updated
  Quick Start to reference schema and npm scripts
- CLAUDE.md: updated commands to use npm scripts, added schema reference

Fixes:
- project.yml: mapping.file path corrected from "provisions/index.yml"
  to "mapping/index.yml" (was relying on undocumented fallback)
- Added last_verified dates to all example entities (eliminates
  "NEVER VERIFIED" warnings on fresh clone)

New:
- package.json with build/validate/verify scripts and Node &gt;=16 engine

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -22,8 +22,9 @@ docs/                 # Generated output (HTML + JSON API)
 ## Key Commands
 
 ```bash
-node scripts/build.js      # Build site + JSON API
-node scripts/validate.js   # Validate cross-references
+npm run build       # Build site + JSON API (or: node scripts/build.js)
+npm run validate    # Validate cross-references
+npm run verify      # Check entity freshness / staleness
 ```
 
 ## Entity Model
@@ -41,12 +42,14 @@ Relationship: Authority → Container → Secondary → Primary
 
 ## Adding Data
 
-1. Create a `.md` file in the appropriate `data/` directory
-2. Add YAML frontmatter with required fields (see existing files for format)
+See `data/_schema.md` for the full file format reference.
+
+1. Create a `.md` file in the appropriate `data/examples/` directory
+2. Add YAML frontmatter with required fields per the schema
 3. For containers: add timeline table and provision sections separated by `---`
 4. Add mapping entries to `data/examples/mapping/index.yml`
-5. Run `node scripts/validate.js` to check cross-references
-6. Run `node scripts/build.js` to generate the site
+5. Run `npm run validate` to check cross-references
+6. Run `npm run build` to generate the site
 
 ## Customization
 
diff --git a/README.md b/README.md
@@ -12,11 +12,11 @@ A template for building structured, version-controlled knowledge bases with an o
 
 ## 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. **Add data** — create markdown files in `data/` following the schema in `data/_schema.md`
-4. **Build** — `node scripts/build.js`
-5. **Deploy** — push to GitHub, Pages deploys automatically
+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](#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
 
@@ -74,11 +74,32 @@ All domain-specific settings live in `project.yml`:
 - **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`](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:**
+   ```bash
+   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
 
 ```bash
-node scripts/build.js      # Build the site
-node scripts/validate.js   # Validate cross-references
+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
@@ -92,11 +113,37 @@ node scripts/validate.js   # Validate cross-references
 
 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. Tools are dynamically named from your `project.yml` config. Run with `node mcp-server.js` or add to your MCP client config via `mcp.json`.
-- **llms.txt** — Generated at `docs/llms.txt` with entity model, API endpoints, and entity listings for LLM context
-- **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/`
+- **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`:
+
+```json
+{
+  "mcpServers": {
+    "knowledge-base": {
+      "command": "node",
+      "args": ["mcp-server.js"],
+      "description": "Read-only access to the knowledge base"
+    }
+  }
+}
+```
+
+**Test it directly:**
+
+```bash
+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
 
diff --git a/data/_schema.md b/data/_schema.md
@@ -0,0 +1,171 @@
+# Data Schema
+
+This file documents the file format for each entity type. All data files use YAML frontmatter followed by a markdown body.
+
+## Primary entities
+
+**Directory:** `data/examples/{primary.directory}/` (configured in `project.yml` as `entities.primary.directory`)
+
+**Example:** `requirements/access-control.md`
+
+```yaml
+---
+id: access-control              # Required. Kebab-case identifier, must match filename
+name: Access Control            # Required. Human-readable name
+group: governance               # Required. Must match a group name in project.yml
+status: active                  # Optional. Lifecycle state
+last_verified: 2026-03-25       # Optional. Date of last verification check
+search_terms:                   # Optional. Additional search keywords
+  - authorization
+  - permissions
+---
+```
+
+**Body sections:** Defined in `project.yml` under `entities.primary.body_sections`. Each section is an `## H2` heading followed by markdown content. For the example config:
+
+```markdown
+## Summary
+
+One paragraph describing the requirement.
+
+## What Counts
+
+- Concrete examples that satisfy this requirement
+
+## What Does Not Count
+
+- Anti-patterns or things that look similar but don't qualify
+```
+
+## Container entities
+
+**Directory:** `data/examples/{container.directory}/`
+
+**Example:** `frameworks/iso-27001.md`
+
+```yaml
+---
+name: ISO 27001                   # Required. Human-readable name
+authority: iso                    # Required. ID of the authority entity
+jurisdiction: International       # Required if scope_field is set in project.yml
+type: standard                    # Optional. Category label
+status: active                   # Required. Must match a status in project.yml
+enacted: 2022-10-25              # Optional. Date of enactment
+effective: 2022-10-25            # Optional. Date it took effect
+official_url: https://...        # Optional. Link to official source
+last_verified: 2026-03-25        # Optional. Date of last verification check
+---
+```
+
+**Body structure:** Container files have a specific structure that the build script parses. The body has two parts separated by `---`:
+
+1. **Timeline table** (optional, when `has_timeline: true` in config)
+2. **Provision sections** (one or more, separated by `---`)
+
+```markdown
+## Timeline
+
+| Milestone | Date | Notes |
+|-----------|------|-------|
+| Published | 2022-10-25 | Initial release |
+| Amendment | 2024-01-15 | Updated controls |
+
+---
+
+## Provision Title
+
+| Property | Value |
+|----------|-------|
+| Obligation | access-control |
+| Sections | Annex A.5-A.8 |
+| Status | active |
+| Effective | 2022-10-25 |
+| Verified | 2026-03-25 |
+| Checked | 2026-03-25 |
+
+### Requirements
+
+| Requirement | Details |
+|-------------|---------|
+| Access control policy | Define and enforce access control rules |
+
+### Talking Point
+
+> "A single quoted sentence for use in summaries or presentations."
+
+### Sources
+
+- [Source Name](https://source-url.com)
+
+---
+
+## Another Provision Title
+
+(same structure as above)
+```
+
+**Important format requirements:**
+
+- The `| Property | Value |` table is required for each provision. The `Obligation` row links this provision to a primary entity by ID.
+- Provision sections are separated by `---` (horizontal rule).
+- The `### Requirements` table is optional but recommended.
+- The `### Talking Point` must be a blockquote with the text in double quotes.
+- The `### Sources` section uses markdown link syntax.
+
+## Authority entities
+
+**Directory:** `data/examples/{authority.directory}/`
+
+**Example:** `organizations/iso.md`
+
+```yaml
+---
+id: iso                                           # Required. Kebab-case identifier
+name: International Organization for Standardization  # Required. Full name
+jurisdiction: International                       # Optional. Geographic scope
+website: https://www.iso.org                      # Optional. Official website
+last_verified: 2026-03-25                         # Optional. Verification date
+---
+```
+
+**Body:** A list of container IDs that this authority produces:
+
+```markdown
+## Regulations
+
+- iso-27001
+- iso-42001
+```
+
+The heading name should match your container entity's plural name (e.g., "Regulations", "Products", "Frameworks").
+
+## Mapping file
+
+**Path:** `data/examples/mapping/index.yml` (configured in `project.yml` as `mapping.file`)
+
+The mapping file connects containers to primaries through secondary (provision) entities:
+
+```yaml
+- id: iso-27001-access-control        # Unique provision ID
+  regulation: iso-27001               # Container file name (without .md)
+  authority: iso                      # Authority ID
+  source_heading: Information Security Controls (Annex A)  # Must match an ## H2 in the container file
+  obligations:                        # List of primary entity IDs this provision maps to
+    - access-control
+```
+
+The `regulation` field should use your container entity name from config (the field name comes from `project.yml`). The `obligations` field should use your primary entity name from config.
+
+## File naming
+
+- All files use kebab-case: `access-control.md`, `iso-27001.md`
+- The filename (without `.md`) is used as the entity ID for primaries and authorities
+- Container files use the `name` frontmatter field (lowercased, spaces replaced with hyphens) as their ID
+
+## Adding new entities
+
+1. Create the `.md` file in the appropriate directory
+2. Add YAML frontmatter with required fields
+3. If adding a container, create corresponding mapping entries in `mapping/index.yml`
+4. Run `node scripts/validate.js` to check cross-references
+5. Run `node scripts/build.js` to generate the site
diff --git a/data/examples/organizations/iso.md b/data/examples/organizations/iso.md
@@ -3,6 +3,7 @@ id: iso
 name: International Organization for Standardization
 jurisdiction: International
 website: https://www.iso.org
+last_verified: 2026-03-25
 ---
 
 ## Regulations
diff --git a/data/examples/organizations/nist.md b/data/examples/organizations/nist.md
@@ -3,6 +3,7 @@ id: nist
 name: National Institute of Standards and Technology
 jurisdiction: Federal
 website: https://www.nist.gov
+last_verified: 2026-03-25
 ---
 
 ## Regulations
diff --git a/data/examples/requirements/access-control.md b/data/examples/requirements/access-control.md
@@ -3,6 +3,7 @@ id: access-control
 name: Access Control
 group: governance
 status: active
+last_verified: 2026-03-25
 search_terms:
   - authorization
   - permissions
diff --git a/data/examples/requirements/data-quality.md b/data/examples/requirements/data-quality.md
@@ -3,6 +3,7 @@ id: data-quality
 name: Data Quality
 group: technical
 status: active
+last_verified: 2026-03-25
 search_terms:
   - data validation
   - data integrity
diff --git a/data/examples/requirements/incident-response.md b/data/examples/requirements/incident-response.md
@@ -3,6 +3,7 @@ id: incident-response
 name: Incident Response
 group: operational
 status: active
+last_verified: 2026-03-25
 search_terms:
   - incident management
   - breach response
diff --git a/package.json b/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "knowledge-as-code-template",
+  "version": "1.0.0",
+  "description": "Template for building structured, version-controlled knowledge bases with an ontology-first approach.",
+  "license": "MIT",
+  "scripts": {
+    "build": "node scripts/build.js",
+    "validate": "node scripts/validate.js",
+    "verify": "node scripts/verify.js"
+  },
+  "author": "PAICE.work PBC <https://paice.work/>",
+  "homepage": "https://github.com/snapsynapse/knowledge-as-code-template",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snapsynapse/knowledge-as-code-template"
+  },
+  "keywords": [
+    "knowledge-base",
+    "ontology",
+    "static-site",
+    "zero-dependency",
+    "knowledge-as-code",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}
diff --git a/project.yml b/project.yml
@@ -71,7 +71,7 @@ entities:
 
 # Mapping file — connects containers to primaries via secondaries
 mapping:
-  file: "provisions/index.yml"
+  file: "mapping/index.yml"
 
 # ---------------------------------------------------------------------------
 # Site navigation
