#How to load new station?
cd /Users/rbutare/websites/apps/weather_station/weather/
#Run: 
php scripts/weather.location.cli.php add --zip 90210 --nick Beverly Hills

## OUTPUT ###
#Added #27 Bayonne (07002) Bayonne, NJ @ 40.6664,-74.1192
##NWS grid resolved: OKX/30,39, tz America/New_York
#run - Get update to all weather stations: 
php /Users/rbutare/websites/apps/weather_station/weather/scripts/weather.ingest.cli.php
exit
running both of these will get data from nws
Bug
changing station should auto change current content in main.content
need to know what state is content to refresh it with new station id

How to get zip code long/lat
curl -s "https://api.zippopotam.us/us/90210"
#The -k flag tells curl to ignore self-signed SSL certificate warnings if you are running local HTTPS).
curl -k -d "action=lookup&zip=90210" -X POST https://localhost:8443/weatherdash/pages/add.station.php


How to Fix It
To make sure PHP can always find your database connection file regardless of where you execute the script from, define an absolute path using __DIR__:
what does this mean? This ensures that whenever you add or modify stations 
in your database, your frontend dropdown picker (wsUI_updateStations()) will 
automatically receive and display all of them instantly!

- fix config.generator.php - bugs
- create docs: README tasks faq lessonslearned, goldenRulesUpdates, 

XXXX
what is this: How to Download & Manage Your Documentation Package
You can download the generated .zip archive directly via the sandbox link above, or you can generate/manage the files locally using your project workspace tools.
XXXX
Standard Project Documentation Required (docs/)
To keep your application maintainable, secure, and fully auditable, a standard modular documentation structure has been established in your repository:
README.md — Core project overview, architecture breakdown, setup instructions, and entry points.
tasks.md — Active task list, completed milestones, and immediate next steps.
faq.md — Frequently asked questions regarding routing, fragment loading, script execution, and charts.
lessons_learned.md — Technical takeaways (e.g., handling script injection via .innerHTML, configuration syncing).
golden_rules_updates.md — Architectural standards and code style rules for weatherdash.
limitations.md — Known constraints (e.g., browser restrictions on dynamic script execution without manual extraction).
security.md — Input sanitization, database query safety, and API access controls.
testing.md — Unit and integration test procedures, console debugging steps, and browser verification methods.
not_complete.md — Incomplete features and pending integration items.
future_ideas.md — Roadmap items and enhancement suggestions.
admin.Req.md — Administrative requirements & audit protocols (detailed below).
admin.Req.md — Administrative Requirements & Audit Guidelines
Below is the standard specification for your project's administrative auditing and file/directory hygiene requirements:
Markdown
# WeatherDash Administrative Requirements & Audit Protocol (`admin.Req.md`)

## 1. File & Directory Naming Conventions
- **Directories**: Must use lowercase, dash-separated or underscore-separated naming conventions (e.g., `pages/`, `api/weather_station/`, `js/`, `css/`).
- **PHP Fragments**: Must use descriptive lowercase filenames ending in `.php` (e.g., `historical.php`, `settings.php`).
- **JavaScript Modules**: Must be prefixed or grouped logically (e.g., `weather.js`).
- **Prohibited**: Spaces, uppercase letters, or special characters in physical file paths to ensure cross-platform compatibility (macOS, Linux production servers).

## 2. Code Auditing & Compliance
- **Script Execution Auditing**: Any dynamic DOM injection via `loadPage()` must properly inspect and re-evaluate inline `<script>` blocks to comply with browser execution limitations.
- **Configuration Synchronization**: Frontend configurations (`WS_PHP_CONFIG`) must be dynamically populated via database queries rather than hardcoded arrays to prevent stale station lists.
- **Error Handling**: All API fetch operations and asynchronous calls must include `try/catch` blocks with clear console logging prefixed with `[wsDB]`.

## 3. Testing & Verification Standards
- **Console Inspection**: Developers must verify that no uncaught ReferenceErrors or 404 network requests occur during page transitions.
- **Chart Lifecycle Management**: All Chart.js instances must verify existing canvas state and call `.destroy()` prior to re-initialization to prevent memory leaks and canvas overlap bugs.
- **Dependency Checks**: CDN dependencies (such as Chart.js and Lucide icons) must be verified for version compatibility and fallback behavior.
XXXX
# WeatherDash Administrative Requirements & Audit Protocol (`admin.Req.md`)

## 1. File & Directory Naming Conventions
- **Directories**: Must use lowercase, dash-separated or underscore-separated naming conventions (e.g., `pages/`, `api/weather_station/`, `js/`, `css/`).
- **PHP Fragments**: Must use descriptive lowercase filenames ending in `.php` (e.g., `historical.php`, `settings.php`).
- **JavaScript Modules**: Must be prefixed or grouped logically (e.g., `weather.js`).
- **Prohibited**: Spaces, uppercase letters, or special characters in physical file paths to ensure cross-platform compatibility (macOS, Linux production servers).

## 2. Code Auditing & Compliance
- **Script Execution Auditing**: Any dynamic DOM injection via `loadPage()` must properly inspect and re-evaluate inline `<script>` blocks to comply with browser execution limitations.
- **Configuration Synchronization**: Frontend configurations (`WS_PHP_CONFIG`) must be dynamically populated via database queries rather than hardcoded arrays to prevent stale station lists.
- **Error Handling**: All API fetch operations and asynchronous calls must include `try/catch` blocks with clear console logging prefixed with `[wsDB]`.

## 3. Testing & Verification Standards
- **Console Inspection**: Developers must verify that no uncaught ReferenceErrors or 404 network requests occur during page transitions.
- **Chart Lifecycle Management**: All Chart.js instances must verify existing canvas state and call `.destroy()` prior to re-initialization to prevent memory leaks and canvas overlap bugs.
- **Dependency Checks**: CDN dependencies (such as Chart.js and Lucide icons) must be verified for version compatibility and fallback behavior.
XXXX
XXXX
XXXX
XXXX
XXXX
#Get Coordinates
#https://tooltrio.com/zip/zip-to-coordinates
Coding golden rule: 
Centralizing request parsing, validation, and headers into a single shared 
bootstrap file is the exact right architectural pattern. It enforces 
DRY (Don't Repeat Yourself), makes CLI testing seamless, and ensures all
endpoints behave identically under strict validation.
- What is the document flow of applications? files and order that are required:
	paths db config env etc
	How to add assets like ? css and js in config files How to make sure order
	dependency are followed
	What is the best way to test end points since the do not run from cli? curl
	options

1. GET vs. POST for Weather Data APIs
REST Best Practice: Retrieving weather conditions, forecasts, and alerts is safe, read-only, and idempotent. Therefore, GET is standard for these endpoints.
Security & Flexibility ($_REQUEST): To give you the best of both worlds (easy browser/curl testing via query strings and protection/flexibility if you ever want to post data), your API endpoints should read parameters using $_REQUEST instead of strictly $_GET. $_REQUEST automatically checks both $_GET and $_POST, meaning your endpoints can accept either method without changing code.

structure of apps
/Users/rbutare/websites/apps/weatherdash
=== APPNAME.index.php
- weatherdash.index.php (setup paths, env etc) no html

<?php
declare(strict_types=1);

const SYSTEM_ROOT = '/Users/rbutare/websites/system';
const APP_NAME = 'weatherdash';

// 1. Load System Bootstrap & Paths
$bootstrapFile = SYSTEM_ROOT . '/php/bootstrap.php';
if (!is_file($bootstrapFile) || !is_readable($bootstrapFile)) {
    throw new RuntimeException('System bootstrap error: ' . $bootstrapFile);
}
require_once $bootstrapFile;
bootstrap_app();

// Ensure _system/paths.php is loaded if available in your system architecture
$systemPaths = SYSTEM_ROOT . '/_system/paths.php';
if (is_file($systemPaths)) {
    require_once $systemPaths;
}

// 2. Define Helper Functions
if (!function_exists('include_if_exists')) {
    function include_if_exists(string $file): void {
        if (is_file($file) && is_readable($file)) {
            require $file;
        }
    }
}

if (!function_exists('versioned_system_asset_url')) {
    function versioned_system_asset_url(string $path): string {
        $file = dirname(__DIR__) . DIRECTORY_SEPARATOR . '_system' . DIRECTORY_SEPARATOR . str_replace('/', DIRECTORY_SEPARATOR, ltrim($path, '/'));
        if (!is_file($file) || !is_readable($file)) {
            throw new RuntimeException('Missing public system asset: ' . $file);
        }
        $hash = hash_file('sha256', $file);
        $url = system_asset_url($path);
        return $url . (str_contains($url, '?') ? '&' : '?') . 'v=' . substr($hash, 0, 12);
    }
}

$includesDir = __DIR__ . DIRECTORY_SEPARATOR;
$runtimeConfig = [
    'app'             => APP_NAME,
    'traceEndpoint'   => system_asset_url('php/trace.write.php'),
    'debugLogEndpoint'=> '/_system/php/debug.client.log.php',
];

// 5. Render Template View
require_once __DIR__ . '/weatherdash.view.php';
?>
	============== weather.setup.php ========
	weatherdash.setup.php (loads the APPNAME setup - config for page and assets to
	be includeds)
## Seperates base app code(APPNAME.index.php)  from what new app needs to customize to load its
pages (APPNAME.setup.php)
$pageSetup  = [
    'navbar' => $includesDir .'/pages/navbar.admin.php',
    'sidebar' => $includesDir .'/pages/sidebar.test.php',
    'sidebarMain' => '',
    'footer' => $includesDir .'/pages/footer.php',
		'breadcrumbs' => $includesDir .'/pages/breadcrumbs.php',
	  'spinner' => $includesDir .'/pages/spinner.php',
	  'content' => '',
	  'appContent' => $includesDir .'/pages/content.php',
	  'debugwin' => $includesDir .'/pages/debugwin.php',
	  'dtable' => $includesDir .'/pages/dtable.php',
	  'modal' => $includesDir .'/pages/modal.php',
	  'toast' => $includesDir .'/pages/toast.php',
];

		//'breadcrumbs' => $includesDir .'/pages/breadcrumbs.php',
$assetOptions = [
    'bootstrap5' => true,
    'adminlte' => true,
    'fontawesome' => true,
    'datatables' => true,
    'jquery' => true,
];

=====
- call weatherdash.html.php ( contains structure of html page/template) self contained
	with place holders for each defined item in template
	- 
- What are the dependencies between SQL table? stations observations sources etc
- How to test the database links are working?
FAQ
How to change location limits

Tasks:
- Move to UTC timing
- Move from lucide to Fontawesome
- Improve UX space between navbar, main-content; sidebar and main-content scroll
	together should be independent
- error management not implemented: ie how pages/add.station.php randomly added
	debug info to screen not to the debugWin
- fix ux of Add Stations
- sidebar text hard to read
- navbar items not working: time, themes/light/dark/auto, Messages when alerts
	exist in weather for any locations in stations, need configuration to
	customize if want all alerts in stations to notify you or pick ones you want,
	define your home/default station (hardcoded now)
	- add use of registry code ; login/password, users, application access
	- implement error_management from registration or weather_station
	- Define standards for CLI of key php ? We had a solution to make them work
		but I think it got lost in updates
	- Link rules in weather_station and weatherdash - colors alerts etc
 - naming conventions of id not standardized
 - document required files and junk/not needed - create a manifest file
 - documentation needs to have json file to organize docs into categories like
	 in defapps
	 - cleanup debug.js and new.debug.js - why aren't all functions accessible