From 0052746f331030b0f862539954c90ce385568cb9 Mon Sep 17 00:00:00 2001
From: luinbytes <42706009+luinbytes@users.noreply.github.com>
Date: Sat, 14 Nov 2026 01:18:26 +0000
Subject: [PATCH 1/3] Add AGENTS.md and CLAUDE.md for coding CLIs

---
 AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 48 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b3ad37f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,47 @@
+# luinbytes.dev
+
+## Layout
+- `app/`: application and rendering entries; `components/`: UI components; `lib/`: shared logic.
+- `public/`: static assets; `scripts/`: generation, prerendering, and preview serving.
+- `tests/`: pond Node tests and browser Playwright tests; `review-previews/`: review evidence.
+- Configuration: `site.config.json`, `vite.config.ts`, and `eslint.config.mjs`.
+
+## Setup
+Use Node 22 and a repo-local Python environment for browser tests:
+
+```sh
+npm ci
+python3 -m venv .venv
+.venv/bin/python -m pip install -r requirements-test.txt
+.venv/bin/python -m playwright install --with-deps chromium
+```
+
+## Workflow and completion
+- Work on a task branch; never commit to `master`.
+- Use repo-local environments and dependencies; do not install packages or toolchains globally.
+- Never print, log, or commit secrets, tokens, credentials, or auth-file contents.
+- Before claiming done, run the required checks below from the repo root and report results and any blocked or skipped checks.
+- Timing-sensitive tests must use a handshake or event, never sleep, extra retries, or a longer timeout to make a test pass.
+
+## Required checks
+All required checks must pass:
+
+```sh
+npm audit --audit-level=high
+npm run lint
+npm run test:pond
+PATH="$PWD/.venv/bin:$PATH" npm run test:e2e
+```
+
+`test:e2e` already runs `npm run build` before the Python browser suite; a successful full gate covers the build without repeating it.
+
+## Development and gotchas
+```sh
+npm run dev
+npm run build
+npm run preview
+```
+
+The build runs TypeScript checking, Vite client/SSR builds, and prerendering. Preview serves `out/` at http://127.0.0.1:3004 with real 404 responses; browser tests use this production export.
+
+The default branch is `master`. Pushes to `master` run checks, then build and deploy to GitHub Pages.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md

From 9a78b476ddc9df9f6a92bcbd6e1ec567799b7b9f Mon Sep 17 00:00:00 2001
From: luinbytes <42706009+luinbytes@users.noreply.github.com>
Date: Sat, 14 Nov 2026 02:13:20 +0000
Subject: [PATCH 2/3] docs: avoid playwright --with-deps and document sitemap
 dirtying

---
 AGENTS.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index b3ad37f..a997ebf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,9 +13,11 @@ Use Node 22 and a repo-local Python environment for browser tests:
 npm ci
 python3 -m venv .venv
 .venv/bin/python -m pip install -r requirements-test.txt
-.venv/bin/python -m playwright install --with-deps chromium
+npx playwright install chromium
 ```
 
+CI's `.github/workflows/checks.yml` uses `--with-deps` to install system packages through sudo apt on the runner. Local/CLI setup must not use `--with-deps`. If Chromium still cannot start because system libraries are missing, those libraries are a host prerequisite; do not install them with sudo or apt as part of repo commands.
+
 ## Workflow and completion
 - Work on a task branch; never commit to `master`.
 - Use repo-local environments and dependencies; do not install packages or toolchains globally.
@@ -44,4 +46,6 @@ npm run preview
 
 The build runs TypeScript checking, Vite client/SSR builds, and prerendering. Preview serves `out/` at http://127.0.0.1:3004 with real 404 responses; browser tests use this production export.
 
+`npm run build` runs `prebuild` (`node scripts/generate-sitemap.js`), which rewrites the `lastmod` values in tracked `public/sitemap.xml`. This also happens during `npm run test:e2e`, since it runs the build. Commit the sitemap change only when the task is to update the sitemap; otherwise, revert it before finishing with `git restore -- public/sitemap.xml`.
+
 The default branch is `master`. Pushes to `master` run checks, then build and deploy to GitHub Pages.

From ed03f611bd15f6afa521bfcf08f19dd1c2035538 Mon Sep 17 00:00:00 2001
From: luinbytes <42706009+luinbytes@users.noreply.github.com>
Date: Sat, 14 Nov 2026 02:44:04 +0000
Subject: [PATCH 3/3] docs: install Playwright browsers with the pinned Python
 package

---
 AGENTS.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index a997ebf..bb92b06 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -13,10 +13,10 @@ Use Node 22 and a repo-local Python environment for browser tests:
 npm ci
 python3 -m venv .venv
 .venv/bin/python -m pip install -r requirements-test.txt
-npx playwright install chromium
+.venv/bin/python -m playwright install chromium
 ```
 
-CI's `.github/workflows/checks.yml` uses `--with-deps` to install system packages through sudo apt on the runner. Local/CLI setup must not use `--with-deps`. If Chromium still cannot start because system libraries are missing, those libraries are a host prerequisite; do not install them with sudo or apt as part of repo commands.
+CI's `.github/workflows/checks.yml` runs the same Python command with the runner-only `--with-deps` addition: `.venv/bin/python -m playwright install --with-deps chromium`. This installs system packages through sudo apt on the runner. Local/CLI setup must not use `--with-deps`. If Chromium still cannot start because system libraries are missing, those libraries are a host prerequisite; do not install them with sudo or apt as part of repo commands.
 
 ## Workflow and completion
 - Work on a task branch; never commit to `master`.