> For the complete documentation index, see [llms.txt](https://docs.cozycrafters.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cozycrafters.net/plugin-docs/cozyguides.md).

# CozyGuides

### What It Does

CozyGuides provides player-facing server guides and an optional welcome checklist.

Players can open a guide menu, start available guides, and quit an active guide when the guide allows it. Staff can reload guide files, list loaded guides, force-start a guide for a player, or stop a player's active guide.

The bundled welcome checklist helps new players complete starter tasks such as opening claims, homes, rewards, goals, market, and ranks.

### Main Features

| Feature                | Description                                                                                                           |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Guide browser          | `/guides` opens an inventory menu of available guides.                                                                |
| Chat guide list        | `/guides list` lists available guides in chat.                                                                        |
| Direct guide start     | `/guides start <guideId>` starts a specific guide.                                                                    |
| Welcome checklist      | `/welcome` opens the configured checklist guide when enabled.                                                         |
| Checklist progress     | Checklist steps can be completed when players use matching commands.                                                  |
| Completion rewards     | Checklist guides can run final reward commands after completion.                                                      |
| Guide progress storage | The plugin stores started and completed counts, timestamps, checklist step completions, and checklist reward records. |
| Admin reload           | `/cozyguides reload` reloads config, messages, and guide files.                                                       |
| Session cleanup        | Active guide sessions are cleared on player quit, player death, plugin disable, and plugin reload.                    |

### Basic Admin Workflow

1. Install the plugin and start the server so default files are created.
2. Review the generated guides in `plugins/CozyGuides/guides/`.
3. Use `/cozyguides reload` after changing config, messages, or guide files.
4. Use `/cozyguides list` to confirm which guides loaded.
5. Give normal players `cozyguides.use` and `cozyguides.welcome` if your permissions plugin does not already grant default permissions.
6. Give staff the admin permissions they need for reloads, guide starts, and guide stops.

### Notes

* `/guides` and `/welcome` are player-only commands.
* `/welcome` only works when welcome checklist support is enabled in config and the configured guide is loaded as a checklist.
* `/welcome` has the aliases `/welcomeguide` and `/starter`.
* `/cozyguides` has the alias `/cguides`.
* `/cozyguides reload` cancels active guide sessions safely.
* Console command guide steps are disabled by default in `config.yml`; player command guide steps are enabled by default.
* The source does not declare any plugin dependencies in `plugin.yml`.

### Common Use Cases

| Use Case                             | Command                                |
| ------------------------------------ | -------------------------------------- |
| Player opens the guide menu          | `/guides`                              |
| Player opens the welcome checklist   | `/welcome`                             |
| Player starts a known guide directly | `/guides start <guideId>`              |
| Player quits an active guide         | `/guides quit`                         |
| Admin reloads guide content          | `/cozyguides reload`                   |
| Admin checks loaded guide IDs        | `/cozyguides list`                     |
| Admin starts a guide for a player    | `/cozyguides start <guideId> <player>` |
| Admin stops a player's active guide  | `/cozyguides stop <player>`            |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cozycrafters.net/plugin-docs/cozyguides.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.