# Menus

Menus are declared in the manifest and implemented by registering command
handlers during activation.

```json
{
  "contributes": {
    "menus": [
      {
        "id": "hello-plugin.menu",
        "label": "Hello Plugin",
        "topLevel": true,
        "order": 100
      }
    ],
    "menuItems": [
      {
        "id": "hello-plugin.open.item",
        "targetMenuId": "hello-plugin.menu",
        "label": "Open Dashboard",
        "command": "hello-plugin.open",
        "order": 10,
        "when": "projectOpen"
      }
    ]
  }
}
```

Then register the command id:

```ts
export function activate(ctx: ActivateContext): void {
  const disposable = ctx.commands?.registerCommand("hello-plugin.open", async () => {
    await ctx.services?.windows.open({ layoutType: "hello-plugin.dashboard" });
  });
  if (disposable) ctx.subscriptions.push(disposable);
}
```

## Rules

- There is no separate `contributes.commands` collection. A command can only be
  registered if at least one manifest `menuItems[].command` or
  `slashCommands[].command` entry declares that exact id.
- A missing command handler is surfaced by the host as a retryable reload error;
  menu clicks must never fail silently.
- A handler owns precondition checks and feedback. See
  [Commands And Feedback](commands-and-feedback.md).
- Menu item `when` expressions are evaluated by the host; unsupported or false
  conditions hide/disable the item according to host policy.

## Targets

`targetMenuId` can refer to a plugin top-level menu id or a host menu id exposed
by IdeA. Prefer a plugin top-level menu for plugin-specific workflows and host
menus only when the action naturally belongs beside native actions.