Bookmark  *bool  `json:"bookmark" jsonschema:"Set bookmark flag (true/false)"`
	Comment   string `json:"comment" jsonschema:"User comment (max 140 chars, ASCII only)"`

	Bookmark      *bool  `json:"bookmark,omitempty"`
	Comment       string `json:"comment,omitempty"`

	// Validate comment (max 140 chars, ASCII only)
	if len(input.Comment) > 140 {
		output.Error = "--comment must be 140 characters or less"
		return output, fmt.Errorf("%s", output.Error)
	}
	for i, r := range input.Comment {
		if r > 127 {
			output.Error = fmt.Sprintf("--comment must be ASCII only (non-ASCII at position %d)", i)
			return output, fmt.Errorf("%s", output.Error)
		}
	}

	bookmarkChanging := input.Bookmark != nil && *input.Bookmark != targetLabel.Bookmark
	commentChanging := input.Comment != "" && input.Comment != targetLabel.Comment

	if !speciesChanging && !certaintyChanging {
		output.Error = "No changes needed: species+calltype and certainty already match"

	if !speciesChanging && !certaintyChanging && !bookmarkChanging && !commentChanging {
		output.Error = "No changes needed: all values already match"

	// Update bookmark (only if explicitly set)
	if input.Bookmark != nil {
		targetLabel.Bookmark = *input.Bookmark
		output.Bookmark = input.Bookmark
	}
	// Update comment (only if non-empty)
	if input.Comment != "" {
		targetLabel.Comment = input.Comment
		output.Comment = input.Comment
	}

	fmt.Fprintf(os.Stderr, "  --bookmark          Mark segment as bookmarked for navigation\n")
	fmt.Fprintf(os.Stderr, "  --comment <text>    User comment (max 140 chars, ASCII only)\n")

	fmt.Fprintf(os.Stderr, "  If species+calltype and certainty match current values, no modification is made.\n")

	fmt.Fprintf(os.Stderr, "  If all specified values match current values, no modification is made.\n")

	fmt.Fprintf(os.Stderr, "    --filter mymodel --segment 67-88 --species Noise --certainty 100\n")

	fmt.Fprintf(os.Stderr, "    --filter mymodel --segment 67-88 --species Noise --certainty 100\n\n")
	fmt.Fprintf(os.Stderr, "  # Bookmark a segment for later review\n")
	fmt.Fprintf(os.Stderr, "  skraak calls modify --file recording.data --reviewer GLM-5 \\\n")
	fmt.Fprintf(os.Stderr, "    --filter mymodel --segment 12-15 --certainty 100 --bookmark\n\n")
	fmt.Fprintf(os.Stderr, "  # Add a comment to a segment\n")
	fmt.Fprintf(os.Stderr, "  skraak calls modify --file recording.data --reviewer GLM-5 \\\n")
	fmt.Fprintf(os.Stderr, "    --filter mymodel --segment 12-15 --certainty 100 --comment \"Good example of duet\"\n")

	var file, reviewer, filter, segment, species string

	var file, reviewer, filter, segment, species, comment string

	var certaintySet bool

	var certaintySet, bookmark bool

			i += 2
		case "--bookmark":
			bookmark = true
			i++
		case "--comment":
			if i+1 >= len(args) {
				fmt.Fprintf(os.Stderr, "Error: --comment requires a value\n")
				os.Exit(1)
			}
			comment = args[i+1]

		Comment:   comment,
	}
	if bookmark {
		input.Bookmark = &bookmark

./skraak calls modify --file recording.data --reviewer Claude --filter opensoundscape-multi-1.0 --segment 12-15 --certainty 80 --bookmark
./skraak calls modify --file recording.data --reviewer Claude --filter opensoundscape-multi-1.0 --segment 12-15 --certainty 80 --comment "Clear example of male call"

## [2026-04-03] Added `--bookmark` and `--comment` flags to `calls modify`
Allow agents and users to bookmark segments and add comments for information preservation in .data files.
**New flags:**
- `--bookmark` — Mark segment as bookmarked for navigation (boolean flag, sets `bookmark=true`)
- `--comment <text>` — Add user comment (max 140 chars, ASCII only)

**Usage:**
```bash
# Bookmark a segment for later review
skraak calls modify --file recording.data --reviewer GLM-5 \
  --filter mymodel --segment 12-15 --certainty 100 --bookmark
# Add a comment to a segment
skraak calls modify --file recording.data --reviewer GLM-5 \
  --filter mymodel --segment 12-15 --certainty 100 --comment "Good example of duet"
```
**Behavior:**
- `--bookmark` sets `bookmark=true` on the label
- `--comment` stores text in the label's comment field
- Comment validation: max 140 characters, ASCII only
- If all specified values match current values, no modification made (error)
**Changes:**
- `tools/calls_modify.go` — Added `Bookmark` and `Comment` fields to input/output structs, validation logic
- `cmd/calls_modify.go` — Added `--bookmark` and `--comment` flag parsing

**Note on Frequency Scaling:** Spectrogram frequency ranges may vary based on recording
equipment (8kHz/16kHz/32kHz). Focus on the **relative pattern** (spacing, thickness,
regularity of vertical bars) rather than absolute frequency position. Male calls show
bold, regularly-spaced bars at lower frequencies relative to the display; female calls
are thinner and higher relatively. 
If the samaple rate is above 16kHz, audio is downsampled to 16kHz, if sample rate is below 16kHz, it is left as is fro the spectrogram. In practice images will be 8kHz (most common) or 16kHz.

### Token Efficiency Guidelines
- **<100 segments**: Review all at once
- **100-300 segments**: Review in one batch (acceptable cost)
- **>300 segments**: Consider filtering by calltype (e.g., review Duets/Females first, 
  then Males) or by date range to manage token costs

### When to Skip (Leave at certainty 70)
- **Duration <15 samples** (very short segments)
- **Signal-to-noise ratio too low** (fainter than reference examples)
- **Fragmented/incomplete patterns** (file boundary artifacts)
- **Uncertain classification** (pattern doesn't clearly match reference)
- **Never guess** - skip rather than misclassify

```
Bookmark an outstanding example:
```bash
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <Your Name> \
  --filter <filter> --segment <start>-<end> --certainty 80 --bookmark

### Step 7: Final summary

Add a comment to preserve information:
```bash
./skraak calls modify --file "<folder>/<basename>.wav.data" --reviewer <Your Name> \
  --filter <filter> --segment <start>-<end> --certainty 80 --comment "Clear duet with visible female component"
```
**Bookmark**: Use `--bookmark` to mark outstanding, clear, or beautiful examples of a call. Bookmarked segments can be easily found later for training reference or demonstration purposes.
**Comment**: Use `--comment "text"` to preserve useful information about a segment. Comments are stored in the .data file and visible when classifying calls manually. Max 140 characters, ASCII only. Examples:
- "Clear duet with visible female component"
- "Unusual timing pattern, verify with audio"
- "Good training example for male vs female distinction"
### Step 7: Verify Changes (Optional)
Check that modifications were applied correctly:
```bash
# Count segments at certainty 80
grep -r '"certainty": 80' <folder>/*.data | wc -l

# View a specific modified file
cat <folder>/<filename>.wav.data | grep -A5 '"segment_start":<start>'

### Step 8: Final summary
```

- **Certainty 80**: use for all Claude classifications (distinguishes from ML=70, human=100)
- **Reviewer**: always "Claude"

- **Certainty 80**: use for all LLM classifications (distinguishes from ML=70, human=100)
- **Reviewer**: always the actual model being used, eg haiku-4.5, kimi-k2.5, glm-5, minimax-m2.7, 

## Calltype-Specific Tips
### GSK/Roroa Specific Guidance
- **Male**: Most common, look for bold vertical stripes at ~1/3 to 1/2 of spectrogram height
- **Female**: Higher frequency, thinner bars, often fainter - don't mistake faintness for absence
- **Duet**: Both patterns present simultaneously - if you see ANY female component with male, it's a Duet
- **Distant calls**: Fainter versions of same patterns are still valid - only skip if pattern is unclear
### Reference Image Strategy
1. Read 2-3 reference images from EACH calltype folder
2. Mentally note the **key distinguishing features**:
   - Male: Bar thickness, spacing regularity, relative frequency position
   - Female: Thin bars, higher position, delicate appearance  
   - Duet: Two distinct frequency bands with overlapping patterns