kogral/assets/web/README.md

# KOGRAL Web Assets

Web-based landing page and static content for KOGRAL.

## Directory Structure

```text
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`:

```bash
# 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`:

```bash
# 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:

```bash
# 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`:

```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

```bash
# 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)