kogral/assets/web/README.md

KOGRAL Web Assets

Web-based landing page and static content for KOGRAL.

Directory Structure

assets/web/
├── src/
│   ├── index.html        # Source HTML (readable)
│   └── kogral.svg        # Logo for landing page
├── index.html            # Minified/Production HTML
├── kogral.svg            # Logo for landing page
├── minify.sh             # Minification script
└── README.md             # This file

Files

src/index.html - Source Version

• Purpose: Development and maintenance
• Content:
  • Full formatting and indentation
  • Inline CSS and JavaScript
  • Bilingual (English/Spanish) content
  • Language-aware dynamic switching
  • Knowledge graph showcase
  • Technology stack display
  • Core components grid

Use for:

• Editing content
• Understanding structure
• Version control
• Making translation updates

index.html - Production Version

• Purpose: Served to browsers (fast loading)
• Optimizations:
  • Removed all comments
  • Compressed CSS (removed spaces, combined rules)
  • Minified JavaScript (single line)
  • Removed whitespace between tags
  • Preserved all functionality

Use for:

• Production web server
• CDN distribution
• Browser caching
• Fast load times

kogral.svg - Logo

• Purpose: Landing page branding
• Source: Copy of ../logos/kogral-h.svg (horizontal logo)
• Dimensions: 610×200px (viewBox 0 0 610 200)
• Features: Animated knowledge graph nodes, connections, and text

How to Use

Development

Edit src/index.html:

# Edit source file
nano assets/web/src/index.html

# Regenerate minified version (see below)
./assets/web/minify.sh

Update Minified Version

When you update src/index.html, regenerate index.html:

# Using minify.sh script
cd /path/to/kogral
./assets/web/minify.sh

# Or manually
cd /path/to/kogral
perl -e '
use strict;
use warnings;

open(my $fh, "<", "assets/web/src/index.html") or die $!;
my $content = do { local $/; <$fh> };
close($fh);

# Remove comments
$content =~ s/<!--.*?-->//gs;

# Compress whitespace in style tags
$content =~ s/(<style[^>]*>)(.*?)(<\/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 whitespace in script tags
$content =~ s/(<script[^>]*>)(.*?)(<\/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+</></gs;
$content =~ s/\s+/ /gs;
$content =~ s/^\s+|\s+$//g;

open(my $out, ">", "assets/web/index.html") or die $!;
print $out $content;
close($out);

print "✅ Minified version created\n";
'

Deployment

Serve index.html from your web server:

# Using Rust
cargo install static-web-server
static-web-server -d assets/web/

# Using Python
python3 -m http.server --directory assets/web

# Using Node.js
npx http-server assets/web

# Using nginx
# Point root to assets/web/
# Serve index.html as default

Features

Responsive Design

• Mobile-first approach
• Flexbox and Grid layouts
• Media queries for mobile
• Touch-friendly navigation

Performance

• Inline CSS (no separate requests)
• Inline JavaScript (no blocking external scripts)
• Minimal dependencies (no frameworks)
• Optimized minified size

Bilingual

• English and Spanish
• LocalStorage persistence
• Data attributes for translations
• Dynamic language switching

Modern CSS

• CSS Gradients
• Animations (fadeInUp)
• Hover effects
• Grid and Flexbox layouts

Styling

• KOGRAL color scheme (Blue #4a9eff, Green #3dd68d, Gold #fbbf24)
• Gradient backgrounds
• Inter font family
• Smooth transitions

Content Sections

1. Hero - Title, tagline, logo, version badge
2. Problems - 4 knowledge management problems KOGRAL solves
   • Scattered documentation
   • No version control for decisions
   • Lost context over time
   • Isolated team knowledge
3. How It Works - Feature overview (Markdown-native, Semantic Search, Config-driven, Claude Code)
4. Technology Stack - Tech badges (Rust, Nickel, SurrealDB, fastembed, MCP, Logseq, etc.)
5. Core Components - Component showcase (kogral-core, kogral-cli, kogral-mcp, etc.)
6. CTA - Call-to-action button linking to GitHub
7. Footer - Credits and tagline

Translations

All text content is bilingual. Edit data attributes in src/index.html:

<!-- English/Spanish example -->
<span data-en="Knowledge Graphs" data-es="Grafos de Conocimiento">Knowledge Graphs</span>

The JavaScript automatically updates based on selected language.

Color Scheme

KOGRAL branding colors:

• Primary Blue: #4a9eff - Main brand color
• Secondary Green: #3dd68d - Highlights and active states
• Gold Accent: #fbbf24 - Gradient accents
• Slate: #64748b - Secondary text
• Dark Background: #0a0a14 - Main background

Maintenance

• Source edits go in src/index.html
• Regenerate index.html when source changes
• Both files are versioned in git
• Keep them in sync

Git Workflow

# Edit source
nano assets/web/src/index.html

# Regenerate minified version
./assets/web/minify.sh

# Commit changes
git add assets/web/src/index.html
git add assets/web/index.html
git commit -m "Update landing page content"
git push

File Sizes

Source and production versions:

File	Type
src/index.html	Source (readable, formatted)
index.html	Production (minified, optimized)
kogral.svg	~15KB (animated horizontal logo)

Version Information

• Last Updated: 2026-01-23
• Version: 0.1.0
• Format: HTML5 + CSS3 + ES6
• Compatibility: All modern browsers
• Languages: English, Spanish

Technology Focus

KOGRAL landing page emphasizes:

• 📝 Git-native knowledge management
• 🔍 Semantic search with embeddings
• ⚙️ Config-driven architecture (Nickel)
• 🤖 Claude Code integration (MCP)
• 📊 6 node types, 6 relationships
• 🗄️ Multi-backend storage (Filesystem, SurrealDB, Memory)

Features Highlighted

4 Core Problems Solved

1. Scattered Documentation - Unifies notes, decisions, guidelines across tools
2. No Version Control - Git-tracked ADRs with full history
3. Lost Context - Semantic search and relationship tracking
4. Isolated Knowledge - Multi-graph architecture with inheritance

How It Works

1. Markdown-Native - YAML frontmatter, wikilinks, code references
2. Semantic Search - Vector embeddings, local or cloud
3. Config-Driven - Nickel schemas, 3 modes (dev/prod/test)
4. Claude Code - MCP server with 7 tools, 6 resources, 2 prompts

Technology Stack

• Rust Edition 2021
• Nickel Config
• SurrealDB
• fastembed (local embeddings)
• rig-core (cloud embeddings)
• MCP Protocol
• Logseq Compatible
• Nushell Scripts

Core Components

• kogral-core - Core library
• kogral-cli - 13 commands
• kogral-mcp - MCP server
• Config System - Nickel schemas
• 3 Storage Backends - Filesystem, SurrealDB, Memory
• 2 Embedding Providers - FastEmbed, rig-core
• 6 Node Types - Note, Decision, Guideline, Pattern, Journal, Execution
• 6 Relationships - relates_to, depends_on, implements, extends, supersedes, explains

Quality Metrics

• 3 Rust crates
• 56 tests passing
• 15K lines of code
• 0 unsafe blocks
• 100% documentation coverage
• 0 clippy warnings

---

Last Updated: 2026-01-23 Version: 0.1.0 (matches KOGRAL release)