docs: Icon CRUD API (5 endpoints) completely missing from behaviors.md

[evan-zhang11]

Problem

The Icon management feature includes 5 API endpoints that are completely undocumented in docs/dev/behaviors.md:

Undocumented Endpoints

#	Endpoint	Method	Purpose
1	/api/icons	GET	List all icons in the current workspace
2	/api/icons	POST	Upload a new icon (PNG or SVG)
3	/api/icons/:id	PATCH	Update icon name
4	/api/icons/:id	DELETE	Delete icon (DB record + filesystem cleanup)
5	/api/icons/:id/file	GET	Serve the raw icon file

Implementation Details

All endpoints are defined in backend/src/icon_handlers.rs and registered in backend/src/routes.rs.

Common characteristics:

• All require authentication
• All scoped to currentWorkspaceId (workspace isolation)
• Icons are stored in {upload_dir}/icons/{icon_id}/original.{ext}

Endpoint Details

1. GET /api/icons — List Icons

• Response: 200 + array of IconItem
• IconItem fields (camelCase): id, name, fileType ("png"|"svg"), width?, height?, size, status ("ready"), error?, createdAt, updatedAt?
• Ordering: created_at DESC

2. POST /api/icons — Upload Icon

• Request: multipart/form-data with file field
• Accepted types: .png and .svg only (extension validated)
• Size limit: Enforced via state.max_size (same as file upload limit)
• Processing: Extracts image dimensions (width/height) synchronously
  • PNG: uses image crate decoder
  • SVG: uses resvg/usvg to parse dimensions
• Response: 201 + { id, status: "ready" }
• Errors: 400 (invalid format/missing file/too large), 401

3. PATCH /api/icons/:id — Update Icon

• Request: { name: string } (must be non-empty, trimmed)
• Response: 204 (no content)
• Errors: 400 (empty name), 401, 404

4. DELETE /api/icons/:id — Delete Icon

• Removes DB record AND attempts filesystem cleanup (remove_dir_all)
• Path traversal protection: canonical path checked against upload_dir_canonical
• Response: 204
• Errors: 401, 404

5. GET /api/icons/:id/file — Serve Icon File

• Returns raw file bytes with appropriate Content-Type (image/png or image/svg+xml)
• Path traversal protection applied
• Response: 200 + binary data
• Errors: 401, 403 (path escape), 404

Why This Matters

Icons support custom map marker/symbol styling — a significant feature for cartographic customization. The complete absence of documentation means:

• No behavior contract to test against
• Frontend developers lack API reference
• Security review has no documented surface area (SVG XSS risk is tracked separately in security: SVG icon upload is a stored XSS vector — no sanitization of SVG content #358)

Proposed Action

Add a new behavior contract section (e.g., ICON-001 through ICON-005) covering:

• Upload format validation and dimension extraction
• Workspace-scoped listing
• Name update
• Deletion with filesystem cleanup
• Raw file serving with content type

Priority: P1 — Icons are a user-facing feature with security implications (SVG content, file serving).