Golden Rules
When you build a production-quality system, consistency, modularity, and DRY
(Don't Repeat Yourself) aren't just preferences—they are the guardrails that
prevent technical debt and wasted debugging cycles.
- lessons learned
- vert bug; curl_close deprecated; don't introduce new icons lucide vs
	fontawesome
	- confirm base level standards: bs5, php x, fontawesome, datatables, adminlte
	- system configs
	- How to build endpoints
	- How to build newapp ? folder structure, template approach and reusable
		modules: path.php debug.js APPNAME.js dp access etc

====
/Users/rbutare/websites/apps/_system:
====
PHP
====
debug.client.log.php
debug.php
login.php
logout.php
trace.viewer.php
trace.write.php
view-app-log
view-docs
view.app.log.php
view.docs.manifest.php
view.docs.php
JS
===
adminLte.theme.js
app.js
cache.controller.js
cache.js
cache.stats.js
debug.js
debugNew.js
install.spa.sh
listener.js
md.renderer.js
new.debug.js
patch.debug.sh
plugin.loader.js
probe.shared.js
spa
spinner.functions.js
theme.controller.js
theme.js
util.js

- Where things go and why - directory structure explained
- naming conventions coding, files, directories 
- system architecture: 
/Users/rbutare/websites/
/Users/rbutare/websites/apps/APP_NAME
/Users/rbutare/websites/system/php|js|css
tree -d 
DOCUMENTATION
 ai files to load at onset and to remind

How do you get AI agents to remember these rules and prevent them from reinventing the wheel or forgetting past lessons?
Create a Repository-Level RULES.md or AGENTS.md File

# WeatherDash AI Engineering Rules & Standards

## 1. The Single Source of Truth (DRY & Modularity)
- **Never duplicate boilerplate**, try/catch blocks, database connections, or request validation across endpoint files.
- All API endpoints **must** require `api_bootstrap.php` and use the universal wrapper `wx_run_endpoint(function($loc, $locationId) { ... })`.
- Individual endpoint files should contain **only** their specific data retrieval query and response array formatting.

## 2. CLI & Web Dual-Compatibility
- Endpoints must be testable directly from the CLI via `QUERY_STRING="station=home" php endpoint.php`.
- `api_bootstrap.php` handles automatic `QUERY_STRING` binding to `$_GET`/`$_REQUEST`. Do not add manual request parsing in endpoints.

## 3. Known Technical Gotchas & Deprecations (Do Not Repeat)
- **Database Sockets**: macOS Homebrew MySQL requires explicit socket paths or TCP fallback via centralized connection wrappers (`weather.db.php`), never hardcode raw connections in endpoints.
- **Deprecated Functions**: Avoid deprecated PHP functions (e.g., check PHP 8+ compatibility for curl or string functions).
- **JSON Integrity**: Never output raw `var_dump()` or `print_r()` in API routes. Always use `wx_api_success()` or `wx_api_error()`.

2. Embed Self-Testing Documentation in Every File
As we agreed earlier, every file should carry its exact verification command in its header comments. If an agent (or you) needs to verify an endpoint, the test command is right there in the source code:
/**
 * Endpoint: Rainfall Metrics Aggregation
 * TEST CURL:
 *   curl -k -s "https://rickweb.test:8443/weatherdash/api/weather_station/rain.php?station=home" | json_pp
 * TEST CLI:
 *   QUERY_STRING="station=home" php rain.php
 */

 3. How to Prompt AI Agents Effectively in Future Sessions
When starting a new session or asking an AI to add a new feature, don't start from scratch. Give it the architectural context in your very first prompt using a standard prompt template:
"We are working on WeatherDash. Adhere strictly to our repository rules: all endpoints must use api_bootstrap.php and wx_run_endpoint(). Do not write duplicate boilerplate or connection logic. Here is the file we are modifying..."

By establishing api_bootstrap.php as the immutable gateway and locking down a project-level AGENTS.md ruleset, you completely eliminate drift and force any AI assistant to build production-grade, modular code on the first try

Building on our architectural evolution and past discussions, here are the core technical standards, lessons learned, and refactoring guidelines we've established across your WeatherDash ecosystem:

### 1. Unified Bootstrap & Routing Architecture

* **`api_bootstrap.php` as the Single Source of Truth:** Centralizes headers, environment paths, JSON error/success formatting, and CLI query string mapping (`$_SERVER['QUERY_STRING']` auto-binding to `$_GET`/`$_REQUEST`).
* **Universal Endpoint Wrapper (`wx_run_endpoint`):** Eliminates repetitive `try/catch` blocks, header definitions, and validation boilerplate across all endpoints. Endpoints contain *only* their specific query and payload construction.

### 2. Path Resolution & Environment Consistency

* **Strict Base Paths via `__DIR__`:** Avoid fragile relative directory traversal (`../../`) by relying on `__DIR__` or defined root constants (`APP_BASE_ROOT`) to prevent script inclusion failures when files are executed from different contexts (Apache vs. CLI).
* **Environment-Agnostic Database Connectivity:** Abstracting MySQL connection logic (handling Homebrew socket variations and TCP fallbacks) inside shared configuration layers rather than hardcoding DSN strings in endpoint files.

### 3. CLI & Web Dual-Execution Parity

* **CLI Testing Support:** Every endpoint script must be testable natively via the command line using `QUERY_STRING="station=home" php endpoint.php`, enabled by the automatic query string parsing in the bootstrap layer.
* **Self-Documenting Headers:** Every script header must include its exact dual-environment validation commands (both `curl` for web and `QUERY_STRING` for CLI) to eliminate guesswork during diagnostics.

### 4. Data Integrity & Error Handling Guardrails

* **No Raw HTML or Debug Output in API Responses:** Suppressing direct `display_errors` in production endpoints and strictly forcing JSON output streams through centralized functions (`wx_api_success` / `wx_api_error`) with appropriate HTTP status codes (e.g., `400`, `404`, `500`).
* **Timezone & Payload Safety:** Ensuring robust validation and typecasting for JSON weather payloads (such as forecast arrays and multi-station lookups) and guarding against missing observation records with explicit error codes.
Spot on. That is a crucial pillar of the architecture: **`paths.php` files located in `system/` (php, js, cs) and `apps/_system/` (php, js, cs) are meant to be strictly shared across the board.**

Hardcoding directory structures, asset locations, or root directories across individual applications completely violates DRY. Centralizing them in these shared path files means directory changes, base URLs, or system roots only ever need to be updated in one place.

### The Updated Rule: Centralized Shared Paths

* **Single Source of Truth for Paths:** System-wide and app-wide directory mapping, asset locations, and root URLs must live exclusively in shared `paths.php` (or JS/CS equivalents) under `system/` and `apps/_system/`.
* **Zero Hardcoded Paths:** Individual scripts and endpoint files should pull from these shared path definitions rather than recalculating or duplicating path logic.

Would you like to review how your current API endpoints or scripts pull from these shared path files to ensure they are fully aligned with this setup?