CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a Jekyll-based static website for Medulla Labs, deployed via GitHub Pages. The site uses the Minimal Mistakes remote theme.

Development Commands

Local Development

# Install dependencies
bundle install

# Run local development server
bundle exec jekyll serve

# Site will be available at http://localhost:4000

Architecture

Site Structure

• _config.yml: Main Jekyll configuration file containing site metadata, theme settings, plugins, and default values for posts and pages
• _pages/: Static pages (About, Home/Index) with front matter defining layout and permalink
• _posts/: Blog posts following Jekyll naming convention YYYY-MM-DD-title.md
• assets/images/: Image assets including logo and splash images
• _site/: Generated static site (git-ignored, auto-generated by Jekyll)

Theme Configuration

The site uses remote_theme: "mmistakes/minimal-mistakes@4.24.0" which means:

• Theme files are not stored locally in the repository
• Theme customization is done through _config.yml settings
• To override theme defaults, create corresponding files locally (e.g., _layouts/, _includes/)

Content Front Matter

Pages and posts use YAML front matter. Key fields:

• layout: Determines page template (e.g., single, home)
• permalink: Custom URL path for pages
• title: Page/post title
• author_profile: Shows/hides author sidebar
• header: Configuration for overlay images and CTAs

Deployment

Deployment is automated via GitHub Actions (.github/workflows/jekyll-gh-pages.yml):

• Triggers on pushes to main branch
• Uses GitHub’s native Jekyll build action
• Deploys to GitHub Pages at https://medullalabs.io
• No manual deployment steps required

Jekyll Conventions

• Posts must be named: YYYY-MM-DD-title.md in _posts/
• Pages go in _pages/ with permalink defined in front matter
• All Markdown files require front matter (even if just --- delimiters)

Current Implementation (v1.0.0)

Design System

• Color Scheme: Blue gradient system (#0066cc, #004d99, #3399ff, #00ccff)
• Typography: Inter (headings), Open Sans (body), Fira Code (code)
• Theme Skin: “air” - clean, professional appearance
• Styling: Custom CSS in assets/css/main.scss with gradients and hover effects

Pages

• Homepage (/): Splash layout with hero and 3 feature cards
• Services (/services/): 4 core offerings with anchor links (infrastructure, agentic-ai, analytics, validator)
• About (/about/): Company info, mission, Cyprus jurisdiction
• Team (/team/): Founder profiles and philosophy
• Contact (/contact/): FormSubmit contact form
• Legal Pages (/legal/*):
  • Privacy Policy (GDPR-compliant)
  • Terms of Service (Cyprus jurisdiction)
  • Cookie Policy (detailed cookie usage)
  • Accessibility Statement (WCAG 2.1 AA)

GDPR Compliance

• Cookie Consent Banner: Pure JavaScript implementation in _includes/cookie-consent.html
• User Controls: Accept/Decline buttons with 365-day persistence
• Conditional Analytics: Google Analytics only loads with consent
• Legal Framework: Full privacy policy with GDPR rights
• Footer Links: All legal pages linked in footer

Voice and Content Guidelines

• Tone: Calm approachable authority - professional but accessible
• Focus: Technical substance over hype
• Avoid: Crypto buzzwords, overpromises, superlatives
• Emphasize: Production systems, reliability, operational excellence

Assets

• Logo: /assets/images/logo.svg
• Splash: /assets/images/splash.svg
• Service icons needed (placeholders): infrastructure-icon.svg, agentic-icon.svg, analytics-icon.svg
• Team photos: /assets/images/team/bob.jpg (placeholder)

Forms

• Contact form uses FormSubmit (https://formsubmit.co/contact@medullalabs.io)
• No backend required
• Service interest dropdown included

Legal & Compliance Notes

• Company: Medulla Labs Limited, Cyprus
• GDPR compliance via cookie consent and privacy policy
• All legal pages completed and cross-referenced
• Email addresses: contact@, privacy@, gdpr@, legal@, support@, careers@medullalabs.io

Agents for Repository Management

This repository uses specialized agents to handle different aspects of site management. Each agent has specific expertise and responsibilities.

Available Agents

content-editor - Content updates and blog management

• Use for: Updating page content, creating blog posts, editing copy
• Expertise: Markdown, Jekyll front matter, content guidelines
• Command: Invoke when editing content in _pages/ or _posts/

legal-compliance - Legal page reviews and updates

• Use for: Updating privacy policy, terms, cookie policy, accessibility
• Expertise: GDPR compliance, legal language, Cyprus jurisdiction
• Command: Invoke when modifying files in _pages/legal/

asset-manager - Image and asset management

• Use for: Adding/optimizing images, managing icons, fonts
• Expertise: Image optimization, SVG creation, asset organization
• Command: Invoke when working with files in assets/

style-designer - Visual design and CSS updates

• Use for: Updating styles, colors, layouts, responsive design
• Expertise: SCSS, Minimal Mistakes theme customization, CSS
• Command: Invoke when modifying assets/css/main.scss or theme overrides

seo-analytics - SEO optimization and analytics

• Use for: Meta tags, performance, analytics setup, search optimization
• Expertise: Jekyll SEO, Google Analytics, performance optimization
• Command: Invoke for SEO improvements or analytics configuration

deployment-validator - Build verification and deployment checks

• Use for: Pre-deployment testing, build validation, link checking
• Expertise: Jekyll builds, GitHub Actions, deployment verification
• Command: Invoke before pushing to main or when troubleshooting builds

Agent Usage Guidelines

1. Invoke the appropriate agent for the task at hand
2. Provide context about what you’re trying to accomplish
3. Follow agent recommendations for consistency
4. Review changes before committing

When to Use Which Agent

• Changing homepage copy → content-editor
• Adding a new privacy clause → legal-compliance
• Uploading a new hero image → asset-manager
• Adjusting button colors → style-designer
• Improving meta descriptions → seo-analytics
• Verifying build before launch → deployment-validator