# Cursor quickstart for this repository

A cheat sheet for working on this project with Cursor's Agent. It describes what is checked into `.cursor/`, who does what, and the normal path from a request to a GitHub pull request. Format facts below were checked against [cursor.com/docs/rules](https://cursor.com/docs/rules), [cursor.com/docs/subagents](https://cursor.com/docs/subagents), and [cursor.com/docs/skills](https://cursor.com/docs/skills) on 2026-10-09 with Cursor 3.21.18. Cursor's docs are not version-tagged, so re-check them when Cursor updates.

## What is in `.cursor/`

| Path | Kind | Loaded when |
| --- | --- | --- |
| `rules/agent-workflow.mdc` | Rule, generic | Every chat. How the agent works and when it delegates. |
| `rules/warno-project.mdc` | Rule, WARNO-specific | Every chat. Project facts, invariants, secrets, validation command. |
| `rules/unraid-template.mdc` | Rule, generic | Only when a template, profile, Dockerfile, entrypoint, or check script is in context. |
| `agents/warno-researcher.md` | Subagent, WARNO-specific | When the main agent launches it, or you type `/warno-researcher`. |
| `agents/unraid-template-reviewer.md` | Subagent, generic with a project-specifics paragraph | Same. |
| `agents/verifier.md` | Subagent, generic | Same. |
| `agents/docs-consistency.md` | Subagent, generic | Same. |
| `agents/credential-reviewer.md` | Subagent, WARNO-specific | When the main agent launches it, or you type `/credential-review`. Not part of ordinary review. |
| `agents/workshop-mod-reader.md` | Subagent, WARNO-specific | When the main agent launches it, or you type `/workshop-mods`. |
| `commands/*.md` | Slash commands | Only when you type `/<name>`. |

Rules are injected into the prompt. Subagents run in their own context window and return one final message. Commands are reusable prompts. Nothing in `.cursor/` runs on a timer or on every file save; a subagent runs only when the main agent delegates to it or you invoke it.

## The six subagents

| Agent | Purpose | Main agent uses it when | Call it yourself |
| --- | --- | --- | --- |
| `warno-researcher` | Fetches and labels upstream facts: Eugen's Docker Hub docs, the `eugensystems/warno` image config, Steam Workshop pages, scenario IDs from a subscribed mod's `Scenarios/` folder. Read-only. | A task depends on an upstream fact that `docs/ARCHITECTURE.md` does not record with a source, or that may have changed. | `/warno-researcher does Eugen's image still exec /server/entrypoint2.sh?` |
| `unraid-template-reviewer` | Reviews the template XML, CA profile, Dockerfile, entrypoint, networking statements, and install docs against `docs/UNRAID-TEMPLATE-GUIDE.md`. Read-only; reports `file:line`. | Any of those files changed. | `/unraid-template-reviewer review the uncommitted template changes` |
| `verifier` | Runs `sh scripts/check_repo.sh`, re-reads changed files against the claim, probes edge cases, reports Passed / Failed / Unverified. Does not fix. | A nontrivial change is marked done. | `/verifier confirm the entrypoint still rejects placeholder map IDs` |
| `docs-consistency` | Compares the facts this change altered (name, default, description, port, path, image, command) with the template, README, and install docs. Read-only; names the one sentence to fix. Does not reread untouched docs. | The functional edit is done and one of those facts changed, so a pair such as a template field description and the README may disagree. | `/docs-consistency the template field description changed; check the README pair` |
| `credential-reviewer` | Adversarial review of the Eugen login and dedicated key. Read-only. Clear text on those two form fields is accepted. | You run `/credential-review`, or a change writes, logs, templates, or documents the login, the key, or `login.ini`. | `/credential-review` |
| `workshop-mod-reader` | Reads the local Steam Workshop folder for WARNO and reports `Config.ini` versions, tags, and scenario IDs that differ from `README.md`. Read-only. | You run `/workshop-mods`, or you ask to refresh those facts from the subscribed PC. | `/workshop-mods` |

Cursor also ships built-in subagents (for example `explore` for codebase search, `bugbot` and `security-review` for diff review, `cursor-guide` for Cursor questions). The main agent may use those too; they are not part of this repository.

`warno-researcher`, `unraid-template-reviewer`, and `verifier` return findings as bullets with a source or `file:line`, affected files, commands run with results, and remaining uncertainty. `docs-consistency` returns only Consistent, Mismatches, and Skipped, in under 200 words. `credential-reviewer` returns Findings, Accepted, and Unverified, in under 400 words. `workshop-mod-reader` returns the `scripts/list_workshop_mods.py --diff` report, including full scenario lists for mods that differ. If you get a wall of text instead, ask for that shape.

## Routing rules

From `.cursor/rules/agent-workflow.mdc`:

- Research first only when an upstream fact is missing or stale. Skip it for wording, structure, or facts already recorded with a URL.
- Reviewer after changes to template, Docker, networking, paths, variables, or install docs. Skip for `.cursor/`, tests, workflow YAML. It checks structure; field wording belongs to `docs-consistency`.
- Verifier after any nontrivial implementation or any doc that makes testable claims. Skip for one-line edits the agent already checked by running the command.
- `docs-consistency` after a functional edit that changed a name, default, description, port, path, image, or command. Skip tests, CI, `.cursor/` edits, and wording no other file restates.
- Researcher before implementation when needed. `docs-consistency` next, and its sentences are applied before review. Reviewer and verifier then run in parallel. A small task uses none of them.
- `credential-reviewer` only for `/credential-review`, or when a change writes, logs, templates, or documents the Eugen login, dedicated key, or `login.ini`. Skip it on ordinary feature work and on `/review-and-verify`.
- `workshop-mod-reader` only for `/workshop-mods`, or when the task is to refresh workshop versions and scenario IDs from the local Steam library. Skip it on the review pass.

## Normal workflow

1. **Ask.** Describe the change, or use `/implement-feature <description>`.
2. **Plan.** The agent reads the relevant files and `docs/DECISIONS.md`, states a short plan, and proceeds unless a decision is yours.
3. **Research (if needed).** `warno-researcher` returns labeled facts and affected files.
4. **Implement.** Edits plus a test case in `tests/entrypoint_test.sh` when wrapper behavior changes.
5. **Align paired wording.** If a name, default, description, port, path, image, or command changed, `docs-consistency` compares that fact with the template, README, and install docs. Apply only the sentences it names.
6. **Check.** `sh scripts/check_repo.sh` (XML well-formedness, repository invariants, shell syntax, wrapper tests against a fake upstream).
7. **Review and verify.** `/review-and-verify`, or the agent launches `verifier` and, when relevant, `unraid-template-reviewer` in parallel. Fix, re-check. A credential audit is `/credential-review`, not this step.
8. **Record decisions.** `docs/ARCHITECTURE.md`, `docs/DECISIONS.md`, or `docs/ROADMAP.md` when behavior, a verified fact, or a goal changed. The consistency check does not write those.
9. **Commit on `dev`.** You decide when to commit. The agent commits that work on `dev` and pushes `origin/dev`. Feature work, including the WebUI, commits on `dev`. There is no long-lived feature branch. If the checkout is `main`, it switches to `dev` first. Community Apps and the raw template URL read `main`, so commits on `dev` do not change the Apps listing or the Docker image.
10. **Publish to `main` only when you ask.** Say explicitly that you want the accumulated work on `main`. The agent then merges `dev` into `main` and pushes `origin/main`. If that request names a version ("publish as 1.0"), the agent writes the normalized number (`1.00`) into `VERSION` on `dev` before the merge. Otherwise it leaves `VERSION` alone. **Tag WARHOST release** then tags that `main` commit: `v0.90` the first time, otherwise one minor step past the latest tag (`v0.90` then `v0.91`, and `v1.00` then `v1.01`). A `VERSION` file higher than the latest tag is used instead. A file that still matches the latest tag increments. A file below the latest tag is stale, so the workflow ignores it and increments the latest tag. The tag is created only when that name is missing. A later run keeps a version tag already on that commit. The tag push does not create another commit. The `Check repository` workflow runs `scripts/check_repo.sh` on every PR and on `main`. A `main` push that changes `Dockerfile`, `entrypoint-unraid.sh`, or the rebuild workflow also triggers **Rebuild WARHOST image**, which publishes `ghcr.io/suchamoneypit/warhost:latest`. Wording and template-only pushes update the Apps listing and do not rebuild that image. The agent will not push to `main`, force-push, or merge on its own.

## Starting a fresh chat without losing knowledge

Long chats slow down and cost more context. A new chat starts with the task.

- The two always-on rules load automatically. The template rule loads when you open a template or wrapper file.
- Durable facts are in `docs/`. The agent reads them when the task touches behavior, decisions, or installation, and it runs `git status` itself. An unfinished goal goes in `docs/ROADMAP.md` in the same change as the work.
- To carry a specific thread over, mention the old chat with `@Chats` in the new one, or use Cursor's fork-chat action to continue from a chosen message. In the CLI, `/summarize` compacts the current chat in place. Cursor also compacts old turns automatically.
- Memories and Notepads are not in Cursor's current docs; do not rely on them.

## Slash commands

Project commands in `.cursor/commands/` (name = file name):

| Command | Use it when |
| --- | --- |
| `/project-help` | You are unsure which workflow or agent fits, or you want the setup explained. |
| `/unraid-script` | You want separate Unraid terminal scripts for the `main` and `dev` templates, plus a clean-slate removal of those two. |
| `/implement-feature <what>` | A change that touches code, template, or docs and should end with checks and updated docs. |
| `/review-and-verify` | You want an independent review of uncommitted changes before committing. |
| `/credential-review` | You want an adversarial review of the Eugen login and dedicated key. Clear text on the Unraid form is accepted. |
| `/slop-review` | You want an adversarial read of what ships (the app card, the form, the README, the install guide, the wrapper, and the icon) the way a moderator, a first-time installer, and a skeptical homelabber would read it. Start a new Agent chat and pick your strongest model first. It reports only; reply `apply` with finding IDs to fix those. |
| `/workshop-mods` | You want the local WARNO workshop mods compared with the README: versions, tags, and scenario IDs. It reports only, unless you also ask it to apply the report. |

Useful built-ins (from Cursor's docs; the editor and the CLI differ slightly): `/plan` to switch to Plan mode, `/create-rule`, `/create-subagent`, `/create-skill`, `/review` for a diff review, `/summarize` (CLI) to compact context. Cursor's docs now treat skills (`.cursor/skills/<name>/SKILL.md`) as the successor to commands and offer `/migrate-to-skills`; the commands above are small enough that migrating them is optional.

## What is generic and what is WARNO-specific

Generic, ready to copy into another game-server template repository: `rules/agent-workflow.mdc`, `rules/unraid-template.mdc`, `agents/unraid-template-reviewer.md` (replace its project-specifics paragraph), `agents/verifier.md`, `agents/docs-consistency.md`, the commands in `.cursor/commands/` except `credential-review.md` and `workshop-mods.md` (replace the branch names in `unraid-script.md`, and replace the project-specifics section of `slop-review.md`), `docs/UNRAID-TEMPLATE-GUIDE.md`, `scripts/print_template_fetch.sh`, and this file's structure.

WARNO-specific: `rules/warno-project.mdc`, `agents/warno-researcher.md`, `agents/credential-reviewer.md`, `agents/workshop-mod-reader.md`, `commands/credential-review.md`, `commands/workshop-mods.md`, `scripts/list_workshop_mods.py`, `README.md`, `docs/INSTALL-UNRAID.md`, `docs/ARCHITECTURE.md`, `docs/DECISIONS.md`, `docs/ROADMAP.md`, the template, the wrapper, samples, and tests.