# Setup Engine v4

The server setup system was rebuilt as a staged reconciler around the documented discord.js manager APIs.

## Execution order

1. Fetch the current guild roles/channels.
2. Apply server settings.
3. Create/update roles without attempting hierarchy moves during creation.
4. Fetch roles again and apply role hierarchy with `guild.roles.setPositions()`.
5. Create/update categories.
6. Create/update child channels. Channel positions are never passed to `channels.create()`.
7. Apply category and channel ordering with `guild.channels.setPositions()`.
8. Optionally delete only resources previously recorded as blueprint-managed.
9. Atomically save the state file.

## Important Discord constraints

- The bot cannot edit, move, or create a role at/above its highest role.
- `@everyone` is never treated as a normal blueprint role.
- Managed Discord/integration roles are never edited.
- Role colors use the documented `colors: { primaryColor: ... }` shape.
- Permission names are resolved to actual discord.js permission flags and rejected before an API call if no numeric flag exists.
- Role icon/unicode emoji entitlement failures are handled as a non-fatal skip.
- Positions are validated as finite integers before position APIs are called.
- Creation/edit operations and hierarchy/order operations are separate phases.

## Test

```bash
npm install
npm run validate
npm start
```

Then run `/setup` in a server where the bot has `Manage Server`, `Manage Roles`, and `Manage Channels`.