add changeset instructions to AGENTS.md

Author: hzrd149

AGENTS.md

@@ -450,3 +450,248 @@ The torrents view (`src/views/torrents/`) demonstrates this pattern:
 - **Detail View**: `src/views/torrents/torrent.tsx` - Individual torrent details
 - **Routes**: `src/views/torrents/routes.tsx` - Route configuration
 - **Components**: `src/views/torrents/components/` - Reusable UI components
+
+## Changesets for Version Management
+
+This project uses [Changesets](https://github.com/changesets/changesets) to manage versioning and changelogs. **Only create changesets when user-facing APIs change or break.**
+
+### When to Create a Changeset
+
+**CREATE a changeset when:**
+
+- ✅ Adding new public functions, classes, or methods
+- ✅ Modifying signatures of exported functions/methods
+- ✅ Adding/removing/changing public exports
+- ✅ Fixing bugs that affect user-facing behavior
+- ✅ Changing the behavior of existing APIs
+- ✅ Adding new features users can utilize
+- ✅ Deprecating or removing public APIs
+
+**DO NOT create a changeset for:**
+
+- ❌ Internal refactoring (no API changes)
+- ❌ Test-only changes
+- ❌ Documentation updates (unless they reflect API changes)
+- ❌ Build configuration changes
+- ❌ Changes to dev dependencies
+- ❌ Code formatting or linting fixes
+- ❌ Internal helper functions not exported
+
+### Determining the Bump Type
+
+Follow [Semantic Versioning](https://semver.org/):
+
+**PATCH (0.0.X) - Bug Fixes**
+
+- Bug fixes in existing APIs
+- Performance improvements
+- Internal refactoring (if it fixes user-facing issues)
+
+```markdown
+---
+"nostrudel": patch
+---
+
+Fix memory leak in event handler cleanup
+```
+
+**MINOR (0.X.0) - New Features (Backwards Compatible)**
+
+- New public functions/classes/methods
+- New optional parameters
+- New exports
+- Deprecation warnings (not removal)
+
+```markdown
+---
+"nostrudel": minor
+---
+
+Add `getGroupMembers()` method to retrieve all members in a group
+```
+
+**MAJOR (X.0.0) - Breaking Changes**
+
+- Removing public APIs
+- Changing required parameters
+- Removing/renaming exports
+- Incompatible behavior changes
+
+```markdown
+---
+"nostrudel": major
+---
+
+**Breaking:** Remove deprecated `sendMessage()` method. Use `send()` instead.
+```
+
+### One Changeset Per Logical Change
+
+**IMPORTANT: When a single PR or commit contains multiple distinct user-facing changes, create one changeset per change — not one combined changeset.**
+
+Each changeset should describe exactly one thing. This keeps the generated changelog readable: entries map to individual features, fixes, or breaking changes rather than a mixed list.
+
+```bash
+# Example: a PR that adds a new method AND removes a deprecated one
+pnpm changeset add --empty   # changeset 1: minor — Add foo() method
+pnpm changeset add --empty   # changeset 2: major — Remove deprecated bar() method
+```
+
+Multiple changesets are combined automatically at release time; separate entries produce cleaner per-item changelog lines.
+
+### How to Create a Changeset
+
+**IMPORTANT: Always use the CLI to create changesets. Never manually create changeset files.**
+
+Use the `pnpm changeset add` command with the `--empty` flag to create a changeset template:
+
+```bash
+pnpm changeset add --empty
+```
+
+This will:
+
+1. Create a new changeset file with a randomly generated name (e.g., `.changeset/funny-cats-smile.md`)
+2. Generate an empty template that you can then edit
+
+After the file is created, you'll see output like:
+
+```
+🦋  Empty Changeset added! - you can now commit it
+🦋  info /home/user/project/.changeset/funny-cats-smile.md
+```
+
+Then, edit the generated file to add the package name, bump type, and **a single line description**:
+
+```markdown
+---
+"nostrudel": minor
+---
+
+Add support for encrypted group messaging
+```
+
+**Important Guidelines:**
+
+- Keep the description to a **single line of text**
+- This ensures it fits cleanly into the changelog
+- Be concise but descriptive
+
+**Why use the CLI?**
+
+- Ensures correct file naming and format
+- Prevents formatting errors
+- Follows the project's changeset conventions
+
+### Changeset Writing Guidelines
+
+**User-Facing Language:** Write for library users, not developers:
+
+- ✅ "Add `maxRetries` option to connection configuration"
+- ❌ "Implement retry logic in ConnectionManager class"
+
+**Action-Oriented:** Start with a verb:
+
+- **Add:** New features
+- **Fix:** Bug fixes
+- **Update:** Improvements
+- **Remove:** Deleted features
+- **Change:** Modified behavior
+
+**Be Specific:**
+
+- ✅ "Fix reconnection failure after network timeout"
+- ❌ "Fix bug"
+
+**Single Line Only:**
+
+- ✅ "Add group management methods including mute, pin, and stats"
+- ❌ Multi-line descriptions with bullet points (these don't format well in changelogs)
+
+### Workflow Integration
+
+When making changes that affect the public API:
+
+1. Make your code changes
+2. Run `pnpm format` to format code
+3. Run `pnpm test` to ensure tests pass
+4. Run `pnpm build` to verify compilation
+5. **Create a changeset using `pnpm changeset add --empty`** if the change is user-facing
+6. Edit the generated changeset file to add package name, bump type, and **a single line description**
+7. Commit both your changes AND the changeset file
+
+```bash
+# After making changes to public API
+pnpm changeset add --empty
+# This creates .changeset/some-random-name.md
+
+# Edit the file to add your changeset details
+# Then commit everything together
+git add .
+git commit -m "Add group encryption feature"
+# Both code changes and the changeset file are committed together
+```
+
+### Example Scenarios
+
+**Scenario 1: Adding a new public method**
+
+```typescript
+// In src/client/marmot-client.ts
+export class MarmotClient {
+  // New method added
+  public async getGroupInfo(groupId: string): Promise<GroupInfo> {}
+}
+```
+
+Run `pnpm changeset add --empty`, then edit the generated file:
+
+```markdown
+---
+"nostrudel": minor
+---
+
+Add getGroupInfo() method to retrieve group metadata
+```
+
+**Scenario 2: Fixing a bug**
+
+```typescript
+// Fixed: Connection now properly retries on timeout
+```
+
+Run `pnpm changeset add --empty`, then edit the generated file:
+
+```markdown
+---
+"nostrudel": patch
+---
+
+Fix connection retry logic to handle network timeouts
+```
+
+**Scenario 3: Breaking change**
+
+```typescript
+// Changed signature from:
+// createGroup(name: string, relays: string[])
+// to:
+// createGroup(options: CreateGroupOptions)
+```
+
+Run `pnpm changeset add --empty`, then edit the generated file:
+
+```markdown
+---
+"nostrudel": major
+---
+
+Change createGroup() to accept options object instead of positional arguments
+```
+
+### Additional Notes
+
+- Changeset files are consumed during the release process by maintainers
+- Multiple changesets can exist and will be combined during version bumping
+- See `.changeset/README.md` for comprehensive documentation
+- The configuration uses `master` as the base branch