chore: update planning notes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

findings.md

@@ -65,3 +65,20 @@
 - Existing sessions created before enforcement are reconciled when the authenticated device list is read, preserving the current session first and then the most recently created sessions.
 - Follow-up display requirement: `lastSeenAt` must be a timezone-neutral instant over the API. The backend will emit RFC3339 UTC and the browser will format it with `Intl.DateTimeFormat` using its local timezone and the selected UI locale.
 - No configured `mcp-zero` callable tool is available in this session, so API validation/generation will use the documented `goctl` fallback after the `.api` spec is updated.
+
+## Visual Annotation Request (2026-07-11)
+- The supplied reference adds `标注改图` as an image action with brush, circle, rectangle, and cross tools, a mark list, and generation controls.
+- The repository already has general canvas point annotations for Agent Chat, but those annotations are not image-local drawing geometry and cannot represent marked regions.
+- `CanvasWorkspace` owns image action mode state and already routes selected-image operations through a shared asynchronous generation path; the new mode should extend that path rather than add a parallel API.
+- The requested `告诉 AI 怎么改` content needs to be an editable instruction per visual mark, not a fixed tool-name label as shown in the reference HTML.
+- Existing unrelated user edits are limited to `frontend/src/app/layout.tsx`, `CanvasAgentComposer/index.css`, and `ImageDropOverlay/index.css`; the annotation work must preserve them.
+- The existing node action contract already carries an open action string, prompt, selection, mask, and options map, but the backend rejects unknown normalized action names and only sends the original source image to the image model.
+- A reliable annotated edit should send both the clean source and a browser-rendered annotated guide image; coordinate-only text is less robust for freehand marks and irregular regions.
+- The browser can rasterize the selected node through the existing `imageNodeRasterBlob`, draw normalized annotation geometry and numbered badges, upload the guide with `designGateway.uploadImage`, and submit its URL through a dedicated spec field.
+- The server should treat the guide as temporary visual context: include it as a second image in the action message, tell the model never to reproduce the marks, and keep the clean source as the output base.
+- The selected canvas image model and credit metadata already exist in `CanvasWorkspace`; the annotation panel can expose the same model selection rather than invent a separate model state.
+- Existing side panels use viewport-aware positioning and restrained neutral surfaces. The annotation UI should follow this dense operational style while keeping all drawing geometry directly on the selected image.
+- The implemented contract adds `annotationImage` to the existing node-action request. The backend requires it for `visual-annotation`, keeps the clean source first, appends the guide second, and stores both URLs in generator-task metadata for traceability and asset cleanup.
+- Brush, circle, rectangle, and cross marks use normalized coordinates, so the on-canvas overlay, uploaded guide raster, structured action payload, and resized canvas view stay aligned.
+- Generation remains blocked until every mark has a non-empty editable instruction, preventing unlabeled regions from reaching the image model.
+- Follow-up invariant: visual annotation never changes the source node. Submission creates a sibling copy to the source's right; generation state, failures, and the final image are isolated to that copy.

progress.md

@@ -70,3 +70,20 @@
 - Added device-list reconciliation for sessions created before enforcement and verified current-session preservation.
 - Changed the device API timestamp contract to RFC3339 UTC and formatted it with the browser's local timezone via `Intl.DateTimeFormat`.
 - Regression tests now pass for configured desktop limit 1, pre-enforcement reconciliation, concurrent PostgreSQL logins, and timezone-neutral API timestamps.
+
+### Phase 11: Visual Annotation Discovery and Design
+- **Status:** complete
+- Loaded the repository workflow, supplied HTML reference, frontend design guidance, and existing planning state.
+- Located the image toolbar/action mode owner, the shared canvas action generation route, and the separate general-purpose Agent Chat annotation feature.
+- Established the implementation boundary: image-local geometry plus editable per-mark instructions, submitted through the existing image action flow.
+- Chose a clean-source plus annotated-guide submission model so freehand and shape marks are visible to the image model without becoming output pixels.
+- Confirmed the panel can reuse the active canvas model, existing asset upload, asynchronous node action, task event, and result replacement paths.
+
+### Phase 12: Visual Annotation Implementation
+- **Status:** in_progress
+- Started the API-first action contract extension and canvas-native visual annotation component implementation.
+- Added and validated the API request field for an uploaded annotation guide, then regenerated go-zero types through the local `mcp-zero` stdio server.
+- Added the toolbar entry, drawing overlay, four visual tools, numbered mark list, editable instructions, undo/delete, shared model picker, responsive panel placement, and guide rasterization.
+- Added backend validation, prompt constraints, clean-source plus guide-image inputs, action lifecycle copy, generator metadata, and focused action coverage.
+- Targeted Go tests, locale JSON parsing, and frontend TypeScript validation pass.
+- Updated the action contract so visual annotation preserves the original and generates into a sibling copy placed to its right.

task_plan.md

@@ -4,7 +4,7 @@
 Persist Brand Kits by authenticated user, bind one optional Brand Kit to each project/canvas, expose a canvas-header selector, and make every Agent Chat turn and newly created thread use the selected kit as authoritative creative context.
 
 ## Current Phase
-Phase 7
+Phase 12
 
 ## Phases
 
@@ -68,6 +68,29 @@ Phase 7
 - [ ] Provide the working preview URL and concise implementation notes
 - **Status:** pending
 
+### Phase 11: Visual Annotation Discovery and Design
+- [x] Map image toolbar/action generation, canvas transforms, and reusable panel conventions
+- [x] Translate the supplied annotation reference into the repository's interaction and visual language
+- **Status:** complete
+
+### Phase 12: Visual Annotation Implementation
+- [ ] Add an image-toolbar entry and visual annotation editing mode
+- [ ] Support brush, circle, rectangle, and cross marks on the selected image
+- [ ] Make each mark's AI edit instruction directly editable and removable
+- [ ] Submit the annotated source through the existing image action generation flow
+- [ ] Preserve the source node and write generation state/results only to a sibling copy
+- **Status:** in_progress
+
+### Phase 13: Visual Annotation Verification
+- [ ] Add focused interaction/serialization coverage where supported
+- [ ] Run frontend typecheck/build and inspect desktop/mobile behavior in a real browser
+- **Status:** pending
+
+### Phase 14: Visual Annotation Delivery
+- [ ] Review scope and final diff without altering unrelated user changes
+- [ ] Provide the working preview URL and concise implementation notes
+- **Status:** pending
+
 ## Invariants
 - Brand Kits are owned and queried only through the authenticated user ID from request context.
 - A project may reference zero or one Brand Kit owned by the same user.
@@ -82,6 +105,7 @@ Phase 7
 - Revoked and expired sessions never authenticate or appear in the active-device list.
 - Device metadata is derived from request headers for display only and never used as an authorization signal.
 - Device timestamps cross the API boundary as RFC3339 UTC instants and are localized only in the browser's timezone.
+- Visual annotation actions never mutate the source image node; their copied result node is the only generation target.
 - Desktop and mobile web-session limits come from server configuration; the API returns the effective values and the UI never hard-codes them.
 
 ## Errors Encountered
@@ -102,3 +126,4 @@ Phase 7
 | The in-app browser runtime reported no available browser backends | 1 | Keep the verified local preview running and report the browser-only visual inspection gap; do not substitute an unrelated browser surface against the browser skill rules. |
 | Escaping the `psql \d` meta-command through Docker produced an invalid command | 1 | Query `information_schema.columns` and `pg_indexes` with regular SQL instead. |
 | Desktop limit regression test observed two valid desktop sessions when the configured limit was 1 | 1 | Confirmed the limit was presentation-only; enforce it atomically during session creation and reconcile pre-fix sessions during device listing. |
+| Launching `mcp-zero` from `server/` used a repository-root relative path | 1 | Relaunch with `../.tools/bin/mcp-zero` while keeping generation output rooted in `server/`. |