# Working Environment Standard

## Scope
This document defines the expected local setup and environment quality baseline for contributors.

## How To Use This File
1. Use this file when onboarding or troubleshooting local setup.
2. `Must` items are baseline environment requirements.
3. `Should` items are expected consistency improvements.
4. `Could` items are optional local productivity upgrades.

## Must (Environment Baseline)
- [ ] PHP 8.1+ is available locally.
- [ ] A modern browser with DevTools is available.
- [ ] Internet access is available for CDN dependencies.
- [ ] Editor diagnostics for PHP and JavaScript are enabled.
- [ ] LF line endings and UTF-8 encoding are used.

## Should (Consistency Practices)
- [ ] Format-on-save is enabled.
- [ ] Trailing whitespace is trimmed on save.
- [ ] PRs stay scoped and include verification notes.
- [ ] UI changes include screenshots or short visual notes.

## Could (Productivity Enhancements)
- [ ] Add local lint task shortcuts.
- [ ] Add optional browser profile for test isolation.
- [ ] Add pre-commit hooks for docs and style checks.

## Local Run Reference
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`

## 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 network response.
2. If AJAX navigation fails, verify `templ.php?page=<key>&ajax=1` returns a fragment.
3. If charts fail, check Chart.js CDN loading and browser console errors.
4. If sidebar behavior is inconsistent, clear localStorage key `sidebar-mini`.