# TOGTools — Claude Instructions

WoW Classic Era addon. Lua 5.1, AceGUI-3.0, AceDB-3.0, AceAddon-3.0.

## Tool Usage (Always Follow)

**Always use dedicated tools for file operations — never Bash or PowerShell for these tasks:**

- **Read files** → Read tool
- **Edit files** → Edit or Write tool
- **Search content** → Grep tool
- **Find files** → Glob tool

Only use Bash/PowerShell for operations with no dedicated tool equivalent: running scripts, git commands, process management.

## Development Rules (Always Follow)

- **Use AceGUI widgets** — never raw `CreateFrame()` unless a specific WoW API requires it.
- **Use AceGUI methods** — e.g. `widget:SetText()` not `widget.label:SetText()`.
- **Persistent windows** — never call `Release()` on a window that stays open. Use `ReleaseChildren()` + re-populating.
- **Fix ALL lint/compile errors automatically** — this includes Lua, Markdown, and HTML files. Never leave a known error unfixed.
- **Lua globals** — `.luarc.json` defines all known WoW API globals; add new ones to `diagnostics.globals` when needed.
- **Markdown lint** — `.markdownlint.json` enforces MD047 (single trailing newline); always ensure `.md` files end with a newline.
- **Comments must be accurate** — only explain the non-obvious "why". Never write aspirational comments. Update stale comments in any block you edit.
- **Look at TOGProfessionMaster and FastGuildInvite first** — check them before inventing a solution.

## Module Pattern

Every tool is its own module pair:

- `Modules/<Name>/<Name>.lua` — engine logic; registers `addon.modules["<key>"]`
- `GUI/<Name>Tab.lua` — AceGUI settings panel; merges `tabKey`, `label`, `WINDOW_SIZE`, and `Draw` into the module table

Tabs auto-appear in the main window, sorted alphabetically by `label`.

## Commit & Version Process (ALWAYS follow — no exceptions)

1. **Never commit without explicit user approval.** After completing any work, summarise what changed and ask: *"Ready to commit — what version should I use? (current latest is vX.X.X)"*
2. **Wait for the version answer before writing any changelog entry or running any git command.**
3. **Multiple changes may share one version.** The user will say when they are ready to commit; do not assume one change = one commit.
4. **Stage all modified and untracked addon files** — never cherry-pick only the files you worked on. Run `git status` first.
5. **Never create or push git tags.** Tags are the user's responsibility. Only run `git add` and `git commit` and `git push` (branch only). Do not run `git tag` under any circumstances.

## Documentation (run after EVERY feature or fix, before asking to commit)

### CHANGELOG.md — developer-level record

- Always prepend a new entry; never edit existing ones.
- Include technical detail: root causes, file names, function names, architectural decisions.
- Format:

```markdown
## [vX.X.X] (YYYY-MM-DD) - Short Title

### New Features
- **Feature name** — Technical description. Location: `File.lua`.

### Bug Fixes
- **Bug** — Root cause and fix. Location: `File.lua`.

### Improvements
- **Improvement** — What changed and why.

---
```

- Increment patch (Z) for bug fixes/polish; minor (Y) for new user-facing features.

### docs/Curseforge_Description.html — user-facing record

- Written for players, not developers. Plain language only.
- **No** code identifiers (function names, file names, event names), **no** internal architecture terms, **no** ticket IDs, **no** error-message text quoted verbatim.
- The "Recent Updates" section keeps **only the last 5 patches**. When adding a new entry, remove the oldest so the count stays at 5.
- **When a patch is rolled off the Recent Updates list**, check whether it introduced a major user-facing feature. If it did, add a permanent entry for that feature in the relevant feature section higher up in the HTML so it is not lost from the page.
