docs(kanvas): document whiteboard behaviour changed by the capture-defect fixes

content/en/kanvas/designer/canvas-objects/index.md

@@ -76,8 +76,8 @@ they move with it.
 ### Adding textboxes {#adding-textboxes}
 
 Drag the textbox tool from the dock onto the canvas, or press
-<button class="kbc-button kbc-button-xs">T</button>. The keyboard route places the textbox near the
-center of the canvas and puts the cursor straight into it, so you can start typing immediately.
+<button class="kbc-button kbc-button-xs">T</button>, which places it near the center of the
+canvas. Either way, the cursor goes straight into the new textbox, so you can start typing immediately.
 
 A new textbox arrives 60 pixels tall with a dashed gray border and a transparent fill, and its text
 sits at the top left of the box. To edit the text of an existing textbox - or of any shape, since

content/en/kanvas/designer/layout-and-layers/index.md

@@ -50,7 +50,7 @@ The **Layers** panel controls what the canvas draws. Open it from the **Layers**
 
 In Designer mode the panel is organized into four sections:
 
-- **By type** - a single toggle each for **Annotations** (comments, shapes, text and other non-semantic components) and **Configurable Components** (the semantic components that actually get deployed). Turning annotations off is the fastest way to see the deployable shape of a design on its own. The count beside each is the number of components of that type in the design.
+- **By type** - a single toggle each for **Annotations** (comments, shapes, text and other non-semantic components) and **Configurable Components** (the semantic components that actually get deployed). Turning annotations off is the fastest way to see the deployable shape of a design on its own: whiteboard elements hide, while a workload's containers stay with it, and turning annotations back on leaves every component where it was. The count beside each is the number of components of that type in the design.
 - **Component Badges** - **Validation Warnings**, **Deployment Errors** and **Inventory** badges. These are the small markers Kanvas draws on components; hiding them declutters a design that is mid-review. See [Interpreting Component Badges]({{< ref "kanvas/designer/interpreting-component-badges/index.md" >}}).
 - **Components** - every kind present in the design, grouped by model. Expanding a group lists the individual components, each with its own visibility toggle, so you can hide one Deployment without hiding the rest. Clicking a component's name selects it on the canvas and zooms the view to it.
 - **Relationships** - each relationship kind, type and subtype found in the design, with its own toggle and a count. TagSet relationships appear here under that name.

content/en/kanvas/designer/merging-designs/index.md

@@ -30,7 +30,7 @@ The Merge Design dialog offers three choices:
 
 ### Merge with existing nodes on the canvas
 
-**Merge into current** combines the two designs. Every component and relationship from the dropped design is added to the design you already have open. The block's top-left corner moves to the drop position when you dropped a file. Otherwise it lands 50 pixels right and 50 pixels down from its original coordinates, and it can overlap existing components. Every component and relationship in the incoming design receives a new identifier. Kanvas does not match or de-duplicate against existing components, so merging the same design twice doubles its components. Names, kinds, configuration, styles, and the internal layout of the incoming block are preserved. The incoming design's name, id, version, visibility, catalog data, layer preferences, and workspace are not carried over. Relationship evaluation runs as for any edit, and autosave persists the result after three seconds. If the merged design exceeds your plan's component limit, the save fails and the merged components remain unsaved on the canvas. Merging needs no permission key, but the incoming design must be one you can read: your own, public, published, or shared with you. Cancel on a merge prompt does not delete a design the import already saved. A failed merge shows `Failed to merge design: <reason>`.
+**Merge into current** combines the two designs. Components from the dropped design are added to the design you already have open, except those the open design already holds: a component with the same model, kind, namespace and name is matched to the existing one instead of being added again, and so is a second copy of one resource inside the dropped design. The open design keeps its own configuration and position for a matched component, relationships that pointed at an incoming component point at the one it matched, and a relationship that would duplicate an existing one is not added. Annotations (shapes, text, pencil strokes and other whiteboard elements) are always added. The block's top-left corner moves to the drop position when you dropped a file. Otherwise it lands 50 pixels right and 50 pixels down from its original coordinates, and it can overlap existing components. Every added component and relationship receives a new identifier. Merging the same design twice adds nothing the second time. Copying and pasting, or duplicating a selection, still makes copies. Names, kinds, configuration, styles, and the internal layout of the incoming block are preserved. The incoming design's name, id, version, visibility, catalog data, layer preferences, and workspace are not carried over. Relationship evaluation runs as for any edit, and autosave persists the result after three seconds. If the merged design exceeds your plan's component limit, the save fails and the merged components remain unsaved on the canvas. Merging needs no permission key, but the incoming design must be one you can read: your own, public, published, or shared with you. Cancel on a merge prompt does not delete a design the import already saved. A failed merge shows `Failed to merge design: <reason>`.
 
 Merging does not consume the design you dragged. It remains in your design list, unchanged and independently owned - what you have merged is a copy of its contents into the design in front of you.
 

content/en/kanvas/designer/understanding-tool-modes/index.md

@@ -44,7 +44,7 @@ You can switch between mouse modes using hotkeys or tool selection. Here are hot
 
 {{% tab header="Pencil Tool" lang="en" action="true" %}}
 
-Pencil lines do not connect individual components, but offer annotating capability, allowing you to take notes and draw annotations to enhance your designs.
+Pencil lines do not connect individual components, but offer annotating capability, allowing you to take notes and draw annotations to enhance your designs. A stroke can start, run and end over a component, so you can circle or underline anything on the canvas; while the Pencil is active, pressing on a component draws instead of moving it.
 
 | Action                      | Cursor Style        | Behavior                                              | Example                                                        |
 |-----------------------------|---------------------|--------------------------------------------------------|----------------------------------------------------------------|
@@ -64,7 +64,7 @@ Pencil lines do not connect individual components, but offer annotating capabili
 
 {{% tab header="Pen Tool" lang="en" action="true" %}}
 
-The Pen tool operates as a creator of annotation edges. Note that the pen tool has two behaviors depending upon the context in which you initiate the connection.
+The Pen tool operates as a creator of annotation edges. Note that the pen tool behaves differently depending upon where you initiate the connection.
 
 **To Activate:** `(CMD/CTRL)+E`
 
@@ -73,6 +73,9 @@ The Pen tool operates as a creator of annotation edges. Note that the pen tool h
 
 - **Component-connect Behavior**: When you click an empty spot on the canvas, and drag to another empty spot on the canvas, you get a joint (aka a terminal node) from which you can create new connections as well as new edge relationships.  
 - **Canvas-connect Behavior**: When you click an empty spot on the canvas, and drag to an existing component, you get an annotation edge relationship.
+- **Start on a component**: When you press on a component and drag, the connector starts from that component and follows it when it moves.
+
+Connectors snap to the component under the cursor, never to a Pencil stroke drawn around it, and never back onto the component they started from. Pressing on a Pencil stroke or a connector's end point starts the connector from the component underneath it; a Pencil stroke is never either end of a connector.
 
 </details>
 

content/en/kanvas/designer/whiteboarding/index.md

@@ -71,12 +71,20 @@ To hide or restore the whiteboard dock, right-click an empty area of the canvas,
 
 Shapes within the canvas offer flexibility. Select any shape to access a tooltip with options to resize, reshape, and change colors. This allows for precise adjustments similar to popular design software.
 
+Dropping a shape on the canvas leaves your next click and keystrokes with the canvas and the tools. Dropping a component adds it without opening its configurator; double-click it to configure it. To label a shape, double-click it; press <kbd>Escape</kbd> or click elsewhere to finish.
+
 #### Text Annotation Customization
 
 ![Text Box](images/text-customization.png)
 
 Text annotations come with various options. Customize fonts, sizes, alignments, and styles easily. Text boxes resize for seamless integration with the canvas.
 
+A text box you drop on the canvas opens for typing straight away, outlined while it has the keyboard. Press <kbd>Escape</kbd> or click elsewhere to finish.
+
+#### Animating Components
+
+Select a component or shape and choose **Node Animation** in its tooltip to draw attention to it: blink, ripple, bounce or pulse. Animations work on containers such as a Deployment as well as on single components, and they play again when the design is opened. Switching from one animation to another starts the new one straight away. They run at a calm pace, and Kanvas starts none when your system asks for reduced motion.
+
 #### Interactive Tooltip Interface
 
 ![Tooltip](images/tooltip.png)