AGENTS.md

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

Build and Development Commands

npm install          # install dependencies
npm start            # build + watch + serve at http://localhost:8080
npm run build        # production build → _site/

No linter or test suite is configured.

Architecture

This is a static marketing site for Arcus, built with Eleventy (11ty) 3.x and served by Caddy on an EC2 instance. No Node.js runs in production — Caddy serves the _site/ directory as static files.

How pages work

Every page is an HTML file with YAML front matter. Eleventy stamps each page into _includes/base.njk (the single shared layout providing <head>, nav, footer, fonts, CSS, JS) and outputs static HTML to _site/.

Front matter convention:

---
layout: base.njk
title: "Page title"
description: "Meta description"
navStyle: solid        # omit on homepage; "solid" on inner pages
permalink: /page.html  # explicit output path
---

navStyle: solid sets data-nav-style="solid" on <body>, giving inner pages a permanent nav border instead of the scroll-triggered one on the homepage.

Key files

_includes/base.njk — the only layout; nav and footer live here exclusively
css/arcus.css — all styles in one file; uses CSS custom properties for design tokens (colors: --ink, --paper, --accent; fonts: --serif EB Garamond, --mono JetBrains Mono, --sans DM Sans); responsive breakpoints at 768px and 480px
js/arcus.js — vanilla JS IIFE handling nav scroll border, section anchor navigation, and reveal-on-scroll (IntersectionObserver adds .visible to .reveal elements)
.eleventy.js — config: passthrough copies css/, js/, favicon.ico, arcus.logo.jpeg; input is repo root, output is _site/

Blog posts

Blog posts live in blog/*.html with the same front matter pattern. The blog index (blog-index.html) is hand-maintained — new posts must be manually added as <a class="blog-post-card"> entries.

Contact form

The contact form on /schedule-consult.html uses Web3Forms (no backend). It POSTs to https://api.web3forms.com/submit via client-side fetch().

Deployment

Manual process on the production server:

cd /root/deploy/website
git pull upstream main
rm -rf _site        # Eleventy never deletes outputs for moved/removed pages;
npm run build       # a stale copy of a gated /private/ page would stay public

Caddy picks up the new _site/ immediately — no reload needed.

Private pages

Pages with a /private/... permalink are gated behind Google SSO (restricted to @arcusx.ai accounts) by the Caddyfile in this repo — see docs/private-sso-runbook.md for the OAuth client, custom Caddy build (xcaddy build --with github.com/greenpau/caddy-security), and .env setup. docs/ is excluded from the Eleventy build via .eleventyignore.