# App Shell Navigation

The App Shell navigation system is configuration-driven. Desktop navigation,
mobile bottom tabs, and the mobile full-navigation index are fed from the
central frontend navigation registry.

## Defaults

- Mobile tab bar is enabled by default.
- Mobile top navigation is hidden by default when the tab bar is active.
- Default mobile tabs are `Console`, `Health`, `Nav`, and `Settings`.
- `Nav` points to `/admin` and is the full-navigation fallback. `Nav` is the
  user-facing mobile label; it does not rename the route or the admin feature
  category.
- `Settings` points to `/settings` and exposes user preferences, including App
  Shell navigation preferences.
- Desktop top navigation remains available on desktop.

## User Preference

Signed-in users have a database-backed App Shell navigation preference:

- `mobileTopNavMode`: `hidden`, `minimal`, `full_mobile`, or `desktop_like`
- `tabBarStyle`: `ios` or `floating_frosted`

The default is `hidden` + `ios`. The option is available from the Settings page
under **App Shell Navigation**. This lets an operator review mobile top-menu
styles live, then return to the default tab-bar-only mobile mode.

The preference is not a workflow authority surface. It only changes navigation
presentation for the signed-in user.

## Mobile Surfaces

`ios` tab bar style is fixed to the bottom edge, safe-area aware, full width,
frosted/blurred, and separated from content by a subtle top border.

`floating_frosted` preserves the earlier inset rounded/floating style as a
configurable alternative.

When mobile top navigation is hidden, full navigation must remain reachable.
The default full-navigation surface is the `/admin` Nav index route, which lists
authorized navigation items from the same registry.

## Naming Compatibility

- `/admin` remains the full-navigation fallback route even when the mobile tab
  label is `Nav`.
- `/admin/health` remains the compatibility route for the user-facing Runtime
  Action Panel.
- The compact mobile tab label may remain `Health` where space is limited; the
  page title and route metadata should use `Runtime Action Panel`.

## Boundaries

- Do not hardcode tab links in components when the registry/config can provide
  them.
- Do not use desktop dropdowns as the default mobile navigation pattern.
- Do not break `/admin` route compatibility when changing user-facing labels.
- Do not add workflow mutation controls to navigation surfaces.
- Preserve role/permission filtering for every navigation surface.