# Working Environment Guide

## Goal
Keep development consistent across contributors and reduce environment-related defects.

## Local Development Requirements
1. PHP 8.1+ recommended.
2. Modern browser with DevTools.
3. Internet access for CDN dependencies.
4. Code editor with PHP and JavaScript linting support.

## Suggested Local Run
1. Run from project root with PHP built-in server:
   - `php -S 127.0.0.1:8080`
2. Open in browser:
   - `http://127.0.0.1:8080/templ.php?page=mainContent`

## Recommended Editor Setup
1. Enable format-on-save for consistency.
2. Enable trailing whitespace trimming.
3. Use LF line endings.
4. Use UTF-8 encoding.
5. Enable PHP diagnostics and JavaScript diagnostics.

## Branching And Reviews
1. Use feature branches named by intent.
2. Keep PRs small and scoped.
3. Include testing notes and screenshots for UI changes.
4. Link relevant docs updates in PR description.

## Project Conventions
1. Keep page fragments free of html/head/body wrappers.
2. Register new pages in route allow-list.
3. Match `data-page` values to route keys exactly.
4. Keep naming consistent across route key, label, and title.

## Troubleshooting
1. If icons fail: verify Font Awesome link and browser network response.
2. If AJAX nav fails: verify `templ.php?page=<key>&ajax=1` returns fragment.
3. If charts fail: check Chart.js CDN loading and console errors.
4. If sidebar behavior is odd: clear localStorage key `sidebar-mini`.