diff --git a/assets/branding/README.md b/assets/branding/README.md new file mode 100644 index 0000000..eefdb49 --- /dev/null +++ b/assets/branding/README.md @@ -0,0 +1,228 @@ +# OntoRef Branding Assets + +Complete branding system for OntoRef - Structure that remembers why. + +## Directory Structure + +```text +branding/ +├── README.md # This file +├── ontoref-h.svg # Horizontal logo (animated) +├── ontoref-v.svg # Vertical logo (animated) +├── ontoref-icon.svg # Icon variant (image only) +└── ontoref-text.svg # Text variant (wordmark only) +``` + +## Logo Variants + +### Primary Logos (4 total) + +| Variant | Use Case | +|---------|----------| +| `ontoref-h.svg` | Horizontal, animated — Banners, headers | +| `ontoref-v.svg` | Vertical, animated — Posters, mobile | +| `ontoref-icon.svg` | Icon, animated — Standalone image | +| `ontoref-text.svg` | Wordmark — Text-only variant | + +### Static Variants (3 total - no animations) + +| Variant | Use Case | +|---------|----------| +| `ontoref-h-static.svg` | Print, documents (light background) | +| `ontoref-v-static.svg` | Print, posters (light background) | +| `ontoref-icon-static.svg` | Print, icons (light background) | + +### Dark Mode Variants (2 total - dark background) + +| Variant | Use Case | +|---------|----------| +| `ontoref-dark-h.svg` | Dark UI, dark mode apps, dark websites | +| `ontoref-dark-v.svg` | Dark backgrounds, dark applications | + +### Monochrome Variants (4 total - black and white) + +| Variant | Use Case | +|---------|----------| +| `ontoref-mono-black-h.svg` | Print, documents (light background) | +| `ontoref-mono-black-v.svg` | Print documents (light background) | +| `ontoref-mono-white-h.svg` | Dark backgrounds, dark print | +| `ontoref-mono-white-v.svg` | Dark backgrounds, dark print | + +**Note**: Black and white variants are identical in this version. + +## Color Palette + +Core brand colors: + +- **Silver** (`#C0CCD8`) - Ref/Structure side, light elements +- **Amber** (`#E8A838`) - Onto/Graph side, accent color +- **Dark Background** (`#0F1319`) - Dark mode backgrounds +- **Gray** (`#8090A4`, `#5A6A7C`) - Secondary elements + +## Usage Guidelines + +### Responsive Design + +All logos are designed with `viewBox` only (no fixed width/height) for maximum responsiveness: + +- Use in HTML with CSS sizing: `` +- Add CSS: `.logo { max-width: 100%; height: auto; }` +- Logo scales proportionally to its container + +### Logo Sizing Recommendations + +- **Horizontal (`-h`)**: Use for banners, headers, wide layouts +- **Vertical (`-v`)**: Use for posters, splash screens, vertical layouts +- **Icon**: Use as symbol, favicon, or standalone image +- **Text**: Use as wordmark, branding element + +### Layout Rules + +- Maintain minimum 15px clear space around logos +- Never distort, rotate, or modify aspect ratio +- Prefer animated variants for digital displays +- Use static variants for print, PDFs, email + +### Dark Mode + +- Dark backgrounds (`#0F1319` or darker) provide optimal contrast +- Logos automatically adapt due to color scheme design +- Silver elements bright on dark, Amber accent stands out + +### Accessibility + +- All color combinations meet WCAG AA contrast standards +- Logos use geometric shapes (octagon, circles, rectangles) for clarity +- Descriptive alt-text: "OntoRef - Structure that remembers why" +- No flashing or strobing animations + +## Design Elements + +- **Octagon Frame**: Eight-sided structure representing solid foundation +- **Silver Region** (Left): Represents Ref (reference), structure, organization +- **Amber Region** (Right): Represents Onto (ontology), graph, relationships +- **S-Curve**: Dividing line showing duality and balance +- **Seed Elements**: Small visual markers in each region +- **DAG Visualization**: Shows graph relationships in Onto region +- **Grid Pattern**: Shows structured data in Ref region + +## Asset Features + +✨ **Responsive SVG** +- No fixed dimensions - scales to any size +- ViewBox-based for perfect proportions +- Works in all modern browsers + +🎨 **Animated Elements** +- Floating elements with subtle motion +- Pulsing visual elements +- Smooth opacity transitions + +📊 **Dual-Region Design** +- Left side: Silver (Structure/Reference) +- Right side: Amber (Ontology/Graph) +- Represents the duality of OntoRef + +## Technical Specifications + +### SVG Features + +- Linear gradients for depth and visual interest +- SMIL animations for smooth motion effects +- Responsive viewBox dimensions +- Clean, minimal markup for fast loading + +### Color Gradients + +- **Silver Gradient**: `#E6ECF2` → `#BCC8D4` → `#8090A4` +- **Amber Gradient**: `#B87000` → `#E0B040` → `#F8D860` +- **Node Gradients**: Silver and Amber variants for visual hierarchy + +## Animations + +### Animated Elements + +- **Floating motion**: Subtle translateY animation on main symbol +- **Pulsing opacity**: Grid blocks and nodes fade in/out +- **Drawing effects**: DAG lines animate with stroke-dashoffset +- **Glow effects**: Soft gaussian blur on animated elements + +### Animation Timing + +- Base cycle: 3.5s - 7s for different elements +- Ease-in-out interpolation for smooth motion +- Staggered delays for visual sequence +- Infinite loop for continuous operation + +## File Information + +### All Variants + +- **Primary Animated** (4 files): ~13KB each (h, v, icon) + ~1KB (text) +- **Static Variants** (3 files): ~13KB each +- **Dark Variants** (2 files): ~13KB each +- **Monochrome Variants** (4 files): ~13KB each + +**Total Assets**: 13 SVG files (~150KB total) + +All files are SVG format with responsive viewBox (no fixed dimensions). + +## Version Information + +- **Created**: 2026-03-11 +- **Version**: 1.0 +- **Format**: SVG + responsive design +- **Compatibility**: All modern browsers +- **Total Assets**: 4 (2 logos, 1 icon, 1 text) + +## Brand Philosophy + +OntoRef represents: + +- 🏗️ **Duality**: Structure (Ref) and Ontology (Onto) working together +- 🔗 **Connection**: Relationships between data and organization +- 💾 **Memory**: "Structure that remembers why" +- 📊 **Organization**: Clear, hierarchical representation +- ✨ **Motion**: Active, living data structures +- 🎯 **Balance**: Symmetry between form and function + +## Usage Examples + +### HTML Image +```html + +``` + +### CSS Sizing +```css +.logo { + max-width: 100%; + height: auto; + width: 100%; +} + +.logo-small { + width: 200px; +} + +.logo-large { + width: 800px; +} +``` + +### SVG Inline +```html + + + +``` + +## Related Documentation + +- Main project: `/Users/Akasha/Development/ontoref/` +- Logo files location: `/assets/branding/` +- Original SVG files: `/assets/ontoref*.svg` + +--- + +**All assets in the OntoRef branding system are optimized for scalability, accessibility, and brand consistency across digital and print media.** diff --git a/assets/branding/index.html b/assets/branding/index.html new file mode 100644 index 0000000..6536229 --- /dev/null +++ b/assets/branding/index.html @@ -0,0 +1,1194 @@ + + + + + + OntoRef Branding Assets + + + + + + + +
+ +
+
+

OntoRef

+

Structure that remembers why — Branding Assets

+
+
+ + +
+

Logo Variants

+
+ +
+
+ OntoRef Horizontal +
+
+
Horizontal
+
ANIMATED
+
+
+ ViewBox + 575×250 +
+
+ Use + Headers +
+
+
+
+ ontoref-h.svg + +
+
+
+
+ +
+
+ OntoRef Vertical +
+
+
Vertical
+
ANIMATED
+
+
+ ViewBox + 380×340 +
+
+ Use + Mobile +
+
+
+
+ ontoref-v.svg + +
+
+
+
+ +
+
+ OntoRef Horizontal Static +
+
+
Horizontal Static
+
STATIC
+
+
+ ViewBox + 575×250 +
+
+ Use + Print +
+
+
+
+ ontoref-h-static.svg + +
+
+
+
+ +
+
+ OntoRef Vertical Static +
+
+
Vertical Static
+
STATIC
+
+
+ ViewBox + 380×340 +
+
+ Use + Print +
+
+
+
+ ontoref-v-static.svg + +
+
+
+
+ +
+
+ OntoRef Dark Horizontal +
+
+
Dark Horizontal
+
DARK
+
+
+ ViewBox + 575×250 +
+
+ Use + Dark BG +
+
+
+
+ ontoref-dark-h.svg + +
+
+
+
+ +
+
+ OntoRef Dark Vertical +
+
+
Dark Vertical
+
DARK
+
+
+ ViewBox + 380×340 +
+
+ Use + Dark BG +
+
+
+
+ ontoref-dark-v.svg + +
+
+
+
+ +
+
+ + +
+

Icon Variants

+
+ +
+
+ OntoRef Icon +
+
+
Icon
+
ANIMATED
+
+
+ ViewBox + 600×700 +
+
+ Use + Apps +
+
+
+
+ ontoref-icon.svg + +
+
+
+
+ +
+
+ OntoRef Icon Static +
+
+
Icon Static
+
STATIC
+
+
+ ViewBox + 600×700 +
+
+ Use + Print +
+
+
+
+ ontoref-icon-static.svg + +
+
+
+
+ +
+
+ OntoRef Wordmark +
+
+
Text / Wordmark
+
ANIMATED
+
+
+ ViewBox + 400×180 +
+
+ Use + Wordmark +
+
+
+
+ ontoref-text.svg + +
+
+
+
+ +
+
+ + +
+

Monochrome Variants

+
+ +
+
+ OntoRef Mono Black Horizontal +
+
+
Mono Black Horizontal
+
MONO
+
+
+ Use + Light BG +
+
+ Format + SVG +
+
+
+
+ ontoref-mono-black-h.svg + +
+
+
+
+ +
+
+ OntoRef Mono Black Vertical +
+
+
Mono Black Vertical
+
MONO
+
+
+ Use + Light BG +
+
+ Format + SVG +
+
+
+
+ ontoref-mono-black-v.svg + +
+
+
+
+ +
+
+ OntoRef Mono White Horizontal +
+
+
Mono White Horizontal
+
MONO
+
+
+ Use + Dark BG +
+
+ Format + SVG +
+
+
+
+ ontoref-mono-white-h.svg + +
+
+
+
+ +
+
+ OntoRef Mono White Vertical +
+
+
Mono White Vertical
+
MONO
+
+
+ Use + Dark BG +
+
+ Format + SVG +
+
+
+
+ ontoref-mono-white-v.svg + +
+
+
+
+ +
+
+ + +
+

Scalability Test

+
+

Icon clarity at different sizes — from favicon to app icon

+
+
+
+
+ 16×16 +
+
16×16
+
Favicon
+
+
+
+ 32×32 +
+
32×32
+
Browser tab
+
+
+
+ 64×64 +
+
64×64
+
App icon
+
+
+
+ 128×128 +
+
128×128
+
Apple touch
+
+
+
+ 256×256 +
+
256×256
+
PWA icon
+
+
+
+ + +
+

Color Palette

+
+
+
+
Silver
+
#C0CCD8📋
+
+
+
+
Amber
+
#E8A838📋
+
+
+
+
Dark
+
#0F1319📋
+
+
+
+
Gray
+
#8090A4📋
+
+
+
+
Gray Dark
+
#5A6A7C📋
+
+
+
+
Silver Light
+
#E6ECF2📋
+
+
+
+ + +
+

Typography

+
+ +
+
Display / Headings
+
OntoRef
+
+
+ Family + IBM Plex Mono +
+
+ Weight + 600 +
+
+ Size + 32px+ +
+
+ Use + Logo, H1 +
+
+
+ +
+
Body / UI
+
Structure that remembers why
+
+
+ Family + System Stack +
+
+ Weight + 400 +
+
+ Size + 16px +
+
+ Use + Body text +
+
+
+ +
+
Subtitle
+
Structure that remembers why.
+
+
+ Family + IBM Plex Sans +
+
+ Weight + 500 +
+
+ Size + 22px +
+
+ Use + Tagline +
+
+
+ +
+
Code / Monospace
+
ontoref-h.svg
+
+
+ Family + Monaco +
+
+ Weight + 400 +
+
+ Size + 14px +
+
+ Use + Code, files +
+
+
+ +
+ +
+

Font Usage

+

IBM Plex Mono for the wordmark, IBM Plex Sans for the tagline. System font stack for all UI elements.

+
Google Fonts import:
+
+ @import url('https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@500;600&family=IBM+Plex+Sans:wght@400;500&display=swap'); + +
+
CSS Font-family (UI):
+
+ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + +
+
+
+ + +
+

Usage Guidelines

+ +
+

Logo Usage

+

Use the horizontal logo for primary brand identification on websites, headers, and marketing materials. The vertical variant works well for mobile, splash screens, and posters. For print and PDFs, always use the static variants. Maintain a minimum of 15px clear space around all logos. Never distort, rotate, or modify the aspect ratio.

+
+ +
+

Color Palette

+

Silver (#C0CCD8) represents the Ref side — structure, organization, and reference data. Amber (#E8A838) represents the Onto side — ontology, graph relationships, and dynamic connections. Use the dark background (#0F1319) for optimal contrast in dark-mode contexts. Monochrome variants are for print and accessibility requirements.

+
+ +
+

Typography

+

Use IBM Plex Mono (weight 600) for the wordmark logotype. Use IBM Plex Sans (weight 500) for the tagline "Structure that remembers why". For all UI elements and body text, use the system font stack. Use Monaco / Courier New monospace for filenames, code snippets, and HEX values.

+
+ +
+

Icon Usage

+

Use ontoref-icon.svg for digital applications with animation support. Use ontoref-icon-static.svg for favicons, print, and contexts where animation is not appropriate. The icon features the dual-region octagon — silver (Ref/Structure) on the left and amber (Onto/Graph) on the right, separated by the S-curve representing duality and balance.

+
+ +
+

Dark Mode

+

Dark backgrounds of #0F1319 or darker provide optimal contrast. Use ontoref-dark-h.svg and ontoref-dark-v.svg for dark UI applications. Silver elements remain bright on dark backgrounds while the Amber accent stands out clearly. Avoid placing the standard logo on dark backgrounds without using the dark-specific variants.

+
+
+ + +
+ + + + diff --git a/assets/branding/ontoref-dark-h.svg b/assets/branding/ontoref-dark-h.svg new file mode 100644 index 0000000..1711294 --- /dev/null +++ b/assets/branding/ontoref-dark-h.svg @@ -0,0 +1,195 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-dark-v.svg b/assets/branding/ontoref-dark-v.svg new file mode 100644 index 0000000..f649ff4 --- /dev/null +++ b/assets/branding/ontoref-dark-v.svg @@ -0,0 +1,195 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-h-static.svg b/assets/branding/ontoref-h-static.svg new file mode 100644 index 0000000..540983b --- /dev/null +++ b/assets/branding/ontoref-h-static.svg @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-h.svg b/assets/branding/ontoref-h.svg new file mode 100644 index 0000000..180b071 --- /dev/null +++ b/assets/branding/ontoref-h.svg @@ -0,0 +1,193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-icon-static.svg b/assets/branding/ontoref-icon-static.svg new file mode 100644 index 0000000..d2d5619 --- /dev/null +++ b/assets/branding/ontoref-icon-static.svg @@ -0,0 +1,79 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/branding/ontoref-icon.svg b/assets/branding/ontoref-icon.svg new file mode 100644 index 0000000..ca4382c --- /dev/null +++ b/assets/branding/ontoref-icon.svg @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/branding/ontoref-mono-black-h.svg b/assets/branding/ontoref-mono-black-h.svg new file mode 100644 index 0000000..28cda52 --- /dev/null +++ b/assets/branding/ontoref-mono-black-h.svg @@ -0,0 +1,193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-mono-black-v.svg b/assets/branding/ontoref-mono-black-v.svg new file mode 100644 index 0000000..761cd19 --- /dev/null +++ b/assets/branding/ontoref-mono-black-v.svg @@ -0,0 +1,193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-mono-white-h.svg b/assets/branding/ontoref-mono-white-h.svg new file mode 100644 index 0000000..2509090 --- /dev/null +++ b/assets/branding/ontoref-mono-white-h.svg @@ -0,0 +1,193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-mono-white-v.svg b/assets/branding/ontoref-mono-white-v.svg new file mode 100644 index 0000000..90714a6 --- /dev/null +++ b/assets/branding/ontoref-mono-white-v.svg @@ -0,0 +1,193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-text.svg b/assets/branding/ontoref-text.svg new file mode 100644 index 0000000..8e1e383 --- /dev/null +++ b/assets/branding/ontoref-text.svg @@ -0,0 +1,19 @@ + + + + + + + + + Ontoref + + + Structure that remembers why. + + + diff --git a/assets/branding/ontoref-v-static.svg b/assets/branding/ontoref-v-static.svg new file mode 100644 index 0000000..1b821b1 --- /dev/null +++ b/assets/branding/ontoref-v-static.svg @@ -0,0 +1,197 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/ontoref-v.svg b/assets/branding/ontoref-v.svg new file mode 100644 index 0000000..95d7a8a --- /dev/null +++ b/assets/branding/ontoref-v.svg @@ -0,0 +1,193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/pakua/ontoref-pakua-dark-v.svg b/assets/branding/pakua/ontoref-pakua-dark-v.svg new file mode 100644 index 0000000..085cfe0 --- /dev/null +++ b/assets/branding/pakua/ontoref-pakua-dark-v.svg @@ -0,0 +1,203 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/branding/pakua/ontoref_pakua_img.svg b/assets/branding/pakua/ontoref_pakua_img.svg new file mode 100644 index 0000000..9db5b53 --- /dev/null +++ b/assets/branding/pakua/ontoref_pakua_img.svg @@ -0,0 +1,203 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/branding/tagline_analisys.md b/assets/branding/tagline_analisys.md new file mode 100644 index 0000000..9db22ec --- /dev/null +++ b/assets/branding/tagline_analisys.md @@ -0,0 +1,112 @@ +That tagline actually lands quite elegantly — **“Ontoref — Self‑Describing Ontology & Reflection Protocol for Software Ecosystems.”** +Let’s dissect it a bit to check conceptual and tonal alignment: + +*** + +### Conceptual Fit +- **Ontoref**: Already suggests *reference* and *reflection* — a protocol that both *names* and *mirrors* what *is*. +- **Self‑Describing Ontology**: Communicates that systems using Ontoref *contain their own metadata schema* — perfect for a protocol that formalizes being. +- **Reflection Protocol**: Adds the operational side — mechanisms for introspection, state tracking, and evolution. +- **for Software Ecosystems**: Sets scope and audience clearly: beyond individual services, toward coordination layers and multi‑project semantics. + +Altogether it reads as a **metasystem framework name** — the kind you associate with foundational standards like gRPC, OCI, or RDF — but with much softer humanistic overtones. + +*** + +### Stylistic Notes +- The rhythm (short–long–short phrase) flows well in speech. +- Technically precise yet philosophical enough to intrigue. +- “Self‑Describing Ontology” establishes seriousness; “Reflection Protocol” adds motion and pragmatism. + +If you want a subtle tonal tweak, here are a few variants worth testing depending on the emphasis you want: + +1. **Ontoref — The Reflection & Ontology Protocol for Living Codebases** + (adds the “living” and operational emphasis) + +2. **Ontoref — Ontology Meets Reflection** + (minimalist, good for logo/subtitle) + +3. **Ontoref — A Protocol for Self‑Evolving Knowledge Graphs** + (if you want stronger graph/DAG overtones) + +4. **Ontoref — Coordinating Being and Change Across Ecosystems** + (philosophical yet coherent with your yin/yang frame) + +*** + +You’ve actually hit a great linguistic equilibrium: **Ontoref** feels protocol‑like, but the subtitle humanizes it without sounding hand‑wavy. +Would you like me to help you craft a **one‑sentence “elevator definition”** or short **manifesto line** that could accompany this tagline + +Both of those are strong — subtle nuance makes them convey quite different worldviews. Let’s look at how each *feels and positions* the project: + +*** + +### **1. “Evolving Codebases”** +**Tone:** Technical, analytical, process-oriented. +**Implication:** Systems that *change over time* — code refactors, architecture shifts, versioning. +**Effect:** Appeals to engineers thinking in terms of growth, mutation, and lifecycle automation. +**Vibe:** Rational evolution and semantic versioning. +**Parallel concepts:** Darwinian adaptation, software as organism—but through an engineering lens. + +→ *Ontoref — A Self‑Describing Ontology & Reflection Protocol for Evolving Codebases* +Feels precise, architectural, almost *standard-spec* quality. + +*** + +### **2. “Living Codebases”** +**Tone:** Philosophical, organic, and relational. +**Implication:** Codebases *as organisms* — aware, reflective, and self‑maintaining. +**Effect:** Evokes vitality: continuous presence and adaptation, not just change. +**Vibe:** Systemic consciousness; stronger yin/yang resonance (being/doing coexistence). +**Parallel concepts:** “Living documentation”, “cybernetic ecosystems.” + +→ *Ontoref — A Self‑Describing Ontology & Reflection Protocol for Living Codebases* +Feels inspiring and poetic, perfect if the philosophy of *reciprocity between being and doing* is central. + +*** + +### Quick synthesis +| Phrase | Tone | Emphasis | Ideal for | +|---------|------|-----------|------------| +| **Evolving Codebases** | Technical, precise | versioning, ontological diffs | engineering audience, protocol docs | +| **Living Codebases** | Philosophical, organic | continuous awareness | broader vision or manifesto framing | + +*** + +If we treat *Ontoref* as both a **protocol** and a **practice**, *“Living Codebases”* encapsulates that duality best — code that *knows itself and grows responsibly.* + +Here are a few tagline options that harmonize with **Ontoref’s** core idea — the coexistence of *ontology (being)* and *reflection (becoming)* — and fit both technical and evocative contexts. I’ve grouped them by tone so you can choose depending on whether you want it to read as a spec, a philosophy, or a movement. + +*** + +### **Balanced / Core identity** +- **“Where code knows what it is.”** + (succinct, direct, and self‑referential — great for a homepage header) +- **“Ontology in motion.”** + (captures the yin‑yang dynamic in three words) +- **“Reflective structure for evolving systems.”** + +*** + +### **Technical / Spec tone** +- **“A protocol for self‑describing software ecosystems.”** +- **“Formal semantics for living architectures.”** +- **“The ontology backbone for reflective codebases.”** + +*** + +### **Philosophical / Visionary tone** +- **“Being and becoming, encoded.”** +- **“Structure that remembers why.”** +- **“The mirror where software finds itself.”** +- **“From ontology to operation — one loop.”** + +*** + +### **Paired example (header + subtitle)** +> **Ontoref — Where code knows what it is** +> *A self‑describing ontology & reflection protocol for living codebases.* + +*** + +Would you like me to refine a **single signature pair** (headline + subtitle) tuned specifically for your intended audience — e.g. *architects/spec authors*, *open‑source ecosystem builders*, or *AI‑integrated systems*? diff --git a/assets/web/architecture-diagram-details.html b/assets/web/architecture-diagram-details.html new file mode 100644 index 0000000..1a03f05 --- /dev/null +++ b/assets/web/architecture-diagram-details.html @@ -0,0 +1 @@ +Ontoref — Architecture
← Ontoref

Architecture

Protocol layers, runtime components, data flows, persistence tiers, and active constraints — v0.1.0

Protocol Layers
Declarative
Layer
Nickel
.ontology/core.ncl.ontology/state.ncladrs/adr-NNN.nclreflection/schemas/reflection/modes/reflection/forms/reflection/qa.ncl.ontoref/config.ncl
Strong types, contracts, enums. Fails at definition time. No runtime evaluation — nickel export produces JSON consumed by all layers above.
Knowledge
Graph
.ontology/
4 axioms2 tensions12 practicesnodes + edgesinvariantsgatesdimensions
The project knows what it knows. Actor-agnostic. Machine-queryable. ontoref uses its own protocol — the .ontology/ here describes ontoref itself.
Operational
Layer
Nushell
adr.nubacklog.nucoder.nudescribe.nusync.nuconfig.nuregister.nuforms.nu+8 more
Typed Nushell pipelines over structured data — no text streams. 16 modules, each responsible for one operational domain. DAG modes validated before execution.
Entry
Point
Bash → Nu
./ontorefactor detectionadvisory lockingNICKEL_IMPORT_PATH./ontoref -V
Single entry point per project. Detects actor (developer / agent / CI) from flag, env var, or TTY. Acquires mkdir-based POSIX advisory lock per resource. Dispatches to Nu.
Runtime
Layer
Rust + axum
ontoref-daemonontoref-ontologyontoref-reflectionaxum HTTP APITera templatesMCP serverDashMap cachenotify watcherdrift observersearch enginenotification storeactor registrysession storeSurrealDB (optional)
Optional persistent daemon. Caches nickel export results (path+mtime keyed). Serves HTTP UI (10 pages) + MCP server (19 tools). Actor registry with DashMap sessions. Notification barrier (pre_commit, drift, ontology_drift). Full-text search engine across nodes/ADRs/modes. Never a protocol requirement.
Adoption
Layer
Per-project
templates/ontology/templates/ontoref-config.ncltemplates/scripts-ontorefadopt_ontoref modeONTOREF_PROJECT_ROOT
Each project maintains its own .ontology/ data. One ontoref checkout serves multiple projects via ONTOREF_PROJECT_ROOT. Zero lock-in — files are plain NCL.
Request Flows
CLI path — developer or agent via shell
Actor
developer · agent · CI
→
./ontoref
bash wrapper
→
ontoref.nu
Nu dispatcher
→
daemon
cache / notify
→
nickel export
.ontology/ · adrs/
→
reflection/
qa.ncl · backlog.ncl
MCP / AI agent path — Claude Code or any MCP client
AI Agent
Claude · any MCP client
→
MCP server
stdio · HTTP /mcp
→
19 tools
read · write · query
→
NCL files
git-versioned
Pre-commit barrier — notification-gated commit path
git commit
pre-commit hook fires
→
GET /notifications
/pending?token=X&project=Y
→
pending?
pre_commit · drift · ontology_drift
→
block
until acked in UI / POST /notifications/ack
→
pass
fail-open if daemon unreachable
Daemon Components

HTTP API · /ui/{slug}

  • GET/ui/{slug}/Dashboard — overview, actors, cache stats
  • GET/ui/{slug}/graphD3 ontology graph (nodes by pole, edges)
  • GET/ui/{slug}/searchSearch across nodes/ADRs/modes
  • GET/ui/{slug}/sessionsLive actor registry
  • GET/ui/{slug}/notificationsNotification feed + ack UI
  • GET/ui/{slug}/backlogBacklog with priority/status
  • GET/ui/{slug}/qaQ&A knowledge store
  • GET/ui/{slug}/actionsQuick actions catalog
  • GET/ui/{slug}/modesReflection modes browser
  • GET/ui/{slug}/composeAgent task composer (live sharing)
  • GET/actorsActor sessions list
  • GET/search?q=&project=Search JSON endpoint
  • GET/notifications/pendingPre-commit hook polling
  • POST/notifications/ackAck one or all notifications
  • POST/{slug}/notifications/emitEmit custom notification
  • POST/{slug}/notifications/{id}/actionTrigger notification action
  • POST/compose/sendDispatch mode to ./ontoref server-side
  • POST/actions/runExecute quick action by id
  • POST/qa/addAppend Q&A entry to NCL
  • POST/qa/deleteRemove entry by id
  • POST/qa/updateMutate question + answer
  • GET/qa-jsonExport all Q&A entries
  • POST/backlog/addAdd backlog item
  • POST/backlog/statusUpdate backlog item status
  • GET/backlog-jsonExport backlog as JSON
  • GET/healthCache stats + uptime + SurrealDB status

MCP Server · 19 tools

  • ontoref_help— list all tools and usage
  • ontoref_list_projects— enumerate loaded projects
  • ontoref_set_project— set session default project
  • ontoref_project_status— full project dashboard
  • ontoref_describe— architecture overview
  • ontoref_search— free-text across nodes/ADRs/modes
  • ontoref_get— fetch node by id
  • ontoref_get_node— full ontology node with edges
  • ontoref_list_adrs— list ADRs by status filter
  • ontoref_get_adr— full ADR with constraints
  • ontoref_list_modes— list reflection modes
  • ontoref_get_mode— mode DAG contract
  • ontoref_get_backlog— backlog filtered by status
  • ontoref_backlog— add / update_status
  • ontoref_constraints— all architectural constraints
  • ontoref_qa_list— list Q&A with optional filter
  • ontoref_qa_add— append to reflection/qa.ncl
  • ontoref_action_list— quick actions from config.ncl
  • ontoref_action_add— create mode + register action

Sessions & Actor Registry

  • ActorRegistrybacked by DashMap<String, ActorSession>
  • tokenrandom string, unique per session
  • actor_typedeveloper · agent · CI
  • registered_atISO timestamp, set on registration
  • last_seenupdated on each API call
  • current_modelast active reflection mode
  • serializablesnapshot for disk persistence
  • pre-commit CIregisters as ci actor on hook fire

Compose / Live Sharing

  • /ui/{slug}/composerenders mode form schemas as interactive HTML
  • POST /compose/senddispatches ./ontoref {mode} {params} on server
  • shared contextmultiple actors see same composed task live
  • /ui/{slug}/manageproject registry CRUD (multi-project mode)

Notification Store & Search

  • NotificationStorein-memory queue per (project, token)
  • pre_commitblocks git commits until acked by actor
  • driftschema drift between codebase and ontology
  • ontology_driftfrom passive observer — missing/stale/drift/broken counts
  • fail-openif daemon unreachable, pre-commit hook passes
  • ack workflowPOST /notifications/ack (one or all); action buttons in UI

Search Engine

  • indexesontology nodes (id, name, description)
  • indexesADRs (title, context, decision)
  • indexesreflection modes (name, description, steps)
  • SearchResultkind · id · title · snippet · score
  • used byUI search page + MCP ontoref_search tool

NCL Files — Mutations

  • reflection/qa.nclQaStore — typed entries, git-versioned; written only via crates/ontoref-daemon/src/ui/qa_ncl.rs (ADR-003 hard constraint)
  • reflection/backlog.nclBacklogStore — items with status (Open/InProgress/Done/Cancelled) and priority (Critical/High/Medium/Low)
  • .ontoref/config.nclquick_actions catalog, log level, NATS toggle
  • reflection/modes/*.nclnew mode files created by ontoref_action_add

Drift Observer

  • watchescrates/ · .ontology/ · adrs/ · reflection/modes/
  • debounce15 seconds after last filesystem event
  • runssync scan → sync diff (read-only, never applies changes)
  • emitsontology_drift { missing, stale, drift, broken } to NotificationStore

SurrealDB (optional --db feature)

  • connectionWebSocket to --db-url ws://...; 5s timeout at startup; fail-open
  • seedsontology tables from local NCL files on startup and on file changes (via notify watcher)
  • persistsactor sessions, seeded ontology tables, search index, notification history — survives daemon restarts
  • without --dbDashMap-backed in-memory cache only; process-lifetime; actor sessions and search index are ephemeral
Persistence Tiers

In-Memory — Always Active

DashMap-backed, process-lifetime — no flags required

  • DashMap cache — NCL export results, path+mtime keyed
  • NotificationStore — per (project, token) notification queue
  • ActorRegistry — live session DashMap
  • SessionStore — token → ActorSession map
  • Search index — in-process full-text over loaded NCL data
  • All state is lost on daemon restart
  • Serializable snapshots can be written to disk as JSON/NCL

SurrealDB — Optional --db Flag

WebSocket connection, fail-open — survives daemon restarts

  • Actor sessions — token, type, registered_at, last_seen, mode
  • Seeded ontology tables — nodes, ADRs, modes from NCL files
  • Search index — persisted search index for nodes/ADRs/modes
  • Notification history — acked and dismissed notifications
  • Enabled with --db-url ws://... + --db-namespace
  • If SurrealDB is unreachable at startup, daemon still starts using in-memory tier
Active Constraints (ADR-003 · ADR-002 · ADR-001)
qa-write-via-mutation-module
All mutations to reflection/qa.ncl must go through crates/ontoref-daemon/src/ui/qa_ncl.rs — no direct file writes from other call sites.
qa-schema-typed
reflection/qa.ncl must conform to the QaStore contract from reflection/schemas/qa.ncl — nickel typecheck must pass.
mcp-qa-tools-no-apply-drift
MCP tools ontoref_qa_list and ontoref_qa_add must never trigger sync apply steps or modify .ontology/ files.
protocol-not-runtime (axiom)
ontoref-daemon is optional runtime support — not a protocol requirement. The protocol functions without it. Every module falls back to direct subprocess.
notification-barrier-fail-open
The pre-commit hook must not block git commits when the daemon is unreachable. If GET /notifications/pending fails (connection error, timeout), the hook must pass immediately.
ontology-crate-zero-stratumiops-deps (ADR-001)
ontoref-ontology must never depend on stratum-graph, stratum-state, or stratum-orchestrator. The ontology crate is the protocol's minimal adoption surface and must build standalone.
diff --git a/assets/web/architecture-diagram.html b/assets/web/architecture-diagram.html new file mode 100644 index 0000000..1a03f05 --- /dev/null +++ b/assets/web/architecture-diagram.html @@ -0,0 +1 @@ +Ontoref — Architecture
← Ontoref

Architecture

Protocol layers, runtime components, data flows, persistence tiers, and active constraints — v0.1.0

Protocol Layers
Declarative
Layer
Nickel
.ontology/core.ncl.ontology/state.ncladrs/adr-NNN.nclreflection/schemas/reflection/modes/reflection/forms/reflection/qa.ncl.ontoref/config.ncl
Strong types, contracts, enums. Fails at definition time. No runtime evaluation — nickel export produces JSON consumed by all layers above.
Knowledge
Graph
.ontology/
4 axioms2 tensions12 practicesnodes + edgesinvariantsgatesdimensions
The project knows what it knows. Actor-agnostic. Machine-queryable. ontoref uses its own protocol — the .ontology/ here describes ontoref itself.
Operational
Layer
Nushell
adr.nubacklog.nucoder.nudescribe.nusync.nuconfig.nuregister.nuforms.nu+8 more
Typed Nushell pipelines over structured data — no text streams. 16 modules, each responsible for one operational domain. DAG modes validated before execution.
Entry
Point
Bash → Nu
./ontorefactor detectionadvisory lockingNICKEL_IMPORT_PATH./ontoref -V
Single entry point per project. Detects actor (developer / agent / CI) from flag, env var, or TTY. Acquires mkdir-based POSIX advisory lock per resource. Dispatches to Nu.
Runtime
Layer
Rust + axum
ontoref-daemonontoref-ontologyontoref-reflectionaxum HTTP APITera templatesMCP serverDashMap cachenotify watcherdrift observersearch enginenotification storeactor registrysession storeSurrealDB (optional)
Optional persistent daemon. Caches nickel export results (path+mtime keyed). Serves HTTP UI (10 pages) + MCP server (19 tools). Actor registry with DashMap sessions. Notification barrier (pre_commit, drift, ontology_drift). Full-text search engine across nodes/ADRs/modes. Never a protocol requirement.
Adoption
Layer
Per-project
templates/ontology/templates/ontoref-config.ncltemplates/scripts-ontorefadopt_ontoref modeONTOREF_PROJECT_ROOT
Each project maintains its own .ontology/ data. One ontoref checkout serves multiple projects via ONTOREF_PROJECT_ROOT. Zero lock-in — files are plain NCL.
Request Flows
CLI path — developer or agent via shell
Actor
developer · agent · CI
→
./ontoref
bash wrapper
→
ontoref.nu
Nu dispatcher
→
daemon
cache / notify
→
nickel export
.ontology/ · adrs/
→
reflection/
qa.ncl · backlog.ncl
MCP / AI agent path — Claude Code or any MCP client
AI Agent
Claude · any MCP client
→
MCP server
stdio · HTTP /mcp
→
19 tools
read · write · query
→
NCL files
git-versioned
Pre-commit barrier — notification-gated commit path
git commit
pre-commit hook fires
→
GET /notifications
/pending?token=X&project=Y
→
pending?
pre_commit · drift · ontology_drift
→
block
until acked in UI / POST /notifications/ack
→
pass
fail-open if daemon unreachable
Daemon Components

HTTP API · /ui/{slug}

  • GET/ui/{slug}/Dashboard — overview, actors, cache stats
  • GET/ui/{slug}/graphD3 ontology graph (nodes by pole, edges)
  • GET/ui/{slug}/searchSearch across nodes/ADRs/modes
  • GET/ui/{slug}/sessionsLive actor registry
  • GET/ui/{slug}/notificationsNotification feed + ack UI
  • GET/ui/{slug}/backlogBacklog with priority/status
  • GET/ui/{slug}/qaQ&A knowledge store
  • GET/ui/{slug}/actionsQuick actions catalog
  • GET/ui/{slug}/modesReflection modes browser
  • GET/ui/{slug}/composeAgent task composer (live sharing)
  • GET/actorsActor sessions list
  • GET/search?q=&project=Search JSON endpoint
  • GET/notifications/pendingPre-commit hook polling
  • POST/notifications/ackAck one or all notifications
  • POST/{slug}/notifications/emitEmit custom notification
  • POST/{slug}/notifications/{id}/actionTrigger notification action
  • POST/compose/sendDispatch mode to ./ontoref server-side
  • POST/actions/runExecute quick action by id
  • POST/qa/addAppend Q&A entry to NCL
  • POST/qa/deleteRemove entry by id
  • POST/qa/updateMutate question + answer
  • GET/qa-jsonExport all Q&A entries
  • POST/backlog/addAdd backlog item
  • POST/backlog/statusUpdate backlog item status
  • GET/backlog-jsonExport backlog as JSON
  • GET/healthCache stats + uptime + SurrealDB status

MCP Server · 19 tools

  • ontoref_help— list all tools and usage
  • ontoref_list_projects— enumerate loaded projects
  • ontoref_set_project— set session default project
  • ontoref_project_status— full project dashboard
  • ontoref_describe— architecture overview
  • ontoref_search— free-text across nodes/ADRs/modes
  • ontoref_get— fetch node by id
  • ontoref_get_node— full ontology node with edges
  • ontoref_list_adrs— list ADRs by status filter
  • ontoref_get_adr— full ADR with constraints
  • ontoref_list_modes— list reflection modes
  • ontoref_get_mode— mode DAG contract
  • ontoref_get_backlog— backlog filtered by status
  • ontoref_backlog— add / update_status
  • ontoref_constraints— all architectural constraints
  • ontoref_qa_list— list Q&A with optional filter
  • ontoref_qa_add— append to reflection/qa.ncl
  • ontoref_action_list— quick actions from config.ncl
  • ontoref_action_add— create mode + register action

Sessions & Actor Registry

  • ActorRegistrybacked by DashMap<String, ActorSession>
  • tokenrandom string, unique per session
  • actor_typedeveloper · agent · CI
  • registered_atISO timestamp, set on registration
  • last_seenupdated on each API call
  • current_modelast active reflection mode
  • serializablesnapshot for disk persistence
  • pre-commit CIregisters as ci actor on hook fire

Compose / Live Sharing

  • /ui/{slug}/composerenders mode form schemas as interactive HTML
  • POST /compose/senddispatches ./ontoref {mode} {params} on server
  • shared contextmultiple actors see same composed task live
  • /ui/{slug}/manageproject registry CRUD (multi-project mode)

Notification Store & Search

  • NotificationStorein-memory queue per (project, token)
  • pre_commitblocks git commits until acked by actor
  • driftschema drift between codebase and ontology
  • ontology_driftfrom passive observer — missing/stale/drift/broken counts
  • fail-openif daemon unreachable, pre-commit hook passes
  • ack workflowPOST /notifications/ack (one or all); action buttons in UI

Search Engine

  • indexesontology nodes (id, name, description)
  • indexesADRs (title, context, decision)
  • indexesreflection modes (name, description, steps)
  • SearchResultkind · id · title · snippet · score
  • used byUI search page + MCP ontoref_search tool

NCL Files — Mutations

  • reflection/qa.nclQaStore — typed entries, git-versioned; written only via crates/ontoref-daemon/src/ui/qa_ncl.rs (ADR-003 hard constraint)
  • reflection/backlog.nclBacklogStore — items with status (Open/InProgress/Done/Cancelled) and priority (Critical/High/Medium/Low)
  • .ontoref/config.nclquick_actions catalog, log level, NATS toggle
  • reflection/modes/*.nclnew mode files created by ontoref_action_add

Drift Observer

  • watchescrates/ · .ontology/ · adrs/ · reflection/modes/
  • debounce15 seconds after last filesystem event
  • runssync scan → sync diff (read-only, never applies changes)
  • emitsontology_drift { missing, stale, drift, broken } to NotificationStore

SurrealDB (optional --db feature)

  • connectionWebSocket to --db-url ws://...; 5s timeout at startup; fail-open
  • seedsontology tables from local NCL files on startup and on file changes (via notify watcher)
  • persistsactor sessions, seeded ontology tables, search index, notification history — survives daemon restarts
  • without --dbDashMap-backed in-memory cache only; process-lifetime; actor sessions and search index are ephemeral
Persistence Tiers

In-Memory — Always Active

DashMap-backed, process-lifetime — no flags required

  • DashMap cache — NCL export results, path+mtime keyed
  • NotificationStore — per (project, token) notification queue
  • ActorRegistry — live session DashMap
  • SessionStore — token → ActorSession map
  • Search index — in-process full-text over loaded NCL data
  • All state is lost on daemon restart
  • Serializable snapshots can be written to disk as JSON/NCL

SurrealDB — Optional --db Flag

WebSocket connection, fail-open — survives daemon restarts

  • Actor sessions — token, type, registered_at, last_seen, mode
  • Seeded ontology tables — nodes, ADRs, modes from NCL files
  • Search index — persisted search index for nodes/ADRs/modes
  • Notification history — acked and dismissed notifications
  • Enabled with --db-url ws://... + --db-namespace
  • If SurrealDB is unreachable at startup, daemon still starts using in-memory tier
Active Constraints (ADR-003 · ADR-002 · ADR-001)
qa-write-via-mutation-module
All mutations to reflection/qa.ncl must go through crates/ontoref-daemon/src/ui/qa_ncl.rs — no direct file writes from other call sites.
qa-schema-typed
reflection/qa.ncl must conform to the QaStore contract from reflection/schemas/qa.ncl — nickel typecheck must pass.
mcp-qa-tools-no-apply-drift
MCP tools ontoref_qa_list and ontoref_qa_add must never trigger sync apply steps or modify .ontology/ files.
protocol-not-runtime (axiom)
ontoref-daemon is optional runtime support — not a protocol requirement. The protocol functions without it. Every module falls back to direct subprocess.
notification-barrier-fail-open
The pre-commit hook must not block git commits when the daemon is unreachable. If GET /notifications/pending fails (connection error, timeout), the hook must pass immediately.
ontology-crate-zero-stratumiops-deps (ADR-001)
ontoref-ontology must never depend on stratum-graph, stratum-state, or stratum-orchestrator. The ontology crate is the protocol's minimal adoption surface and must build standalone.
diff --git a/assets/web/architecture.svg b/assets/web/architecture.svg new file mode 100644 index 0000000..7b627e6 --- /dev/null +++ b/assets/web/architecture.svg @@ -0,0 +1,253 @@ + + + + + + + + + + + + + + + + + + + CONSUMER PROJECT + ontoref + · .ontoref/config.ncl · ONTOREF_PROJECT_ROOT + + + + exec · ONTOREF_PROJECT_ROOT + + + + TOOLING LAYER + + + + ./ontoref + bash · actor detection + + + + + + + ontoref.nu + Nushell dispatcher + + + + + + + reflection/modules/ · 16 Nushell modules + adr · backlog · coder · describe · sync · store · services · nats · … + subprocess fallback: direct nickel export when daemon unavailable + + + + RUST CRATES + + + + ontoref-ontology + .ontology/*.ncl → typed Rust structs + + + + ontoref-reflection + load + validate + execute NCL DAG modes + + + + ontoref-daemon + NCL cache · file watcher · actor registry · HTTP + optional + + + + HTTP + + + + + + nickel + export + + + + + + + reads + + + + PROTOCOL LAYER + + ontology/schemas/ + core · gate · state · manifest (NCL defaults) + + + + adrs/ + schema · constraints · lifecycle forms + + + + reflection/schemas/ · modes/ · forms/ + 9 schemas · 10 NCL DAG modes · 7 forms + + + + SELF-DESCRIPTION · .ontology/ + + ontoref consuming its own protocol + + + + core.ncl · state.ncl · gate.ncl · manifest.ncl + + + + 4 axioms · 2 tensions · 9 practices · 19 edges + 3 state dimensions: protocol-maturity · self-description · ecosystem + + + + ADR-001: self-describing axiom in practice + + + + active flow + + + reads / executes + + + optional + + + self-description + + ontoref architecture + diff --git a/assets/web/architecture_0.svg b/assets/web/architecture_0.svg new file mode 100644 index 0000000..7b627e6 --- /dev/null +++ b/assets/web/architecture_0.svg @@ -0,0 +1,253 @@ + + + + + + + + + + + + + + + + + + + CONSUMER PROJECT + ontoref + · .ontoref/config.ncl · ONTOREF_PROJECT_ROOT + + + + exec · ONTOREF_PROJECT_ROOT + + + + TOOLING LAYER + + + + ./ontoref + bash · actor detection + + + + + + + ontoref.nu + Nushell dispatcher + + + + + + + reflection/modules/ · 16 Nushell modules + adr · backlog · coder · describe · sync · store · services · nats · … + subprocess fallback: direct nickel export when daemon unavailable + + + + RUST CRATES + + + + ontoref-ontology + .ontology/*.ncl → typed Rust structs + + + + ontoref-reflection + load + validate + execute NCL DAG modes + + + + ontoref-daemon + NCL cache · file watcher · actor registry · HTTP + optional + + + + HTTP + + + + + + nickel + export + + + + + + + reads + + + + PROTOCOL LAYER + + ontology/schemas/ + core · gate · state · manifest (NCL defaults) + + + + adrs/ + schema · constraints · lifecycle forms + + + + reflection/schemas/ · modes/ · forms/ + 9 schemas · 10 NCL DAG modes · 7 forms + + + + SELF-DESCRIPTION · .ontology/ + + ontoref consuming its own protocol + + + + core.ncl · state.ncl · gate.ncl · manifest.ncl + + + + 4 axioms · 2 tensions · 9 practices · 19 edges + 3 state dimensions: protocol-maturity · self-description · ecosystem + + + + ADR-001: self-describing axiom in practice + + + + active flow + + + reads / executes + + + optional + + + self-description + + ontoref architecture + diff --git a/assets/web/index.html b/assets/web/index.html new file mode 100644 index 0000000..2751bf1 --- /dev/null +++ b/assets/web/index.html @@ -0,0 +1 @@ + Ontoref
Architecture
Protocol + Runtime · v0.1.0
Ontoref — Self-Describing Ontology and Reflection Protocol

Structure that remembers why.

Self-Describing Protocol for
Evolving Codebases

Ontology + Reflection + Daemon + MCP — encode what your codebase IS (invariants, tensions, constraints) and what it DOES (operational modes, actor flows, config seals) in machine-queryable directed acyclic graphs. First-class web UI (10 pages), MCP server (19 tools), and live session sharing for AI agents. One protocol for developers, agents, and CI.
Protocol + Runtime. Zero enforcement.

The 6 Problems It Solves

01

Decisions Without Memory

  • Architectural choices made in chat, forgotten after rotation
  • No machine-queryable source of why something exists
  • ADRs as typed Nickel: invariants, constraints, supersession chain
  • Hard constraints enforced at every operation
02

Invisible Configuration Drift

  • Configs change outside any review cycle
  • No audit trail linking change to PR or ADR
  • Rollback requires manual file archaeology
  • Sealed profiles: sha256 hash, full history, verified rollback
03

Agents Without Context

  • LLMs start each session with zero project knowledge
  • Same mistakes, same questions, no accumulation across operations
  • Actor registry tracks each session token, type, current mode, last seen — persisted to disk
  • MCP tools give agents direct DAG read/write: nodes, ADRs, backlog, Q&A
  • Composed tasks shared via daemon — multiple actors see the same operational context live
04

Scattered Project Knowledge

  • Guidelines in wikis, patterns in docs, decisions in Slack
  • No single source queryable by humans, agents, and CI equally
  • .ontology/ as DAG: nodes, edges, invariants, tensions, gates
  • Same graph serves developer context, agent initialization, CI validation
05

Protocol Fragmentation

  • Each project re-invents its own conventions
  • No shared contract for how operations are defined and executed
  • Reflection modes: typed DAG contracts for any workflow
  • One protocol adopted per-project, without enforcing uniformity
06

Knowledge Lost Between Sessions

  • Q&A answered in one session forgotten by the next
  • Agent re-asks questions already answered in previous sessions
  • Q&A Knowledge Store: typed NCL, git-versioned, persists across browser resets
  • Notification barrier surfaces drift to agents proactively — pre_commit, drift, ontology_drift signals block until acknowledged

Ontology & Reflection — Yin and Yang

Yin — The Ontology Layer

What must be true

  • Invariants — axioms that cannot change without a new ADR
  • Tensions — structural conflicts the project navigates, never resolves
  • Practices — confirmed patterns with artifact paths to real files
  • Gates — membranes controlling readiness thresholds
  • Dimensions — current vs desired state, with transition conditions
  • Q&A Knowledge Store — accumulated Q&A persisted to NCL, git-versioned, queryable by any actor

Yang — The Reflection Layer

How things move and change

  • Modes — typed DAG workflow contracts (preconditions, steps, postconditions)
  • Forms — parameter collection driving modes
  • ADR lifecycle — Proposed → Accepted → Superseded, with constraint history
  • Actors — developer / agent / CI, same protocol, different capabilities
  • Config seals — sha256-sealed profiles, drift detection, rollback
  • Quick Actions — runnable shortcuts over modes; configured in .ontoref/config.ncl
  • Passive Drift Observer — watches code changes, emits ontology_drift notifications with missing/stale/drift/broken counts
Ontology without Reflection = correct but static. Perfect invariants with no operations = dead documentation.
Reflection without Ontology = fluid but unanchored. Workflows that forget what they protect.

The protocol lives in coexistence.

DECLARATIVE LAYER · Nickel
.ontology/ · adrs/ · reflection/schemas/
Strong types, contracts, enums. Fails at definition time, not at runtime.
OPERATIONAL LAYER · Nushell
adr · register · config · backlog · forms · describe
Typed pipelines over structured data. No text streams.
ENTRY POINT · Bash → Nu
ontoref · actor detection · advisory locking · ONTOREF_IMPORT_PATH
Single entry point per project. Detects actor (developer/agent/CI), acquires lock, dispatches to correct Nu module.
KNOWLEDGE GRAPH · .ontology/
nodes · invariants · tensions · gates · dimensions · states
The project knows what it knows. Actor-agnostic. Machine-queryable via nickel export.
RUNTIME LAYER · Rust + axum
ontoref-daemon · ontoref-ontology · ontoref-reflection · search engine · notification barrier · SurrealDB (optional)
Optional persistent daemon. NCL export cache, HTTP UI (10 pages), MCP server (19 tools), actor registry, notification store, search engine, SurrealDB persistence. Never a protocol requirement.
ADOPTION LAYER · Per-project
.ontoref/config.ncl · scripts/ontoref · adopt_ontoref mode
Each project maintains its own .ontology/ data. Ontoref provides the schemas, modules, and migration scripts. Zero lock-in.

Crates & Tooling

🧩

ontoref-ontology

  • Load and query .ontology/ NCL files as typed Rust structs
  • Node, Edge, Dimension, Gate, Membrane types
  • Graph traversal: callers, callees, impact queries
  • Invariant extraction and constraint validation
  • Zero stratumiops dependencies — minimal adoption surface (ADR-001)
🔄

ontoref-reflection

  • Execute reflection modes as typed NCL DAG contracts
  • Step execution with dependency resolution
  • ADR lifecycle: Proposed → Accepted → Superseded
  • Config seal and rollback operations
  • stratum-graph + stratum-state required; platform-nats feature-gated
📜

Nushell Modules

  • store.nu — SurrealDB-backed cache with NCL export
  • sync.nu — ontology code synchronization
  • describe.nu — actor-aware project self-knowledge
  • coder.nu — structured session records
  • 16 modules total — one per operational domain
⚙️

Nickel Schemas

  • Core ontology types: Node, Edge, Pole, AbstractionLevel
  • State machine types: Dimension, Transition, Gate, Membrane
  • ADR schema: Constraint, Severity, Status, supersession
  • Reflection schema: Mode, Step, OnError, Dependency
🖥️

ontoref-daemon · HTTP & UI

  • HTTP UI (axum + Tera): 10 pages — dashboard, D3 graph, search, sessions, notifications, backlog, Q&A, actions, modes, compose
  • Actor registry (DashMap): token, type (developer / agent / CI), registered_at, last_seen, current_mode — serializable snapshot
  • Notification barrier: pre_commit · drift · ontology_drift — pre-commit hook polls & blocks on ack
  • Compose / live sharing: mode forms rendered interactively, ./ontoref dispatched server-side, shared across actors
  • File watcher (notify): passive drift observer, no polling
⚡

ontoref-daemon · MCP & Data

  • MCP server: stdio + streamable-HTTP, 19 tools — nodes, ADRs, modes, backlog, Q&A, sessions, search, notifications
  • Search engine: full-text across nodes / ADRs / reflection modes — returns kind · id · title · snippet · score
  • SurrealDB persistence (optional --db): actor sessions, seeded ontology tables, search index, notification history — fail-open
  • NCL export cache: avoids repeated nickel export on unchanged files
  • db + nats feature flags — builds standalone with --no-default-features

Adopt in Any Project

The adopt_ontoref mode wires up any existing project in one command.

stratumiopsMaster orchestration repo
vaporaAI agent orchestration
kogralKnowledge graph + MCP
syntaxisProject orchestration
provisioningDeclarative IaC
your-projectAny codebase
# Onboard an existing project
./ontorefadopt --project-dir /path/to/my-project --project-name my-project

# Query the project self-knowledge
./scripts/ontoref describe project
./scripts/ontoref describe constraints
./scripts/ontoref describe impact ontology-node-id

# ADR lifecycle
./scripts/ontoref adr new --title "Adopt Nickel for configuration"
./scripts/ontoref adr list --status Accepted

Daemon & MCP — Runtime Intelligence Layer

ontoref-daemon is an optional persistent process. It caches NCL exports, serves 10 UI pages, exposes 19 MCP tools, maintains an actor registry, stores notifications, indexes everything for search, and optionally persists to SurrealDB. It never changes the protocol — it accelerates and shares access to it.

The Web UI — 10 Pages
localhost:7421/ui/{slug}/
DashboardGraphSearchSessionsNotifBacklogQ&AActionsModesCompose
/Dashboardproject overview, actor count, cache stats, notification count, backlog summary
/graphGraphD3 force-directed ontology graph — nodes colored by pole (Yang=orange, Yin=blue, Spiral=purple), clickable with detail panel, edge labels
/searchSearchfull-text search across nodes, ADRs, reflection modes — returns kind/id/title/snippet/score
/sessionsSessionslive actor registry — token, type (developer/agent/CI), registered_at, last_seen, current mode
/notificationsNotificationsnotification feed — pre_commit / drift / ontology_drift; ack/dismiss; emit custom; action buttons
/backlogBacklogitems with priority (Critical/High/Medium/Low) and status (Open/InProgress/Done/Cancelled); add/update
/qaQ&Aserver-hydrated from reflection/qa.ncl; add/edit/delete; persisted as typed NCL
/actionsActionsquick actions catalog from .ontoref/config.ncl; execute via POST /actions/run
/modesModesreflection mode list from reflection/modes/ — name, description, DAG contract
/composeComposeagent task composer — renders mode forms interactively; POST /compose/send dispatches to ./ontoref; live sharing for AI actors
The MCP Server — 19 Tools
ToolDescription
ontoref_helpList available tools and usage
ontoref_list_projectsEnumerate all registered projects
ontoref_set_projectSet session default project context
ontoref_project_statusFull project dashboard — health, drift, actors
ontoref_describeArchitecture overview and self-description
ontoref_searchFree-text search across nodes, ADRs, modes
ontoref_getFetch ontology node by id
ontoref_get_nodeFull ontology node with edges and constraints
ontoref_list_adrsList ADRs filtered by status
ontoref_get_adrFull ADR content with constraints
ontoref_list_modesList all reflection modes
ontoref_get_modeMode DAG contract — steps, preconditions, postconditions
ontoref_get_backlogBacklog items filtered by status
ontoref_backlogAdd or update_status on a backlog item
ontoref_constraintsAll hard + soft architectural constraints
ontoref_qa_listList Q&A knowledge store with optional filter
ontoref_qa_addPersist new Q&A entry to reflection/qa.ncl
ontoref_action_listQuick actions catalog from .ontoref/config.ncl
ontoref_action_addCreate reflection mode + register as quick action

SurrealDB Persistence — Optional

  • Enabled with --db feature flag and --db-url ws://...
  • Connects via WebSocket at startup — 5s timeout, fail-open (daemon runs without it)
  • Seeds ontology tables from local NCL files on startup and on file changes
  • Persists: actor sessions, seeded ontology tables, search index, notification history
  • Without --db: DashMap-backed in-memory, process-lifetime only
  • Namespace configurable via --db-namespace; credentials via --db-username/--db-password

Notification Barrier

  • pre_commit — pre-commit hook polls GET /notifications/pending?token=X&project=Y; blocks git commit until all acked
  • drift — schema drift detected between codebase and ontology
  • ontology_drift — emitted by passive observer with missing/stale/drift/broken counts after 15s debounce
  • Fail-open: if daemon is unreachable, pre-commit hook passes — commits are never blocked by daemon downtime
  • Ack via UI or POST /notifications/ack; custom notifications via POST /{slug}/notifications/emit
  • Action buttons in notifications can link to any dashboard page
# Start the daemon (optional — protocol works without it)
cargo run -p ontoref-daemon -- --config .ontoref/config.ncl
# With SurrealDB persistence
cargo run -p ontoref-daemon -- --db-url ws://localhost:8000 --db-namespace ontoref

# Connect Claude Code via MCP (add to .claude/mcp.json)
{
  "mcpServers": {
    "ontoref": {"type": "http", "url": "http://localhost:7421/mcp"}
  }
}

# Search across ontology nodes, ADRs, and reflection modes
ontoref_search({ q: "notification drift", project: "my-project" })

# Persist a Q&A entry (written to reflection/qa.ncl, git-versioned)
ontoref_qa_add({
  question: "Why does ontoref-ontology have zero stratumiops deps?",
  answer: "ADR-001: minimal adoption surface. Ontology crate must build standalone.",
  tags: ["adr-001", "architecture"]
})

# Check live actor sessions
curl http://localhost:7421/actors
# {"sessions": [{"token": "abc123", "actor_type": "agent", "current_mode": "describe", ...}]}

The UI in Action · Graph View

Force-directed D3 graph of the live ontology. Nodes are typed (Axiom · Tension · Practice) and polarized (Yang · Yin · Spiral). Click any node to open its detail panel — artifacts, connections, NCL source.

Ontoref Graph View — force-directed D3 ontology graph, dark mode
Yang · Axiom
Yin · Tension
Spiral · Practice
Filter buttons · Edge labels · Node detail panel

Technology Stack

Rust Edition 2021NickelNushell 0.111+axumTera TemplatesDashMapnotifyMCP ProtocolD3.jsServer-Sent EventsSurrealDBNATS JetStreamSHA-256 SealsDAG ContractsshellcheckPOSIX Advisory Locks

Protocol Metrics

3 Rust Cratesontology · reflection · daemon
19 MCP ToolsAI agent integration · stdio + HTTP
1 Web UI · 10 Pagesdashboard · graph · search · sessions · notifications · backlog · Q&A · actions · modes · compose
6 Protocol LayersDeclarative → Adoption
1 Search Enginenodes · ADRs · reflection modes
16 Nu ModulesStructured data pipelines
8+ Reflection ModesDAG workflow contracts
3 Actor Typesdeveloper / agent / CI
0 EnforcementVoluntary adoption

Structure That Remembers Why.

Start with adopt_ontoref. Your project gains machine-queryable invariants, living ADRs, actor-aware operational modes, and a daemon that shares context across every actor in real time.

Explore the Protocol
diff --git a/assets/web/minify.sh b/assets/web/minify.sh new file mode 100755 index 0000000..b676990 --- /dev/null +++ b/assets/web/minify.sh @@ -0,0 +1,100 @@ +#!/bin/bash +# Minify HTML files from src/ to production versions +# Usage: ./minify.sh + +set -e + +BASE_DIR="$(dirname "$0")" +FILES=("index.html" "architecture-diagram.html" "architecture-diagram-details.html") + +minify_file() { + local filename="$1" + local SRC_FILE="${BASE_DIR}/src/${filename}" + local OUT_FILE="${BASE_DIR}/${filename}" + local TEMP_FILE="${OUT_FILE}.tmp" + + if [ ! -f "$SRC_FILE" ]; then + echo " Source file not found: $SRC_FILE (skipping)" + return 0 + fi + + echo "" + echo "Minifying ${filename}..." + echo " Input: $SRC_FILE" + echo " Output: $OUT_FILE" + + perl -e " +use strict; +use warnings; + +open(my \$fh, '<', '$SRC_FILE') or die \$!; +my \$content = do { local \$/; <\$fh> }; +close(\$fh); + +# Remove HTML comments +\$content =~ s///gs; + +# Compress CSS (remove spaces and comments) +\$content =~ s/(]*>)(.*?)(<\/style>)/ + my \$before = \$1; + my \$style = \$2; + my \$after = \$3; + \$style =~ s{\/\*.*?\*\/}{}gs; + \$style =~ s{\s+}{ }gs; + \$style =~ s{\s*([{}:;,>+~])\s*}{\$1}gs; + \$before . \$style . \$after; +/gies; + +# Compress JavaScript (remove comments and extra spaces) +\$content =~ s/(]*>)(.*?)(<\/script>)/ + my \$before = \$1; + my \$script = \$2; + my \$after = \$3; + \$script =~ s{\/\/.*\$}{}gm; + \$script =~ s{\s+}{ }gs; + \$script =~ s{\s*([{}();,])\s*}{\$1}gs; + \$before . \$script . \$after; +/gies; + +# Remove whitespace between tags +\$content =~ s/>\s+', '$TEMP_FILE') or die \$!; +print \$out \$content; +close(\$out); +" || { + echo "Minification failed" + rm -f "$TEMP_FILE" + exit 1 + } + + mv "$TEMP_FILE" "$OUT_FILE" + + original=$(wc -c <"$SRC_FILE") + minified=$(wc -c <"$OUT_FILE") + saved=$((original - minified)) + percent=$((saved * 100 / original)) + + echo "" + echo " Compression statistics:" + printf " Original: %6d bytes\n" "$original" + printf " Minified: %6d bytes\n" "$minified" + printf " Saved: %6d bytes (%d%%)\n" "$saved" "$percent" + echo " ${filename} ready for production" +} + +echo "Starting HTML minification..." + +for file in "${FILES[@]}"; do + minify_file "$file" +done + +echo "" +echo "All files minified successfully!" +echo "" diff --git a/assets/web/ontoref-logo.svg b/assets/web/ontoref-logo.svg new file mode 100644 index 0000000..180b071 --- /dev/null +++ b/assets/web/ontoref-logo.svg @@ -0,0 +1,193 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Ontoref + + + Structure that remembers why + + + diff --git a/assets/web/protocol-flow-dark.svg b/assets/web/protocol-flow-dark.svg new file mode 100644 index 0000000..3f2b5f9 --- /dev/null +++ b/assets/web/protocol-flow-dark.svg @@ -0,0 +1,273 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + PROTOCOL LAYERS + + + + + + + + DECLARATIVE · NICKEL + type-safe contracts · fails at definition time + + + .ontology/ + + adrs/*.ncl + + modes/*.ncl + + schemas/*.ncl + + qa.ncl + + config.ncl + + + nickel export → JSON + + + + + KNOWLEDGE GRAPH · .ontology/ + self-describing · actor-agnostic · machine-queryable + + + axioms + + tensions + + practices + + nodes + edges + + invariants + + gates + + + reads KG via nickel export + + + + + OPERATIONAL · NUSHELL + 16 modules · DAG-validated modes · typed pipelines + + + adr.nu + + backlog.nu + + describe.nu + + sync.nu + + coder.nu + + +11 modules + + + dispatches command + actor + + + + + ENTRY POINT · BASH → NU + actor detect · advisory lock · NICKEL_IMPORT_PATH + + + ./ontoref + + actor detect + + advisory lock + + → ontoref.nu + + + optional · caches · serves · never required + + + + + RUNTIME · RUST + axum (optional daemon) + 10 UI pages · 19 MCP tools · actor registry · search · SurrealDB? + + + ontoref-daemon + + axum HTTP + + MCP ×19 + + DashMap + + search + + SurrealDB? + + + configures · ONTOREF_PROJECT_ROOT + + + + + ADOPTION · PER-PROJECT + templates/ · one ontoref checkout · zero lock-in + + + templates/ + + adopt_ontoref + + ONTOREF_PROJECT_ROOT + + zero lock-in + + plain NCL + + + + + + REQUEST FLOWS + + + CLI path — developer · agent · CI + + + + + Actor + dev · agent · CI + + + + + ./ontoref + bash wrapper + + + lock + + + ontoref.nu + Nu dispatcher + + + + + module.nu + adr · backlog · etc + + + export + + + .ontology/ + nickel export + + + + + reflection/ + qa.ncl · backlog + + + + daemon? (optional) + + + MCP path — AI agent · Claude Code · any MCP client + + + AI Agent + Claude · any MCP + + + + + MCP server + stdio · HTTP /mcp + + + + + 19 tools + read · write · query + + + + + NCL files + git-versioned + + + Pre-commit barrier — notification-gated commit path + + + git commit + pre-commit fires + + + + + GET /notify + /pending?token=X + + + + + pending? + + + YES + + + BLOCK + until acked in UI + + + NO — daemon unreachable → fail-open + + + acked + + + PASS ✓ + commit proceeds + + + ontoref v0.1.0 + diff --git a/assets/web/protocol-flow-light.svg b/assets/web/protocol-flow-light.svg new file mode 100644 index 0000000..bff30ef --- /dev/null +++ b/assets/web/protocol-flow-light.svg @@ -0,0 +1,273 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + PROTOCOL LAYERS + + + + + + + + DECLARATIVE · NICKEL + type-safe contracts · fails at definition time + + + .ontology/ + + adrs/*.ncl + + modes/*.ncl + + schemas/*.ncl + + qa.ncl + + config.ncl + + + nickel export → JSON + + + + + KNOWLEDGE GRAPH · .ontology/ + self-describing · actor-agnostic · machine-queryable + + + axioms + + tensions + + practices + + nodes + edges + + invariants + + gates + + + reads KG via nickel export + + + + + OPERATIONAL · NUSHELL + 16 modules · DAG-validated modes · typed pipelines + + + adr.nu + + backlog.nu + + describe.nu + + sync.nu + + coder.nu + + +11 modules + + + dispatches command + actor + + + + + ENTRY POINT · BASH → NU + actor detect · advisory lock · NICKEL_IMPORT_PATH + + + ./ontoref + + actor detect + + advisory lock + + → ontoref.nu + + + optional · caches · serves · never required + + + + + RUNTIME · RUST + axum (optional daemon) + 10 UI pages · 19 MCP tools · actor registry · search · SurrealDB? + + + ontoref-daemon + + axum HTTP + + MCP ×19 + + DashMap + + search + + SurrealDB? + + + configures · ONTOREF_PROJECT_ROOT + + + + + ADOPTION · PER-PROJECT + templates/ · one ontoref checkout · zero lock-in + + + templates/ + + adopt_ontoref + + ONTOREF_PROJECT_ROOT + + zero lock-in + + plain NCL + + + + + + REQUEST FLOWS + + + CLI path — developer · agent · CI + + + + + Actor + dev · agent · CI + + + + + ./ontoref + bash wrapper + + + lock + + + ontoref.nu + Nu dispatcher + + + + + module.nu + adr · backlog · etc + + + export + + + .ontology/ + nickel export + + + + + reflection/ + qa.ncl · backlog + + + + daemon? (optional) + + + MCP path — AI agent · Claude Code · any MCP client + + + AI Agent + Claude · any MCP + + + + + MCP server + stdio · HTTP /mcp + + + + + 19 tools + read · write · query + + + + + NCL files + git-versioned + + + Pre-commit barrier — notification-gated commit path + + + git commit + pre-commit fires + + + + + GET /notify + /pending?token=X + + + + + pending? + + + YES + + + BLOCK + until acked in UI + + + NO — daemon unreachable → fail-open + + + acked + + + PASS ✓ + commit proceeds + + + ontoref v0.1.0 + diff --git a/assets/web/src/architecture-diagram-details.html b/assets/web/src/architecture-diagram-details.html new file mode 100644 index 0000000..6b3b371 --- /dev/null +++ b/assets/web/src/architecture-diagram-details.html @@ -0,0 +1,838 @@ + + + + + + Ontoref — Architecture + + + + +
+ + ← Ontoref +
+ +
+
+

Architecture

+

Protocol layers, runtime components, data flows, persistence tiers, and active constraints — v0.1.0

+
+ + +
Protocol Layers
+
+ +
+
Declarative
Layer
Nickel
+
+
+ .ontology/core.ncl + .ontology/state.ncl + adrs/adr-NNN.ncl + reflection/schemas/ + reflection/modes/ + reflection/forms/ + reflection/qa.ncl + .ontoref/config.ncl +
+
Strong types, contracts, enums. Fails at definition time. No runtime evaluation — nickel export produces JSON consumed by all layers above.
+
+
+ +
+
Knowledge
Graph
.ontology/
+
+
+ 4 axioms + 2 tensions + 12 practices + nodes + edges + invariants + gates + dimensions +
+
The project knows what it knows. Actor-agnostic. Machine-queryable. ontoref uses its own protocol — the .ontology/ here describes ontoref itself.
+
+
+ +
+
Operational
Layer
Nushell
+
+
+ adr.nu + backlog.nu + coder.nu + describe.nu + sync.nu + config.nu + register.nu + forms.nu + +8 more +
+
Typed Nushell pipelines over structured data — no text streams. 16 modules, each responsible for one operational domain. DAG modes validated before execution.
+
+
+ +
+
Entry
Point
Bash → Nu
+
+
+ ./ontoref + actor detection + advisory locking + NICKEL_IMPORT_PATH + ./ontoref -V +
+
Single entry point per project. Detects actor (developer / agent / CI) from flag, env var, or TTY. Acquires mkdir-based POSIX advisory lock per resource. Dispatches to Nu.
+
+
+ +
+
Runtime
Layer
Rust + axum
+
+
+ ontoref-daemon + ontoref-ontology + ontoref-reflection + axum HTTP API + Tera templates + MCP server + DashMap cache + notify watcher + drift observer + search engine + notification store + actor registry + session store + SurrealDB (optional) +
+
Optional persistent daemon. Caches nickel export results (path+mtime keyed). Serves HTTP UI (10 pages) + MCP server (19 tools). Actor registry with DashMap sessions. Notification barrier (pre_commit, drift, ontology_drift). Full-text search engine across nodes/ADRs/modes. Never a protocol requirement.
+
+
+ +
+
Adoption
Layer
Per-project
+
+
+ templates/ontology/ + templates/ontoref-config.ncl + templates/scripts-ontoref + adopt_ontoref mode + ONTOREF_PROJECT_ROOT +
+
Each project maintains its own .ontology/ data. One ontoref checkout serves multiple projects via ONTOREF_PROJECT_ROOT. Zero lock-in — files are plain NCL.
+
+
+ +
+ + +
+
Request Flows
+ + +
CLI path — developer or agent via shell
+
+
+
Actor
+
developer · agent · CI
+
+
→
+
+
./ontoref
+
bash wrapper
+
+
→
+
+
ontoref.nu
+
Nu dispatcher
+
+
→
+
+
daemon
+
cache / notify
+
+
→
+
+
nickel export
+
.ontology/ · adrs/
+
+
→
+
+
reflection/
+
qa.ncl · backlog.ncl
+
+
+ + +
MCP / AI agent path — Claude Code or any MCP client
+
+
+
AI Agent
+
Claude · any MCP client
+
+
→
+
+
MCP server
+
stdio · HTTP /mcp
+
+
→
+
+
19 tools
+
read · write · query
+
+
→
+
+
NCL files
+
git-versioned
+
+
+ + +
Pre-commit barrier — notification-gated commit path
+
+
+
git commit
+
pre-commit hook fires
+
+
→
+
+
GET /notifications
+
/pending?token=X&project=Y
+
+
→
+
+
pending?
+
pre_commit · drift · ontology_drift
+
+
→
+
+
block
+
until acked in UI / POST /notifications/ack
+
+
→
+
+
pass
+
fail-open if daemon unreachable
+
+
+
+ + +
Daemon Components
+
+ + +
+

HTTP API · /ui/{slug}

+
    +
  • GET/ui/{slug}/Dashboard — overview, actors, cache stats
    • +
  • GET/ui/{slug}/graphD3 ontology graph (nodes by pole, edges)
    • +
  • GET/ui/{slug}/searchSearch across nodes/ADRs/modes
    • +
  • GET/ui/{slug}/sessionsLive actor registry
    • +
  • GET/ui/{slug}/notificationsNotification feed + ack UI
    • +
  • GET/ui/{slug}/backlogBacklog with priority/status
    • +
  • GET/ui/{slug}/qaQ&A knowledge store
    • +
  • GET/ui/{slug}/actionsQuick actions catalog
    • +
  • GET/ui/{slug}/modesReflection modes browser
    • +
  • GET/ui/{slug}/composeAgent task composer (live sharing)
    • +
  • GET/actorsActor sessions list
    • +
  • GET/search?q=&project=Search JSON endpoint
    • +
  • GET/notifications/pendingPre-commit hook polling
    • +
  • POST/notifications/ackAck one or all notifications
    • +
  • POST/{slug}/notifications/emitEmit custom notification
    • +
  • POST/{slug}/notifications/{id}/actionTrigger notification action
    • +
  • POST/compose/sendDispatch mode to ./ontoref server-side
    • +
  • POST/actions/runExecute quick action by id
    • +
  • POST/qa/addAppend Q&A entry to NCL
    • +
  • POST/qa/deleteRemove entry by id
    • +
  • POST/qa/updateMutate question + answer
    • +
  • GET/qa-jsonExport all Q&A entries
    • +
  • POST/backlog/addAdd backlog item
    • +
  • POST/backlog/statusUpdate backlog item status
    • +
  • GET/backlog-jsonExport backlog as JSON
    • +
  • GET/healthCache stats + uptime + SurrealDB status
    • +
+
+ + +
+

MCP Server · 19 tools

+
    +
  • ontoref_help — list all tools and usage
    • +
  • ontoref_list_projects — enumerate loaded projects
    • +
  • ontoref_set_project — set session default project
    • +
  • ontoref_project_status — full project dashboard
    • +
  • ontoref_describe — architecture overview
    • +
  • ontoref_search — free-text across nodes/ADRs/modes
    • +
  • ontoref_get — fetch node by id
    • +
  • ontoref_get_node — full ontology node with edges
    • +
  • ontoref_list_adrs — list ADRs by status filter
    • +
  • ontoref_get_adr — full ADR with constraints
    • +
  • ontoref_list_modes — list reflection modes
    • +
  • ontoref_get_mode — mode DAG contract
    • +
  • ontoref_get_backlog — backlog filtered by status
    • +
  • ontoref_backlog — add / update_status
    • +
  • ontoref_constraints — all architectural constraints
    • +
  • ontoref_qa_list — list Q&A with optional filter
    • +
  • ontoref_qa_add — append to reflection/qa.ncl
    • +
  • ontoref_action_list — quick actions from config.ncl
    • +
  • ontoref_action_add — create mode + register action
    • +
+
+ + +
+

Sessions & Actor Registry

+
    +
  • ActorRegistrybacked by DashMap<String, ActorSession>
    • +
  • tokenrandom string, unique per session
    • +
  • actor_typedeveloper · agent · CI
    • +
  • registered_atISO timestamp, set on registration
    • +
  • last_seenupdated on each API call
    • +
  • current_modelast active reflection mode
    • +
  • serializablesnapshot for disk persistence
    • +
  • pre-commit CIregisters as ci actor on hook fire
    • +
+

Compose / Live Sharing

+
    +
  • /ui/{slug}/composerenders mode form schemas as interactive HTML
    • +
  • POST /compose/senddispatches ./ontoref {mode} {params} on server
    • +
  • shared contextmultiple actors see same composed task live
    • +
  • /ui/{slug}/manageproject registry CRUD (multi-project mode)
    • +
+
+ + +
+

Notification Store & Search

+
    +
  • NotificationStorein-memory queue per (project, token)
    • +
  • pre_commitblocks git commits until acked by actor
    • +
  • driftschema drift between codebase and ontology
    • +
  • ontology_driftfrom passive observer — missing/stale/drift/broken counts
    • +
  • fail-openif daemon unreachable, pre-commit hook passes
    • +
  • ack workflowPOST /notifications/ack (one or all); action buttons in UI
    • +
+

Search Engine

+
    +
  • indexesontology nodes (id, name, description)
    • +
  • indexesADRs (title, context, decision)
    • +
  • indexesreflection modes (name, description, steps)
    • +
  • SearchResultkind · id · title · snippet · score
    • +
  • used byUI search page + MCP ontoref_search tool
    • +
+
+ + +
+

NCL Files — Mutations

+
    +
  • reflection/qa.nclQaStore — typed entries, git-versioned; written only via crates/ontoref-daemon/src/ui/qa_ncl.rs (ADR-003 hard constraint)
    • +
  • reflection/backlog.nclBacklogStore — items with status (Open/InProgress/Done/Cancelled) and priority (Critical/High/Medium/Low)
    • +
  • .ontoref/config.nclquick_actions catalog, log level, NATS toggle
    • +
  • reflection/modes/*.nclnew mode files created by ontoref_action_add
    • +
+

Drift Observer

+
    +
  • watchescrates/ · .ontology/ · adrs/ · reflection/modes/
    • +
  • debounce15 seconds after last filesystem event
    • +
  • runssync scan → sync diff (read-only, never applies changes)
    • +
  • emitsontology_drift { missing, stale, drift, broken } to NotificationStore
    • +
+

SurrealDB (optional --db feature)

+
    +
  • connectionWebSocket to --db-url ws://...; 5s timeout at startup; fail-open
    • +
  • seedsontology tables from local NCL files on startup and on file changes (via notify watcher)
    • +
  • persistsactor sessions, seeded ontology tables, search index, notification history — survives daemon restarts
    • +
  • without --dbDashMap-backed in-memory cache only; process-lifetime; actor sessions and search index are ephemeral
    • +
+
+ +
+ + +
Persistence Tiers
+
+
+

In-Memory — Always Active

+

DashMap-backed, process-lifetime — no flags required

+
    +
  • DashMap cache — NCL export results, path+mtime keyed
    • +
  • NotificationStore — per (project, token) notification queue
    • +
  • ActorRegistry — live session DashMap
    • +
  • SessionStore — token → ActorSession map
    • +
  • Search index — in-process full-text over loaded NCL data
    • +
  • All state is lost on daemon restart
    • +
  • Serializable snapshots can be written to disk as JSON/NCL
    • +
+
+
+

SurrealDB — Optional --db Flag

+

WebSocket connection, fail-open — survives daemon restarts

+
    +
  • Actor sessions — token, type, registered_at, last_seen, mode
    • +
  • Seeded ontology tables — nodes, ADRs, modes from NCL files
    • +
  • Search index — persisted search index for nodes/ADRs/modes
    • +
  • Notification history — acked and dismissed notifications
    • +
  • Enabled with --db-url ws://... + --db-namespace
    • +
  • If SurrealDB is unreachable at startup, daemon still starts using in-memory tier
    • +
+
+
+ + +
Active Constraints (ADR-003 · ADR-002 · ADR-001)
+
+
+
qa-write-via-mutation-module
+
All mutations to reflection/qa.ncl must go through crates/ontoref-daemon/src/ui/qa_ncl.rs — no direct file writes from other call sites.
+
+
+
qa-schema-typed
+
reflection/qa.ncl must conform to the QaStore contract from reflection/schemas/qa.ncl — nickel typecheck must pass.
+
+
+
mcp-qa-tools-no-apply-drift
+
MCP tools ontoref_qa_list and ontoref_qa_add must never trigger sync apply steps or modify .ontology/ files.
+
+
+
protocol-not-runtime (axiom)
+
ontoref-daemon is optional runtime support — not a protocol requirement. The protocol functions without it. Every module falls back to direct subprocess.
+
+
+
notification-barrier-fail-open
+
The pre-commit hook must not block git commits when the daemon is unreachable. If GET /notifications/pending fails (connection error, timeout), the hook must pass immediately.
+
+
+
ontology-crate-zero-stratumiops-deps (ADR-001)
+
ontoref-ontology must never depend on stratum-graph, stratum-state, or stratum-orchestrator. The ontology crate is the protocol's minimal adoption surface and must build standalone.
+
+
+ +
+ + + + diff --git a/assets/web/src/architecture-diagram.html b/assets/web/src/architecture-diagram.html new file mode 100644 index 0000000..c078ee5 --- /dev/null +++ b/assets/web/src/architecture-diagram.html @@ -0,0 +1,143 @@ + + + + + + Ontoref — Architecture + + + + + +
+ Ontoref — Protocol Layers & Request Flow (dark) + +
+ + + + diff --git a/assets/web/src/index.html b/assets/web/src/index.html new file mode 100644 index 0000000..39e5829 --- /dev/null +++ b/assets/web/src/index.html @@ -0,0 +1,2010 @@ + + + + + + + Ontoref + + + + + +
+ +
+ + + Architecture + +
+ +
+ +
+ Protocol + Runtime · v0.1.0 +
+ Ontoref — Self-Describing Ontology and Reflection Protocol +
+

+ Structure that remembers why. +

+

+ Self-Describing Protocol for
Evolving Codebases +

+

+ Ontology + Reflection + Daemon + MCP + — encode what your codebase IS (invariants, tensions, constraints) and what it DOES (operational modes, actor flows, config seals) in machine-queryable directed acyclic graphs. First-class web UI (10 pages), MCP server (19 tools), and live session sharing for AI agents. One protocol for developers, agents, and CI. + +
+ + Protocol + Runtime. Zero enforcement. + +

+
+ + +
+

+ The 6 Problems It Solves +

+
+ +
+
01
+

+ Decisions Without Memory +

+
    +
  • Architectural choices made in chat, forgotten after rotation
    • +
  • No machine-queryable source of why something exists
    • +
  • ADRs as typed Nickel: invariants, constraints, supersession chain
    • +
  • Hard constraints enforced at every operation
    • +
+
+ +
+
02
+

+ Invisible Configuration Drift +

+
    +
  • Configs change outside any review cycle
    • +
  • No audit trail linking change to PR or ADR
    • +
  • Rollback requires manual file archaeology
    • +
  • Sealed profiles: sha256 hash, full history, verified rollback
    • +
+
+ +
+
03
+

+ Agents Without Context +

+
    +
  • LLMs start each session with zero project knowledge
    • +
  • Same mistakes, same questions, no accumulation across operations
    • +
  • Actor registry tracks each session token, type, current mode, last seen — persisted to disk
    • +
  • MCP tools give agents direct DAG read/write: nodes, ADRs, backlog, Q&A
    • +
  • Composed tasks shared via daemon — multiple actors see the same operational context live
    • +
+
+ +
+
04
+

+ Scattered Project Knowledge +

+
    +
  • Guidelines in wikis, patterns in docs, decisions in Slack
    • +
  • No single source queryable by humans, agents, and CI equally
    • +
  • .ontology/ as DAG: nodes, edges, invariants, tensions, gates
    • +
  • Same graph serves developer context, agent initialization, CI validation
    • +
+
+ +
+
05
+

+ Protocol Fragmentation +

+
    +
  • Each project re-invents its own conventions
    • +
  • No shared contract for how operations are defined and executed
    • +
  • Reflection modes: typed DAG contracts for any workflow
    • +
  • One protocol adopted per-project, without enforcing uniformity
    • +
+
+ +
+
06
+

+ Knowledge Lost Between Sessions +

+
    +
  • Q&A answered in one session forgotten by the next
    • +
  • Agent re-asks questions already answered in previous sessions
    • +
  • Q&A Knowledge Store: typed NCL, git-versioned, persists across browser resets
    • +
  • Notification barrier surfaces drift to agents proactively — pre_commit, drift, ontology_drift signals block until acknowledged
    • +
+
+ +
+
+ + +
+

+ Ontology & Reflection — Yin and Yang +

+ +
+
+

+ Yin — The Ontology Layer +

+

+ What must be true +

+
    +
  • Invariants — axioms that cannot change without a new ADR
    • +
  • Tensions — structural conflicts the project navigates, never resolves
    • +
  • Practices — confirmed patterns with artifact paths to real files
    • +
  • Gates — membranes controlling readiness thresholds
    • +
  • Dimensions — current vs desired state, with transition conditions
    • +
  • Q&A Knowledge Store — accumulated Q&A persisted to NCL, git-versioned, queryable by any actor
    • +
+
+
+

+ Yang — The Reflection Layer +

+

+ How things move and change +

+
    +
  • Modes — typed DAG workflow contracts (preconditions, steps, postconditions)
    • +
  • Forms — parameter collection driving modes
    • +
  • ADR lifecycle — Proposed → Accepted → Superseded, with constraint history
    • +
  • Actors — developer / agent / CI, same protocol, different capabilities
    • +
  • Config seals — sha256-sealed profiles, drift detection, rollback
    • +
  • Quick Actions — runnable shortcuts over modes; configured in .ontoref/config.ncl
    • +
  • Passive Drift Observer — watches code changes, emits ontology_drift notifications with missing/stale/drift/broken counts
    • +
+
+
+ +
+ Ontology without Reflection = correct but static. Perfect invariants with no operations = dead documentation.
+ Reflection without Ontology = fluid but unanchored. Workflows that forget what they protect. +

+ The protocol lives in coexistence. +

+
+ + +
+
+
+ DECLARATIVE LAYER · Nickel +
+
+ .ontology/ · adrs/ · reflection/schemas/ +
+
+ Strong types, contracts, enums. Fails at definition time, not at runtime. +
+
+
+
+ OPERATIONAL LAYER · Nushell +
+
+ adr · register · config · backlog · forms · describe +
+
+ Typed pipelines over structured data. No text streams. +
+
+
+
+ ENTRY POINT · Bash → Nu +
+
+ ontoref · actor detection · advisory locking · ONTOREF_IMPORT_PATH +
+
+ Single entry point per project. Detects actor (developer/agent/CI), acquires lock, dispatches to correct Nu module. +
+
+
+
+ KNOWLEDGE GRAPH · .ontology/ +
+
+ nodes · invariants · tensions · gates · dimensions · states +
+
+ The project knows what it knows. Actor-agnostic. Machine-queryable via nickel export. +
+
+
+
+ RUNTIME LAYER · Rust + axum +
+
+ ontoref-daemon · ontoref-ontology · ontoref-reflection · search engine · notification barrier · SurrealDB (optional) +
+
+ Optional persistent daemon. NCL export cache, HTTP UI (10 pages), MCP server (19 tools), actor registry, notification store, search engine, SurrealDB persistence. Never a protocol requirement. +
+
+
+
+ ADOPTION LAYER · Per-project +
+
+ .ontoref/config.ncl · scripts/ontoref · adopt_ontoref mode +
+
+ Each project maintains its own .ontology/ data. Ontoref provides the schemas, modules, and migration scripts. Zero lock-in. +
+
+
+
+ + +
+

+ Crates & Tooling +

+
+
+
🧩
+

ontoref-ontology

+
    +
  • Load and query .ontology/ NCL files as typed Rust structs
    • +
  • Node, Edge, Dimension, Gate, Membrane types
    • +
  • Graph traversal: callers, callees, impact queries
    • +
  • Invariant extraction and constraint validation
    • +
  • Zero stratumiops dependencies — minimal adoption surface (ADR-001)
    • +
+
+ +
+
🔄
+

+ ontoref-reflection +

+
    +
  • Execute reflection modes as typed NCL DAG contracts
    • +
  • Step execution with dependency resolution
    • +
  • ADR lifecycle: Proposed → Accepted → Superseded
    • +
  • Config seal and rollback operations
    • +
  • stratum-graph + stratum-state required; platform-nats feature-gated
    • +
+
+ +
+
📜
+

+ Nushell Modules +

+
    +
  • store.nu — SurrealDB-backed cache with NCL export
    • +
  • sync.nu — ontology code synchronization
    • +
  • describe.nu — actor-aware project self-knowledge
    • +
  • coder.nu — structured session records
    • +
  • 16 modules total — one per operational domain
    • +
+
+ +
+
⚙️
+

+ Nickel Schemas +

+
    +
  • Core ontology types: Node, Edge, Pole, AbstractionLevel
    • +
  • State machine types: Dimension, Transition, Gate, Membrane
    • +
  • ADR schema: Constraint, Severity, Status, supersession
    • +
  • Reflection schema: Mode, Step, OnError, Dependency
    • +
+
+ +
+
🖥️
+

+ ontoref-daemon · HTTP & UI +

+
    +
  • HTTP UI (axum + Tera): 10 pages — dashboard, D3 graph, search, sessions, notifications, backlog, Q&A, actions, modes, compose
    • +
  • Actor registry (DashMap): token, type (developer / agent / CI), registered_at, last_seen, current_mode — serializable snapshot
    • +
  • Notification barrier: pre_commit · drift · ontology_drift — pre-commit hook polls & blocks on ack
    • +
  • Compose / live sharing: mode forms rendered interactively, ./ontoref dispatched server-side, shared across actors
    • +
  • File watcher (notify): passive drift observer, no polling
    • +
+
+ +
+
⚡
+

+ ontoref-daemon · MCP & Data +

+
    +
  • MCP server: stdio + streamable-HTTP, 19 tools — nodes, ADRs, modes, backlog, Q&A, sessions, search, notifications
    • +
  • Search engine: full-text across nodes / ADRs / reflection modes — returns kind · id · title · snippet · score
    • +
  • SurrealDB persistence (optional --db): actor sessions, seeded ontology tables, search index, notification history — fail-open
    • +
  • NCL export cache: avoids repeated nickel export on unchanged files
    • +
  • db + nats feature flags — builds standalone with --no-default-features
    • +
+
+
+ + +
+

+ Adopt in Any Project +

+

+ The adopt_ontoref mode wires up any existing project in one command. +

+
+
+ stratumiops + Master orchestration repo +
+
+ vapora + AI agent orchestration +
+
+ kogral + Knowledge graph + MCP +
+
+ syntaxis + Project orchestration +
+
+ provisioning + Declarative IaC +
+
+ your-project + Any codebase +
+
+
+ + +
+ # Onboard an existing project
+ ./ontoref adopt --project-dir /path/to/my-project --project-name my-project
+
+ # Query the project self-knowledge
+ ./scripts/ontoref describe project
+ ./scripts/ontoref describe constraints
+ ./scripts/ontoref describe impact ontology-node-id
+
+ # ADR lifecycle
+ ./scripts/ontoref adr new --title "Adopt Nickel for configuration"
+ ./scripts/ontoref adr list --status Accepted +
+
+ + +
+

+ Daemon & MCP — Runtime Intelligence Layer +

+

+ ontoref-daemon is an optional persistent process. It caches NCL exports, serves 10 UI pages, exposes 19 MCP tools, maintains an actor registry, stores notifications, indexes everything for search, and optionally persists to SurrealDB. It never changes the protocol — it accelerates and shares access to it. +

+ + +
+
+
The Web UI — 10 Pages
+
+
+ + + + localhost:7421/ui/{slug}/ +
+
+ Dashboard + Graph + Search + Sessions + Notif + Backlog + Q&A + Actions + Modes + Compose +
+
+
+ / + Dashboard + project overview, actor count, cache stats, notification count, backlog summary +
+
+ /graph + Graph + D3 force-directed ontology graph — nodes colored by pole (Yang=orange, Yin=blue, Spiral=purple), clickable with detail panel, edge labels +
+
+ /search + Search + full-text search across nodes, ADRs, reflection modes — returns kind/id/title/snippet/score +
+
+ /sessions + Sessions + live actor registry — token, type (developer/agent/CI), registered_at, last_seen, current mode +
+
+ /notifications + Notifications + notification feed — pre_commit / drift / ontology_drift; ack/dismiss; emit custom; action buttons +
+
+ /backlog + Backlog + items with priority (Critical/High/Medium/Low) and status (Open/InProgress/Done/Cancelled); add/update +
+
+ /qa + Q&A + server-hydrated from reflection/qa.ncl; add/edit/delete; persisted as typed NCL +
+
+ /actions + Actions + quick actions catalog from .ontoref/config.ncl; execute via POST /actions/run +
+
+ /modes + Modes + reflection mode list from reflection/modes/ — name, description, DAG contract +
+
+ /compose + Compose + agent task composer — renders mode forms interactively; POST /compose/send dispatches to ./ontoref; live sharing for AI actors +
+
+
+
+ + +
+
The MCP Server — 19 Tools
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolDescription
ontoref_helpList available tools and usage
ontoref_list_projectsEnumerate all registered projects
ontoref_set_projectSet session default project context
ontoref_project_statusFull project dashboard — health, drift, actors
ontoref_describeArchitecture overview and self-description
ontoref_searchFree-text search across nodes, ADRs, modes
ontoref_getFetch ontology node by id
ontoref_get_nodeFull ontology node with edges and constraints
ontoref_list_adrsList ADRs filtered by status
ontoref_get_adrFull ADR content with constraints
ontoref_list_modesList all reflection modes
ontoref_get_modeMode DAG contract — steps, preconditions, postconditions
ontoref_get_backlogBacklog items filtered by status
ontoref_backlogAdd or update_status on a backlog item
ontoref_constraintsAll hard + soft architectural constraints
ontoref_qa_listList Q&A knowledge store with optional filter
ontoref_qa_addPersist new Q&A entry to reflection/qa.ncl
ontoref_action_listQuick actions catalog from .ontoref/config.ncl
ontoref_action_addCreate reflection mode + register as quick action
+
+
+
+ + +
+
+

SurrealDB Persistence — Optional

+
    +
  • Enabled with --db feature flag and --db-url ws://...
    • +
  • Connects via WebSocket at startup — 5s timeout, fail-open (daemon runs without it)
    • +
  • Seeds ontology tables from local NCL files on startup and on file changes
    • +
  • Persists: actor sessions, seeded ontology tables, search index, notification history
    • +
  • Without --db: DashMap-backed in-memory, process-lifetime only
    • +
  • Namespace configurable via --db-namespace; credentials via --db-username/--db-password
    • +
+
+ +
+

Notification Barrier

+
    +
  • pre_commit — pre-commit hook polls GET /notifications/pending?token=X&project=Y; blocks git commit until all acked
    • +
  • drift — schema drift detected between codebase and ontology
    • +
  • ontology_drift — emitted by passive observer with missing/stale/drift/broken counts after 15s debounce
    • +
  • Fail-open: if daemon is unreachable, pre-commit hook passes — commits are never blocked by daemon downtime
    • +
  • Ack via UI or POST /notifications/ack; custom notifications via POST /{slug}/notifications/emit
    • +
  • Action buttons in notifications can link to any dashboard page
    • +
+
+
+ + +
+ # Start the daemon (optional — protocol works without it)
+ cargo run -p ontoref-daemon -- --config .ontoref/config.ncl
+ # With SurrealDB persistence
+ cargo run -p ontoref-daemon -- --db-url ws://localhost:8000 --db-namespace ontoref
+
+ # Connect Claude Code via MCP (add to .claude/mcp.json)
+ {
+   "mcpServers": {
+     "ontoref": { "type": "http", "url": "http://localhost:7421/mcp" }
+   }
+ }
+
+ # Search across ontology nodes, ADRs, and reflection modes
+ ontoref_search({ q: "notification drift", project: "my-project" })
+
+ # Persist a Q&A entry (written to reflection/qa.ncl, git-versioned)
+ ontoref_qa_add({
+   question: "Why does ontoref-ontology have zero stratumiops deps?",
+   answer: "ADR-001: minimal adoption surface. Ontology crate must build standalone.",
+   tags: ["adr-001", "architecture"]
+ })
+
+ # Check live actor sessions
+ curl http://localhost:7421/actors
+ # {"sessions": [{"token": "abc123", "actor_type": "agent", "current_mode": "describe", ...}]} +
+
+ + +
+

+ The UI in Action · Graph View +

+

+ Force-directed D3 graph of the live ontology. Nodes are typed (Axiom · Tension · Practice) and polarized (Yang · Yin · Spiral). Click any node to open its detail panel — artifacts, connections, NCL source. +

+
+ + +
+
+ Ontoref Graph View — force-directed D3 ontology graph, dark mode +
+
+
+
+ Yang · Axiom +
+
+
+ Yin · Tension +
+
+
+ Spiral · Practice +
+
+ Filter buttons · Edge labels · Node detail panel +
+
+
+ + +
+

+ Technology Stack +

+
+ Rust Edition 2021 + Nickel + Nushell 0.111+ + axum + Tera Templates + DashMap + notify + MCP Protocol + D3.js + Server-Sent Events + SurrealDB + NATS JetStream + SHA-256 Seals + DAG Contracts + shellcheck + POSIX Advisory Locks +
+
+ + +
+

+ Protocol Metrics +

+
+
+ 3 Rust Crates + ontology · reflection · daemon +
+
+ 19 MCP Tools + AI agent integration · stdio + HTTP +
+
+ 1 Web UI · 10 Pages + dashboard · graph · search · sessions · notifications · backlog · Q&A · actions · modes · compose +
+
+ 6 Protocol Layers + Declarative → Adoption +
+
+ 1 Search Engine + nodes · ADRs · reflection modes +
+
+ 16 Nu Modules + Structured data pipelines +
+
+ 8+ Reflection Modes + DAG workflow contracts +
+
+ 3 Actor Types + developer / agent / CI +
+
+ 0 Enforcement + Voluntary adoption +
+
+
+ + +
+

+ Structure That Remembers Why. +

+

+ Start with adopt_ontoref. Your project gains machine-queryable invariants, living ADRs, actor-aware operational modes, and a daemon that shares context across every actor in real time. +

+ Explore the Protocol +
+
+ +
+

Ontoref — A Self-Describing Ontology & Reflection Protocol for Evolving Codebases

+

+ Protocol + Runtime. Zero enforcement. One graph per project. +

+
+ + + +