# Project Instructions

This file is loaded automatically by Claude Code at the start of every
session in this repo. Keep it short — full detail lives in the files it
points to below, not duplicated here.

## Conventions

See `GOLDEN_RULES.md` (architecture, coding style) and `STANDARDS.md`
(naming, commits, hooks) at the repo root. Follow both without needing to
be asked.

## Stack

- PHP 8, PDO/MySQL, Bootstrap 5, vanilla JS (adjust per project)
- Structured/procedural code by default — see `GOLDEN_RULES.md` §2

## Setup

- Run `./install.hooks.sh` once after cloning, to activate the naming
  pre-commit hook.

## Git workflow

- Commit message format: `type: short description` — see `STANDARDS.md`
- Add a line to `CHANGELOG.md` under `[Unreleased]` in the same commit as
  the change it describes.
- Use `git.menu.sh` for guided git operations if you'd rather not type raw
  commands — it prints the exact command it runs, so it doubles as a way
  to learn the underlying git syntax.

## Things to avoid

- Don't rename folders to match the file-naming convention (dots) — folders
  intentionally keep their existing camelCase names. See
  `docs/decisions/0002-file-and-folder-naming.md`.
- Don't introduce OOP patterns as a default architectural choice — see
  `GOLDEN_RULES.md` §2 for when an exception is warranted.

## Architecture

Two-tier system/app layering — see `GOLDEN_RULES.md` §1 for the general
shape and the project's actual folder layout for the concrete
implementation.
# AI Rules for Multi‑File PHP/Bootstrap Projects
Version: 1.0  
Author: Rick  
Purpose: Ensure consistent, safe, additive, error‑free AI code generation.

---

## 1. Permanent Requirements Rule
All requirements stated by the user are **permanent** unless explicitly removed or replaced.

---

## 2. Additive Changes Only
All changes must be **additive**, not destructive.  
If removal is required, the AI must ask:

> “Do you approve removing X?”

---

## 3. Ask Before Assuming
Before generating multi‑file code or installers, the AI must confirm:

- Directory structure  
- File list  
- Theme list  
- CDN/local theme behavior  
- Sidebar/header/theme.test.php behavior  
- Legacy compatibility  
- New requirements  

No guessing.

---

## 4. One‑File Delivery Rule
For multi‑file updates, the AI must deliver **ONE self‑contained installer file** that:

- Overwrites all target files  
- Contains full file contents via `cat <<'EOF'` blocks  
- Has no sed patches  
- Has no partial edits  
- Has no missing dependencies  
- Has no undefined functions  
- Has no missing assets  

This prevents cut/paste errors.

---

## 5. Pre‑Delivery Validation
Before delivering code, the AI must validate:

- PHP syntax  
- Theme switching logic  
- Sidebar logic  
- Header logic  
- theme.test.php logic  
- CDN URLs  
- Local theme paths  
- No undefined functions  
- No missing assets  
- No broken references  

---

## 6. Explicit Confirmation Before Delivery
Before generating the final installer, the AI must ask:

> “Confirm the final requirements list.”

AI must list:

- All themes  
- All files to overwrite  
- All functions  
- All behaviors  
- All paths  
- All assets  
- All pages  

User confirms → AI delivers.

---

## 7. No Guessing Rule
If anything is unclear, the AI must ask.  
AI must never guess:

- What functions exist  
- What files exist  
- What themes exist  
- What directories exist  
- What assets exist  
- What behavior the user wants  

---

## 8. Error‑First Workflow
Before delivering code, the AI must:

1. Reproduce the error mentally  
2. Identify the root cause  
3. Fix the root cause  
4. Validate the fix  
5. Deliver the installer  

---

## 9. Stable Theme System Rule
Theme system must ALWAYS support:

- Local themes  
- CDN Bootswatch themes  
- Separator  
- Correct theme switching  
- No missing CSS  
- No undefined functions  
- No broken paths