1 files changed, 49 insertions, 0 deletions
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..2e61988
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,49 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this repo is
+
+Web frontend for `packages.danix.xyz` — an Apache autoindex-based Slackware package repository. Apache serves directory listings; this repo provides the HTML chrome injected around them.
+
+## How header/footer injection works
+
+Apache's `HeaderName` / `ReadmeName` directives (in `.htaccess`) point to `_header.html` and `_footer.html`. These static files are generated by `gen_web_hook.sh`, which walks `$PKGREPO/{category}/{package}/` and writes a pair at each level. Run standalone or as a slackrepo `HOOK_FINISH` hook.
+
+## Repository directory structure (on server)
+
+```
+/var/www/pkgs/          ← REPO_ROOT (depth 0)
+  category/             ← depth 1
+    pkgname/            ← depth 2
+      pkgname-ver.txz
+      pkgname-ver.txt   ← parsed for title/description/Homepage
+      pkgname-ver.meta  ← parsed for compressed/uncompressed sizes
+```
+
+## CSS design system
+
+CSS variables defined on `:root`:
+
+- Colors: `--bg`, `--bg-card`, `--bg-hover`, `--border`, `--accent`, `--accent-dim`, `--accent2`, `--green`, `--text`, `--text-dim`, `--text-head`
+- Fonts: `--mono` (IBM Plex Mono), `--sans` (IBM Plex Sans) — loaded from Google Fonts
+
+## Static assets
+
+`.assets/matrix-rain.js` — matrix rain canvas animation. Served from `$PKGREPO/.assets/`. Loaded via `<script defer>` in every `_header.html`. Hidden from Apache autoindex via `IndexIgnore .assets` in `.htaccess`. When updating, copy the adapted file to `$PKGREPO/.assets/matrix-rain.js` on the server — it is not regenerated by `gen_web_hook.sh`.
+
+## Apache configuration
+
+- `vhost.conf`: VirtualHost for `packages.danix.xyz:443`, DocumentRoot `/var/www/pkgs`, delegates all index config to `.htaccess`
+- `htaccess`: `IndexOptions HTMLTable SuppressHTMLPreamble ...` — `SuppressHTMLPreamble` is critical; it tells Apache not to emit its own `<html>` so our header file controls the full document
+
+## Running the hook
+
+```bash
+# Standalone against a local repo path
+bash gen_web_hook.sh /path/to/pkgrepo
+
+# Via slackrepo (picks up SR_PKGREPO automatically)
+HOOK_FINISH=/path/to/gen_web_hook.sh slackrepo build pkgname
+```
+