# Menu Metadata Guide

## Purpose
This guide explains how to add routes and navigation entries using central route metadata in `routes.php`.

## Single Source Of Truth
`routes.php` is now the canonical registry for page identity metadata.
Each route entry can define:
1. `file`: PHP content fragment file name.
2. `label`: Menu and navigation label.
3. `title`: Browser/page title label.
4. `admin_only`: Optional boolean access hint for admin-only pages.

Example:

```php
'adminToolsAudits' => [
    'file' => 'adminToolsAudits.php',
    'label' => 'Audits',
    'title' => 'Audits',
    'admin_only' => true,
],
```

## How To Add A New Menu Entry
1. Create the page file (for example `myNewPage.php`).
2. Add route metadata to `routes.php`.
3. Add a navigation placement in `sidebar.php` by calling:
   - `navLink('myNewPage', routeLabel('myNewPage', 'Fallback Label'), 'fa-icon-class')`
4. Optionally add topbar shortcuts in `header.php` using `data-page` and `data-label`.
5. Run checks:
   - `php -l templ.php sidebar.php header.php routes.php myNewPage.php`
6. Open the page and verify:
   - Full load: `templ.php?page=myNewPage`
   - AJAX navigation from menu

## CLI Tooling
Use `tools/route_metadata_tools.php` for validation and CRUD-friendly updates.

Validation:
1. `php tools/route_metadata_tools.php validate`
2. `php tools/route_metadata_tools.php validate --json`

List:
1. `php tools/route_metadata_tools.php list`

Create:
1. `php tools/route_metadata_tools.php add --key=myNewPage --file=myNewPage.php --label="My New Page" --title="My New Page"`

Update:
1. `php tools/route_metadata_tools.php update --key=myNewPage --label="My Updated Label" --title="My Updated Title"`

Delete:
1. `php tools/route_metadata_tools.php delete --key=myNewPage`

Scaffold snippets for sidebar/header/footer references:
1. `php tools/route_metadata_tools.php scaffold --key=myNewPage`

## Why Sidebar Still Needs Editing
`routes.php` stores route metadata, but `sidebar.php` still controls information architecture (section placement, submenu structure, badges).
This is intentional so IA decisions stay explicit.

## Do We Need A Form To Edit Metadata?
Not yet.
1. Current scale is small and code review is preferred for navigation changes.
2. A form adds validation, auth, and migration complexity.
3. If non-developers need to manage menus later, build a controlled admin editor after metadata schema is stable.

## Future Upgrade Path (Optional)
If menu management needs to be non-technical:
1. Move route metadata to a validated JSON/YAML source.
2. Add a schema validator and CI check.
3. Add an admin-only editor UI with role checks and audit logging.