Skip to content

Commit dce6b8f

Browse files
styk-tvstyk-tv
committed
VitePress documentation site with GitHub Actions deployment
- Full CKP documentation: architecture, concepts, quickstart - VitePress config with nav, sidebar, search, social links - Custom theme with brand colors and hover effects - GitHub Actions workflow for automated build and deploy - Discord invite links throughout all pages - README with badge pills (Discord, GitHub, License) - SVG logo and CNAME for conceptkernel.org
1 parent 849e04b commit dce6b8f

22 files changed

Lines changed: 3561 additions & 11 deletions

‎.github/workflows/deploy.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Deploy VitePress to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
with:
24+
fetch-depth: 0
25+
26+
- name: Setup Node
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: 20
30+
cache: npm
31+
32+
- name: Setup Pages
33+
uses: actions/configure-pages@v4
34+
35+
- name: Install dependencies
36+
run: npm ci
37+
38+
- name: Build with VitePress
39+
run: npm run docs:build
40+
41+
- name: Upload artifact
42+
uses: actions/upload-pages-artifact@v3
43+
with:
44+
path: docs/.vitepress/dist
45+
46+
deploy:
47+
environment:
48+
name: github-pages
49+
url: ${{ steps.deployment.outputs.page_url }}
50+
needs: build
51+
runs-on: ubuntu-latest
52+
steps:
53+
- name: Deploy to GitHub Pages
54+
id: deployment
55+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules
2+
docs/.vitepress/cache
3+
docs/.vitepress/dist

‎README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[![Concept Kernel Protocol](https://img.shields.io/badge/Concept_Kernel-Protocol-blue?style=for-the-badge)](https://conceptkernel.org)
2+
[![Discord](https://img.shields.io/badge/Discord-Join_Community-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/sTbfxV9xyU)
3+
[![GitHub](https://img.shields.io/badge/GitHub-ConceptKernel-181717?style=for-the-badge&logo=github)](https://github.com/ConceptKernel)
4+
[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
5+
6+
# Concept Kernel Protocol
7+
8+
An open protocol for autonomous concept governance across distributed agents and semantic systems.
9+
10+
## What is CKP?
11+
12+
The Concept Kernel Protocol defines how autonomous agents can share, govern, and evolve concepts with semantic coherence at scale. Every concept is a **Concept Kernel** — a self-governing process that defends its own ontology, enforces constraints, and participates in consensus.
13+
14+
## Key Features
15+
16+
- **Autonomous Kernels** — Every concept is a self-governing process
17+
- **Protocol-Driven** — All operations flow through typed, logged protocol messages
18+
- **Ontology-First** — Built on LinkML schemas and SHACL constraints
19+
- **Consensus Governance** — Mutations require cryptographic proofs and stakeholder consensus
20+
- **Burst Propagation** — Changes ripple through the concept graph with constraint validation at every hop
21+
- **Agent-Ready** — Designed for billions of autonomous agents
22+
23+
## Documentation
24+
25+
Visit **[conceptkernel.org](https://conceptkernel.org)** for full documentation.
26+
27+
## Quick Start
28+
29+
```bash
30+
git clone https://github.com/ConceptKernel/conceptkernel-python.git
31+
cd conceptkernel-python
32+
pip install -r requirements.txt
33+
```
34+
35+
## Community
36+
37+
[![Discord](https://img.shields.io/badge/Discord-Join_us-5865F2?style=flat-square&logo=discord&logoColor=white)](https://discord.gg/sTbfxV9xyU)
38+
39+
Join our [Discord server](https://discord.gg/sTbfxV9xyU) to discuss the protocol, ask questions, and contribute.
40+
41+
## License
42+
43+
MIT

‎docs/.vitepress/config.mts‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
import { defineConfig } from 'vitepress'
2+
3+
export default defineConfig({
4+
title: 'Concept Kernel Protocol',
5+
description: 'An open protocol for autonomous concept governance across distributed agents',
6+
7+
head: [
8+
['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
9+
['meta', { property: 'og:type', content: 'website' }],
10+
['meta', { property: 'og:title', content: 'Concept Kernel Protocol' }],
11+
['meta', { property: 'og:description', content: 'An open protocol for autonomous concept governance across distributed agents' }],
12+
['meta', { property: 'og:url', content: 'https://conceptkernel.org' }],
13+
],
14+
15+
cleanUrls: true,
16+
lastUpdated: true,
17+
18+
themeConfig: {
19+
logo: '/logo.svg',
20+
siteTitle: 'Concept Kernel',
21+
22+
nav: [
23+
{ text: 'Docs', link: '/introduction' },
24+
{ text: 'Architecture', link: '/architecture' },
25+
{ text: 'Concepts', link: '/concepts/kernels' },
26+
{ text: 'Get Started', link: '/getting-started/quickstart' },
27+
{
28+
text: 'Community',
29+
items: [
30+
{ text: 'Discord', link: 'https://discord.gg/sTbfxV9xyU' },
31+
{ text: 'GitHub', link: 'https://github.com/ConceptKernel' },
32+
]
33+
}
34+
],
35+
36+
sidebar: [
37+
{
38+
text: 'Introduction',
39+
items: [
40+
{ text: 'What is CKP?', link: '/introduction' },
41+
{ text: 'Architecture', link: '/architecture' },
42+
]
43+
},
44+
{
45+
text: 'Core Concepts',
46+
items: [
47+
{ text: 'Kernels', link: '/concepts/kernels' },
48+
{ text: 'Ontology', link: '/concepts/ontology' },
49+
{ text: 'Protocol', link: '/concepts/protocol' },
50+
{ text: 'Consensus', link: '/concepts/consensus' },
51+
{ text: 'Governance', link: '/concepts/governance' },
52+
]
53+
},
54+
{
55+
text: 'Getting Started',
56+
items: [
57+
{ text: 'Quickstart', link: '/getting-started/quickstart' },
58+
{ text: 'Installation', link: '/getting-started/installation' },
59+
]
60+
},
61+
{
62+
text: 'Community',
63+
items: [
64+
{ text: 'Join Discord', link: 'https://discord.gg/sTbfxV9xyU' },
65+
{ text: 'GitHub', link: 'https://github.com/ConceptKernel' },
66+
{ text: 'Contributing', link: '/contributing' },
67+
]
68+
}
69+
],
70+
71+
socialLinks: [
72+
{ icon: 'github', link: 'https://github.com/ConceptKernel' },
73+
{ icon: 'discord', link: 'https://discord.gg/sTbfxV9xyU' },
74+
],
75+
76+
footer: {
77+
message: 'Released under the MIT License.',
78+
copyright: 'Copyright 2024-present ConceptKernel Contributors'
79+
},
80+
81+
search: {
82+
provider: 'local'
83+
},
84+
85+
editLink: {
86+
pattern: 'https://github.com/ConceptKernel/conceptkernel.github.io/edit/main/docs/:path',
87+
text: 'Edit this page on GitHub'
88+
}
89+
}
90+
})

‎docs/.vitepress/theme/custom.css‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
:root {
2+
--vp-c-brand-1: #3B82F6;
3+
--vp-c-brand-2: #2563EB;
4+
--vp-c-brand-3: #1D4ED8;
5+
--vp-c-brand-soft: rgba(59, 130, 246, 0.14);
6+
--vp-home-hero-name-color: transparent;
7+
--vp-home-hero-name-background: linear-gradient(135deg, #3B82F6 0%, #8B5CF6 100%);
8+
--vp-home-hero-image-background-image: linear-gradient(135deg, rgba(59, 130, 246, 0.2) 0%, rgba(139, 92, 246, 0.2) 100%);
9+
--vp-home-hero-image-filter: blur(56px);
10+
}
11+
12+
.dark {
13+
--vp-c-brand-1: #60A5FA;
14+
--vp-c-brand-2: #3B82F6;
15+
--vp-c-brand-3: #2563EB;
16+
}
17+
18+
.VPHero .tagline {
19+
font-size: 1.2rem !important;
20+
max-width: 560px;
21+
line-height: 1.6;
22+
}
23+
24+
.VPFeature {
25+
transition: transform 0.2s, box-shadow 0.2s;
26+
}
27+
28+
.VPFeature:hover {
29+
transform: translateY(-2px);
30+
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
31+
}

‎docs/.vitepress/theme/index.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
import DefaultTheme from 'vitepress/theme'
2+
import './custom.css'
3+
4+
export default DefaultTheme

‎docs/architecture.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Architecture
2+
3+
The Concept Kernel Protocol uses a layered architecture where every concept is an autonomous kernel participating in a governed protocol.
4+
5+
## System Overview
6+
7+
```
8+
┌─────────────────────────────────────────────────────┐
9+
│ Layer 3: User Concepts │
10+
│ Cat · Invoice · Gene · Policy · ... │
11+
├─────────────────────────────────────────────────────┤
12+
│ Layer 2: CK-Protocol │
13+
│ Messages · Actions · Routing · Compliance │
14+
├─────────────────────────────────────────────────────┤
15+
│ Layer 1: CK-Ontology │
16+
│ LinkML · SHACL · Type Registry · Validation│
17+
├─────────────────────────────────────────────────────┤
18+
│ Layer 0: CK-Core │
19+
│ Orchestration · Lifecycle · RBAC · Consensus│
20+
└─────────────────────────────────────────────────────┘
21+
```
22+
23+
## Core Kernels
24+
25+
The protocol is implemented through a set of core kernels, each with a distinct responsibility:
26+
27+
| Kernel | Role | Responsibility |
28+
|--------|------|----------------|
29+
| **CK_Core** | Orchestrator | Routes actions, manages registry, delegates to other kernels |
30+
| **CK_Ontology** | Type System | Registers ontologies, validates actions, queries relationships |
31+
| **CK_Admission** | Entrypoint | Receives requests, validates structure, routes to handlers |
32+
| **CK_Proof** | Cryptographic Proofs | Generates and verifies proofs, logs events, supports rollback |
33+
| **CK_Consensus** | Governance | Proposes consensus rounds, manages voting, validates decisions |
34+
| **CK_Constraint** | Enforcement | Defines constraints, validates actions against SHACL shapes |
35+
| **CK_Storage** | Persistence | Protocol-abstracted storage across disk, git, and triplestore backends |
36+
| **CK_Concept** | Concept Kernel | Every concept is a kernel — defines, validates, and relates itself |
37+
38+
## Concept Kernel Structure
39+
40+
Every concept kernel maintains its own directory structure:
41+
42+
```
43+
/concepts/{ConceptName}/
44+
├── ontology.yaml # LinkML schema + SHACL
45+
├── kernel.js # WASM-executable interface
46+
├── io/
47+
│ ├── input/ # Validated ingress
48+
│ └── output/ # Audited egress
49+
├── shacl/ # SHACL constraint rules
50+
└── var/
51+
├── ledger/ # Immutable audit records
52+
└── jobs/ # Execution traces
53+
```
54+
55+
## Protocol Actions
56+
57+
All operations are expressed as typed protocol actions:
58+
59+
| Action | Purpose |
60+
|--------|---------|
61+
| `REL` | Create or update relationships between concepts |
62+
| `LINK` | Link concepts with type constraints |
63+
| `MERGE` | Merge concepts with strategy selection |
64+
| `UPDATE` | Update attributes with full auditability |
65+
| `PROOF` | Generate or verify cryptographic proofs |
66+
| `CONSENSUS` | Propose voting and governance decisions |
67+
68+
## Message Flow
69+
70+
Every protocol interaction follows a structured message flow:
71+
72+
```
73+
SESSION[s25a8] (Cat Admission)
74+
→ PROPOSE[tx1] : CK_ADM → propose → CK_ONT : cat
75+
→ VALIDATE[tx2]:
76+
→ GET[tx1a]: CK_ONT → get → CK_STO : constraints
77+
← RETURN[tx1b]: CK_STO → return → CK_ONT : [5 rules]
78+
→ VERIFY[tx1c]: CK_ONT → verify → CK_TAX : mammal
79+
→ ASSIMILATE[tx3]: concept stored (version: 1)
80+
← LOG[tx4]: protocol_log saved
81+
```
82+
83+
## Storage Abstraction
84+
85+
All persistence flows through `CK_Storage`, which supports multiple backends:
86+
87+
- **Disk** — Local filesystem for development
88+
- **Git** — Version-controlled concept storage with full history
89+
- **Oxigraph** — RDF triplestore for ontology queries and SPARQL
90+
91+
No kernel may access storage directly. All reads and writes go through the storage protocol.
92+
93+
## Burst Propagation
94+
95+
When a concept changes, the protocol triggers a **burst propagation** — a wave that traverses ontological relationships:
96+
97+
1. Originates at the mutated concept
98+
2. Traverses `REL` and `LINK` edges
99+
3. Evaluates SHACL constraints at each hop
100+
4. Handles locked kernels via consensus escalation
101+
5. Converges proofs from all affected branches
102+
103+
This ensures that the full concept graph remains consistent after every mutation.
104+
105+
---
106+
107+
<div style="text-align: center; padding: 2rem 0;">
108+
<a href="https://discord.gg/sTbfxV9xyU" style="display: inline-block; padding: 0.6rem 1.5rem; background: #5865F2; color: white; border-radius: 6px; font-weight: 600; text-decoration: none;">Discuss Architecture on Discord</a>
109+
</div>

0 commit comments

Comments
 (0)