Skip to content

Commit fa235e5

Browse files
snapsynapseclaude
snapsynapse
and
claude
committed
Initial commit: Knowledge-as-Code template
Config-driven static site generator for ontology-first knowledge bases. Edit project.yml to define entities, groups, statuses, and colors. Add markdown data files, run build.js, get a full HTML site + JSON API. Includes example data (3 requirements, 2 frameworks, 2 organizations) that builds into 21 HTML pages out of the box. Zero dependencies — Node.js built-ins only. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
0 parents  commit fa235e5

19 files changed

Lines changed: 3438 additions & 0 deletions

File tree

‎.github/workflows/build.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Build
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
jobs:
11+
build:
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- uses: actions/checkout@v4
16+
17+
- uses: actions/setup-node@v4
18+
with:
19+
node-version: '20'
20+
21+
- name: Validate cross-references
22+
run: node scripts/validate.js
23+
24+
- name: Build site
25+
run: node scripts/build.js
26+
27+
- name: Deploy to GitHub Pages
28+
if: github.event_name != 'pull_request'
29+
uses: peaceiris/actions-gh-pages@v3
30+
with:
31+
github_token: ${{ secrets.GITHUB_TOKEN }}
32+
publish_dir: ./docs

‎.gitignore‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# OS files
5+
.DS_Store
6+
Thumbs.db
7+
8+
# Editor files
9+
*.swp
10+
*.swo
11+
*~
12+
.idea/
13+
.vscode/
14+
*.sublime-*
15+
.claude/
16+
17+
# Logs
18+
*.log
19+
npm-debug.log*
20+
21+
# Generated output (rebuild with: node scripts/build.js)
22+
# docs/ is generated — track only the static assets
23+
docs/*
24+
!docs/assets/
25+
docs/assets/*
26+
!docs/assets/styles.css
27+
!docs/assets/search.js
28+
29+
# Environment
30+
.env
31+
.env.local

‎CLAUDE.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Knowledge-as-Code Project
2+
3+
A config-driven knowledge base using an ontology-first approach. All domain-specific settings are in `project.yml`.
4+
5+
## Project Structure
6+
7+
```
8+
project.yml # Domain configuration (THE key file)
9+
data/
10+
examples/ # Data files (one .md per entity)
11+
primary/ # Stable anchor entities
12+
container/ # Grouping entities with provisions
13+
authority/ # Source entities
14+
mapping/ # index.yml connecting containers to primaries
15+
scripts/
16+
build.js # Config-driven site generator
17+
validate.js # Cross-reference validator
18+
docs/ # Generated output (HTML + JSON API)
19+
api/v1/ # Static JSON API
20+
```
21+
22+
## Key Commands
23+
24+
```bash
25+
node scripts/build.js # Build site + JSON API
26+
node scripts/validate.js # Validate cross-references
27+
```
28+
29+
## Entity Model
30+
31+
The ontology is defined in `project.yml` under `entities:`. Four roles:
32+
33+
| Role | Config key | Description |
34+
|------|-----------|-------------|
35+
| Primary | `entities.primary` | Stable anchors (e.g., requirements) |
36+
| Container | `entities.container` | Grouping entities (e.g., frameworks) |
37+
| Authority | `entities.authority` | Source entities (e.g., organizations) |
38+
| Secondary | `entities.secondary` | Mapping entities connecting containers to primaries |
39+
40+
Relationship: Authority → Container → Secondary → Primary
41+
42+
## Adding Data
43+
44+
1. Create a `.md` file in the appropriate `data/` directory
45+
2. Add YAML frontmatter with required fields (see existing files for format)
46+
3. For containers: add timeline table and provision sections separated by `---`
47+
4. Add mapping entries to `data/examples/mapping/index.yml`
48+
5. Run `node scripts/validate.js` to check cross-references
49+
6. Run `node scripts/build.js` to generate the site
50+
51+
## Customization
52+
53+
Edit `project.yml` to change:
54+
- Entity names and directories
55+
- Group categories and colors
56+
- Status types and colors
57+
- Site name, URL, and navigation
58+
- Bridge page patterns
59+
- Theme accent colors

‎README.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# Knowledge-as-Code Template
2+
3+
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.
4+
5+
## Quick Start
6+
7+
1. **Use this template** — click "Use this template" on GitHub, or clone locally
8+
2. **Edit `project.yml`** — define your domain entities, groups, colors, and site identity
9+
3. **Add data** — create markdown files in `data/` following the schema in `data/_schema.md`
10+
4. **Build** — `node scripts/build.js`
11+
5. **Deploy** — push to GitHub, Pages deploys automatically
12+
13+
## What You Get
14+
15+
- **Static HTML site** — homepage, list pages, detail pages, coverage matrix, timeline, comparison tool
16+
- **JSON API** — programmatic access at `docs/api/v1/`
17+
- **Bridge pages** — SEO-targeted pages like "Does X require Y?"
18+
- **Dark/light theme** — with persistence
19+
- **Client-side search** — lazy-loaded, keyboard-navigable
20+
- **Zero dependencies** — Node.js built-ins only
21+
22+
## Project Structure
23+
24+
```
25+
project.yml # Domain configuration (edit this first)
26+
data/
27+
examples/ # Example data (replace with your own)
28+
primary/ # Stable anchor entities (e.g., requirements, obligations)
29+
container/ # Grouping entities (e.g., frameworks, regulations)
30+
authority/ # Source entities (e.g., organizations, regulators)
31+
mapping/ # index.yml connecting containers to primaries
32+
scripts/
33+
build.js # Config-driven site generator
34+
validate.js # Cross-reference validator
35+
docs/ # Generated output (do not edit)
36+
```
37+
38+
## The Ontology
39+
40+
Every knowledge-as-code project has four entity roles:
41+
42+
```
43+
Authority → Container → Provision → Primary
44+
```
45+
46+
| Role | What it is | Example domains |
47+
|------|-----------|----------------|
48+
| **Primary** | Stable anchors that don't change when sources change | Requirements, Obligations, Capabilities, Controls |
49+
| **Container** | Grouping entities that contain provisions | Regulations, Frameworks, Products, Standards |
50+
| **Authority** | Source entities that produce containers | Regulators, Vendors, Standards bodies |
51+
| **Secondary** | Mapping entities connecting containers to primaries | Provisions, Implementations, Mappings |
52+
53+
Primaries are stable; containers are unstable. When a framework is amended, its provisions change, but the underlying requirements persist.
54+
55+
## Configuration
56+
57+
All domain-specific settings live in `project.yml`:
58+
59+
- **Entity names** — what to call each entity type (e.g., "Requirement" vs "Obligation")
60+
- **Groups** — categories for primary entities, with dark/light mode colors
61+
- **Statuses** — lifecycle states for containers, with colors
62+
- **Navigation** — site nav items
63+
- **Bridge pages** — which SEO pages to generate
64+
- **Theme** — accent colors
65+
66+
## Commands
67+
68+
```bash
69+
node scripts/build.js # Build the site
70+
node scripts/validate.js # Validate cross-references
71+
```
72+
73+
## Architecture
74+
75+
- **File-over-App** — data in markdown files, not a database
76+
- **Zero dependencies** — no npm install, no supply chain risk
77+
- **Bespoke static generation** — the build script _is_ the specification
78+
- **GitOps** — Git is the single source of truth
79+
80+
## License
81+
82+
MIT

‎data/examples/frameworks/iso-27001.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
name: ISO 27001
3+
authority: iso
4+
jurisdiction: International
5+
type: standard
6+
status: active
7+
enacted: 2022-10-25
8+
effective: 2022-10-25
9+
official_url: https://www.iso.org/standard/27001
10+
last_verified: 2026-03-25
11+
---
12+
13+
## Timeline
14+
15+
| Milestone | Date | Notes |
16+
|-----------|------|-------|
17+
| Published | 2022-10-25 | ISO/IEC 27001:2022 released |
18+
| Transition deadline | 2025-10-31 | Organizations must transition from 2013 version |
19+
20+
---
21+
22+
## Information Security Controls (Annex A)
23+
24+
| Property | Value |
25+
|----------|-------|
26+
| Obligation | access-control |
27+
| Sections | Annex A.5-A.8 |
28+
| Status | active |
29+
| Effective | 2022-10-25 |
30+
| Verified | 2026-03-25 |
31+
| Checked | 2026-03-25 |
32+
33+
### Requirements
34+
35+
| Requirement | Details |
36+
|-------------|---------|
37+
| Access control policy | Define and enforce access control rules |
38+
| User access management | Formal registration and de-registration |
39+
40+
### Talking Point
41+
42+
> "ISO 27001:2022 restructured Annex A controls into **4 themes** (organizational, people, physical, technological) with **93 controls** replacing the previous 114."
43+
44+
### Sources
45+
46+
- [ISO 27001:2022](https://www.iso.org/standard/27001)
47+
48+
---
49+
50+
## Data Quality Requirements (Clause 7.5)
51+
52+
| Property | Value |
53+
|----------|-------|
54+
| Obligation | data-quality |
55+
| Sections | Clause 7.5 |
56+
| Status | active |
57+
| Effective | 2022-10-25 |
58+
| Verified | 2026-03-25 |
59+
| Checked | 2026-03-25 |
60+
61+
### Requirements
62+
63+
| Requirement | Details |
64+
|-------------|---------|
65+
| Documented information | Maintain quality and integrity of ISMS documentation |
66+
| Information classification | Classify information according to sensitivity |
67+
68+
### Talking Point
69+
70+
> "Clause 7.5 requires organizations to ensure documented information is **available, suitable, and adequately protected** throughout its lifecycle."
71+
72+
### Sources
73+
74+
- [ISO 27001:2022](https://www.iso.org/standard/27001)

‎data/examples/frameworks/nist-csf.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
name: NIST Cybersecurity Framework
3+
authority: nist
4+
jurisdiction: Federal
5+
type: framework
6+
status: active
7+
enacted: 2024-02-26
8+
effective: 2024-02-26
9+
official_url: https://www.nist.gov/cyberframework
10+
last_verified: 2026-03-25
11+
---
12+
13+
## Timeline
14+
15+
| Milestone | Date | Notes |
16+
|-----------|------|-------|
17+
| CSF 2.0 published | 2024-02-26 | Major update adding Govern function |
18+
| CSF 1.1 published | 2018-04-16 | Original framework |
19+
20+
---
21+
22+
## Incident Response (RS.AN, RS.MI)
23+
24+
| Property | Value |
25+
|----------|-------|
26+
| Obligation | incident-response |
27+
| Sections | RS.AN, RS.MI |
28+
| Status | active |
29+
| Effective | 2024-02-26 |
30+
| Verified | 2026-03-25 |
31+
| Checked | 2026-03-25 |
32+
33+
### Requirements
34+
35+
| Requirement | Details |
36+
|-------------|---------|
37+
| Analysis | Investigate incidents to determine scope and impact |
38+
| Mitigation | Contain and mitigate effects of detected incidents |
39+
40+
### Talking Point
41+
42+
> "NIST CSF 2.0 restructured response activities into **analysis and mitigation** subcategories, emphasizing that incident response is a continuous improvement process."
43+
44+
### Sources
45+
46+
- [NIST CSF 2.0](https://www.nist.gov/cyberframework)
47+
48+
---
49+
50+
## Access Control (PR.AA)
51+
52+
| Property | Value |
53+
|----------|-------|
54+
| Obligation | access-control |
55+
| Sections | PR.AA |
56+
| Status | active |
57+
| Effective | 2024-02-26 |
58+
| Verified | 2026-03-25 |
59+
| Checked | 2026-03-25 |
60+
61+
### Requirements
62+
63+
| Requirement | Details |
64+
|-------------|---------|
65+
| Identity management | Manage identities and credentials for authorized users |
66+
| Access enforcement | Enforce access permissions based on policies |
67+
68+
### Talking Point
69+
70+
> "CSF 2.0 consolidated identity and access management into a single **PR.AA** subcategory, clarifying that authentication and authorization are inseparable."
71+
72+
### Sources
73+
74+
- [NIST CSF 2.0](https://www.nist.gov/cyberframework)

‎data/examples/mapping/index.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
- id: iso-27001-access-control
2+
regulation: iso-27001
3+
authority: iso
4+
source_file: data/examples/container/iso-27001.md
5+
source_heading: Information Security Controls (Annex A)
6+
obligations:
7+
- access-control
8+
9+
- id: iso-27001-data-quality
10+
regulation: iso-27001
11+
authority: iso
12+
source_file: data/examples/container/iso-27001.md
13+
source_heading: Data Quality Requirements (Clause 7.5)
14+
obligations:
15+
- data-quality
16+
17+
- id: nist-csf-incident-response
18+
regulation: nist-csf
19+
authority: nist
20+
source_file: data/examples/container/nist-csf.md
21+
source_heading: Incident Response (RS.AN, RS.MI)
22+
obligations:
23+
- incident-response
24+
25+
- id: nist-csf-access-control
26+
regulation: nist-csf
27+
authority: nist
28+
source_file: data/examples/container/nist-csf.md
29+
source_heading: Access Control (PR.AA)
30+
obligations:
31+
- access-control

0 commit comments

Comments
 (0)