> ## Documentation Index
> Fetch the complete documentation index at: https://nocturneidle.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Before You Start

> A quick primer on command syntax and the Discord permissions Nocturne needs to function.

Before you begin building your staff hierarchies with Nocturne, please take a moment to understand how commands are formatted in these docs, as well as the strict Discord permissions required for the bot to function.

<h2 id="syntax">
  Reading Command Syntax
</h2>

Throughout this documentation, you will see commands formatted in a specific way to show you what information is required and what is optional.

* **`<angle brackets>`** indicate a **Required** parameter. The command will fail if you do not provide this.
* **`[square brackets]`** indicate an **Optional** parameter. The command will run using a default behavior if you leave this blank.

<h3 id="example">
  Example
</h3>

Let's look at the command to add a base role to a tree:

```text Command theme={null}
/tree role add <tree> <role> [position]
```

* `<tree>`: You **must** specify which tree you are adding the role to.
* `<role>`: You **must** specify the Discord role.
* `[position]`: This is **optional**. If you don't provide a hierarchy number, Nocturne will default to placing the role at the highest available rank.

<Warning>
  When actually typing commands in Discord, you do **not** need to type the brackets.
</Warning>

***

<h2 id="required-permissions">
  Required Permissions & Role Hierarchy
</h2>

Because Nocturne is an automated staff management bot, it relies heavily on Discord's role hierarchy. If Nocturne is failing to promote, demote, or assign linked roles, **99% of the time, it is a Role Hierarchy issue.**

<h3 id="role-hierarchy">
  The Golden Rule of Role Hierarchy
</h3>

In Discord, a bot cannot assign or remove a role that is placed higher than the bot's own highest role in the server settings.

**You must go to `Server Settings > Roles` and drag the `Nocturne` role (or any other role that Nocturne has) to the top of your staff roles.** It must sit physically higher than any Base Role or Linked Role you plan to manage through the bot.

<h3 id="bot-permissions">
  Base Bot Permissions
</h3>

When inviting Nocturne, it requires the following core permissions to function properly:

* **`Manage Roles`**: (Required) Allows the bot to Hire, Fire, Promote, Demote, and assign Linked Roles.
* **`Manage Webhooks`**: (Optional but Recommended) Required only if you plan to use the logging system using the `/config log-channel set`.

<h3 id="user-permissions">
  User Permissions
</h3>

* Only users with the `Manage Server` permission can run `/tree` and `/config` commands.
* By default, only users with `Manage Roles` permission can run `/staff` commands. You can make use of [Whitelist Roles](/commands/config/whitelist-roles) to allow other users to use the commands too.