Staff Handbook Troubleshooting

/handbook Does Not Appear

• Confirm the folder is plugins/staff_handbook.
• Confirm AthenaBot 2.2.0 or newer is running.
• Check startup logs for config or permission-level errors.
• Restart AthenaBot after changing the command name or search option.

A Member Cannot Open the Handbook

• Check permissions.handbook_command against configuration/permission.json5.
• Check the member against access.allowed_role_ids and access.allowed_user_ids.
• An empty role list does not override a populated user list. If either global list contains values, the member must match one listed user or role.
• Confirm the plugin is enabled.

Menus or Buttons Stop Working

• Check permissions.handbook_components against configuration/permission.json5.
• Only the member who opened the handbook can use its controls.
• Confirm the member still has an allowed role.
• Old controls may stop working after a restart or config change. Run /handbook again.

Categories or Pages Are Missing

• Check whether the item uses senior_only: true.
• Check its required_role_ids and required_user_ids.
• Confirm the category contains at least one visible, valid page.
• Use unique IDs containing only letters, numbers, underscores, or hyphens.
• Check AthenaBot logs. The plugin logs invalid content and skips it.

The Plugin Reports Missing Usable Content

• Confirm all three config files loaded.
• Confirm staff_handbook_content.config.categories is an array.
• Check the required category and page fields in the configuration reference.
• Keep steps, action_guidance, evidence_requirements, and notes as arrays, even when empty.
• Check that every link uses an http:// or https:// URL.

Search Returns No Results

• Confirm search.enabled is true.
• Search only checks pages the member can view.
• Confirm the keyword appears in a category, page field, list item, or link.
• Use a shorter search term. Matching checks the entered text as one phrase.

Search or Menus Fail During Startup

• Set search.max_results and ui.max_visible_options between 1 and 25.
• Set search.max_query_length between 1 and 100.
• Set each button style to Primary, Secondary, Success, or Danger.
• Use a six-digit color such as #d7263d for ui.embed_color.

Dashboard Changes Do Not Match Local JSON5

When dashboard-backed configuration is enabled, MongoDB values can override the local files. Make the change in the dashboard or confirm which source AthenaBot loaded before editing JSON5 again.