CLAUDE.md

CLAUDE.md

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

Session Start

At the start of every session, check .github/handover.md for active tasks, pending actions, or context from previous sessions. If there are outstanding items, briefly mention them to the user.

Project Overview

Static website for Warsaw Tactical (warsawtactical.com) — a firearms training business in Poland. Built with Jekyll, hosted on GitHub Pages, auto-deploys on push to main.

Development Commands

# Local development (requires Ruby + Bundler)
bundle config set --local path 'vendor/bundle'
bundle install
bundle exec jekyll serve --livereload
# → http://localhost:4000

# Or just push to main — GitHub Pages builds automatically in 1-2 minutes

No npm, no build tools, no linting, no tests. Pure Jekyll + HTML/CSS/JS.

Architecture

Jekyll static site with Liquid templating. All pages are flat HTML files at root level with YAML front matter (layout, title, description, show_announcement).

Template System

• _layouts/default.html — main layout wrapping all pages (includes head, header, content, footer, floating CTA)
• _layouts/post.html — blog post layout with BlogPosting Schema.org JSON-LD, post header (title/date/author), and footer CTA to courses
• _layouts/page.html — minimal page layout
• _includes/head.html — meta tags, analytics scripts, Schema.org structured data (JSON-LD)
• _includes/header.html — navigation with logo
• _includes/footer.html — links, contact, legal
• _includes/announcement-bar.html — dynamic banner loaded from JSON

Data-Driven Content (key pattern)

JSON files in /data/ power dynamic content loaded via vanilla fetch():

• data/courses.json — keyed by course ID (dynamic-pistol, pistol-cqb, close-contact-gunfighter, 2-day-gunfighter). Each entry has arrays of date objects with date, displayDate, slots, status (open/full), stripeLink. Loaded by js/courses.js which renders date cards and “Book now” buttons linking to Tally.so forms.
• data/faqs.json — array of {question, answer} objects (HTML allowed in answers). Loaded by js/faqs.js with two layout modes: “one-column” (course pages) and “two-column” (homepage).
• data/announcement.json — {enabled, text} for the announcement bar.
• data/link-graph.json — internal linking map used by the AI-SEO engine. Contains site_pages (with URLs, titles, types, keywords) and articles (populated as posts are published).

FAQ Dual-Location Sync (critical)

FAQs must be updated in two places simultaneously:

1. data/faqs.json — powers the visible FAQ display
2. _includes/head.html (lines ~73-146) — static Schema.org FAQ markup for Google rich results

Blog System

• Posts in _posts/YYYY-MM-DD-slug.md with Markdown content
• Permalinks: /blog/:title/ (configured in _config.yml)
• Blog listing page at /blog/index.html using site.posts
• Post front matter: layout: post, title, description, date, author, keywords, schema, last_modified_at
• Drafts staged in _drafts/ (not built by Jekyll unless using --drafts flag)

SEO Engine v4 (.github/)

Automated blog article pipeline running on GitHub Actions cron (Mon + Thu 08:00 UTC):

• 3-agent Claude pipeline: Researcher (web search) → SEO Strategist (JSON brief) → Writer (article)
• Single Python script: .github/scripts/publish-article.py
• Prompts in .github/prompts/ (researcher, seo-strategist, writer, seed-document)
• Content queue: data/content-queue.json (22 articles, status-tracked)
• Validation: YAML front matter, word count >1000, keyword in H1, 3+ H2 sections
• Auto-commits queue state on every run (success, skip, or failure)
• Full docs: .github/README.md

Analytics

• Google Analytics 4: G-2N78XX6GZ7 (gtag.js)
• PostHog: phc_1aNmgFdyWFMGadDV0nHTd2SaSYqPTBv7hS5oBkw95nY
• Custom GA4 event: click_ApplyCourse with course name, date, spots left

External Integrations

• Stripe — payment links (stored in courses.json, no SDK)
• Tally.so — booking forms (https://tally.so/r/LZpl5y) with URL parameter pre-fill (?course=&date=)
• Google Fonts — Miriam Libre (headings) + IBM Plex Sans (body)

CSS Conventions

Single file: css/styles.css. Mobile-first with breakpoints at 768px (tablet), 1024px (desktop), and 1440px (large desktop). BEM-inspired class names (.btn, .btn-primary, .btn-secondary, .btn-small). Black/white aesthetic.

Adding a New Page

Create an HTML file at root with front matter:

---
layout: default
title: Page Title
description: Meta description
---
<section>
  <div class="container">...</div>
</section>

Sitemap is auto-generated by the jekyll-sitemap plugin.

Git Conventions

• Commit messages: short, no Co-Authored-By lines
• Push directly to main unless told otherwise

Important Notes

• baseurl in _config.yml must stay empty ("") for the custom domain to work
• Changes to _config.yml require restarting the Jekyll server
• Archived previous “Rogue Methods Europe” branding lives in _archive/
• _config.yml excludes from build: README.md, brief.md, Gemfile*, vendor/, LOCAL-SETUP.md, data/content-queue.json
• SEO engine handover notes live in .github/handover.md — check at session start