---
description: OM-declared topbar actions — navigation.topbar field and TOPBAR_ACTION_MANIFESTS registry pattern
paths:
  - ui/src/lib/components/AppTopbar*
  - ui/src/routes/__root*
  - core/config/organization-model/**
---

# Topbar Actions (Template Mirror Discipline — Tier 1 Note)

> **Scope:** This note documents substrate that has landed in the monorepo but is not yet published
> to `@elevasis/sdk/reference/rules/`. It will be superseded by the bundled rule once the
> `@elevasis/ui` minor that carries the topbar substrate ships. Until then, use this file.

## navigation.topbar OM Field

The Organization Model now has a `navigation.topbar` region for declaring topbar action items.
Each entry is a distinct node type — OM owns data and visibility; a registry binds behavior.

```ts
// core/config/organization-model.ts (navigation section)
navigation: {
  topbar: {
    request: {
      id: 'request',
      label: 'Request a feature or report an issue',
      tooltip: 'Request a feature or report an issue',
      icon: 'message-plus',
      order: 10,
      enabled: true
    }
  }
}
```

Topbar items are toggled via `/org-os manage` exactly like sidebar surfaces. The `surfaceType`
enum (`page | dashboard | list | detail | graph | settings`) does NOT apply to topbar items —
they are a separate node type, not surfaces.

## TOPBAR_ACTION_MANIFESTS Registry

Behavior for each `navigation.topbar` key is bound through a manifest registry in
`@elevasis/ui`. Each manifest maps a key to a render function:

```ts
// Registered in packages/ui/src/features/registry/manifests.ts
TOPBAR_ACTION_MANIFESTS = {
  request: requestTopbarActionManifest
}
```

The `requestTopbarActionManifest` renders `<RequestActionIcon />` from
`@elevasis/ui/features/monitoring/requests`. It owns its own disclosure state and modal —
no wiring needed at the call site.

## Template Authoring (Tier 2 — Post-Publish)

Declaring `navigation.topbar.request` in the template OM and rendering `<TopbarActions />`
in `AppTopbar` is **Tier 2 post-publish authoring** — it runs after the `@elevasis/ui` minor
bump lands in `external/_template`. Do NOT edit `core/config/organization-model/**` for this
until the publish + baseline bump step completes.

The requests-page `RequestButton` (entry point C) is a CC-level app-local addition in the
platform `apps/command-center` routes. Template projects add their own equivalent in
`ui/src/routes/monitoring/requests.index.tsx` after the surface is present in their navigation.

## Related Rules

- `node_modules/@elevasis/sdk/reference/rules/organization-model.md` — OM schema and authoring ceremony
- `node_modules/@elevasis/sdk/reference/rules/organization-os.md` — `/org-os manage` toggle surface
