docs: update Each documentation and menu reference for clarity and optimization guidance

Author: Varixo

packages/docs/src/routes/docs/(qwik)/core/each/index.mdx

@@ -9,7 +9,9 @@ import CodeSandbox from '../../../../../components/code-sandbox/index.tsx';
 
 `Each` is a built-in Qwik component for rendering keyed lists.
 
-It is most useful when list items have a stable identity and you want Qwik to preserve and move existing rows instead of re-rendering the whole list when the order changes.
+For most list rendering, write normal `items.map()` code and let Qwik optimize compatible keyed loops automatically.
+
+This page documents the manual `Each` API for the cases where you want to use it explicitly. For the default list-rendering guidance, see [Rendering](../rendering/index.mdx).
 
 <CodeSandbox src="/src/routes/demo/component/each/index.tsx" style={{ height: '10em' }}>
 ```tsx /Each/ /key$/ /item$/
@@ -76,33 +78,17 @@ export default component$(() => {
 });
 ```
 
-## `Each` vs `items.map()`
-
-If your list items have stable keys, prefer `Each`.
-
-It is the specialized keyed-list primitive in Qwik and is designed to preserve and move existing rows efficiently.
-
-Use `items.map()` for simple list rendering or when you do not have a stable key:
-
-```tsx
-<ul>
-  {todos.value.map((todo) => (
-    <li key={todo.id}>{todo.label}</li>
-  ))}
-</ul>
-```
+## When to use manual `Each`
 
-Prefer `Each` when:
+Most applications should use `items.map()` in component templates.
 
-- items have stable ids
-- rows are frequently reordered, inserted, or removed
-- you want to preserve existing row DOM and component instances
+Manual `Each` is useful when:
 
-Prefer `map()` when:
+- you want to make the keyed-list behavior explicit in the source
+- you are building a reusable abstraction around `Each`
+- you prefer the explicit `items`, `key$`, and `item$` API shape for a specific list
 
-- there is no stable key for the item
-- you want ordinary JSX list rendering without `Each`'s keyed-row preservation behavior
-- the row output should be recomputed from replaced item objects even when the key stays the same
+If you want the usual authoring experience, use `items.map()` and let the optimizer rewrite compatible loops for you.
 
 ## How keyed updates work
 
@@ -127,5 +113,5 @@ Using unstable keys defeats the main benefit of `Each` and can produce confusing
 
 ## Related
 
-- For general list rendering, see [Rendering](../rendering/index.mdx)
+- For default list rendering with `items.map()`, automatic optimization, warnings, and opt-out comments, see [Rendering](../rendering/index.mdx)
 - For the generated API entry, see [API Reference](/api/qwik/#each)

packages/docs/src/routes/docs/(qwik)/core/rendering/index.mdx

@@ -100,9 +100,9 @@ export const Child = component$((props: { name: string }) => {
 
 ### Rendering a list of items
 
-Qwik supports rendering lists with either `items.map()` or the [`Each`](../each/index.mdx) component.
+Write lists with normal `items.map()` in component templates.
 
-For keyed collections, prefer [`Each`](../each/index.mdx). If you render with `items.map()`, every item in the list must have a unique `key` property on the first child returned by the mapping function. The `key` must be a string or number and must be unique within the list.
+If you render with `items.map()`, every item in the list must have a unique `key` property on the first child returned by the mapping function. The `key` must be a string or number and must be unique within the list.
 
 ```tsx {6} /data.map/ /key/#a
 import { component$ } from '@qwik.dev/core';
@@ -122,6 +122,55 @@ export const Parent = component$(() => {
 
 <Note>It is not recommended to use the array's index as the key unless you can guarantee that the data for a given key will always be the same. It is always preferred to use some unique identifier from the data as the key.</Note>
 
+## Automatic `.map()` optimization
+
+For compatible render loops, Qwik optimizes keyed `items.map()` calls into an internal [`Each`](../each/index.mdx)-style keyed list automatically during compilation.
+
+The optimization applies when:
+
+- the callback returns a single JSX node
+- the first returned node has a `key`
+- the key does not use the callback's index parameter
+- the key is not derived from a function call
+
+For example, this authoring pattern:
+
+```tsx
+{items.value.map((item) => (
+  <div key={item.id}>{item.label}</div>
+))}
+```
+
+can be optimized to the same keyed-list machinery used by manual `Each`.
+
+If a `.map()` looks like a keyed list render but cannot be optimized, Qwik emits a `map-to-each` optimizer warning with the reason. If the conditions are not met, the original `.map()` stays unchanged.
+
+Common reasons for the warning are:
+
+- the returned JSX node is missing a `key`
+- the key uses the callback's index parameter
+- the key comes from a function call
+- the callback does not return a single JSX node
+
+## Disabling the optimization
+
+If you want to opt out for a specific render loop, use:
+
+```tsx
+{
+  /* @qwik-disable-next-line map-to-each */
+  items.map((item) => <div key={item.id}>{item.label}</div>)
+}
+```
+
+That disables the optimization and silences `map-to-each` warnings for that call.
+
+## Manual `Each`
+
+Manual [`Each`](../each/index.mdx) is still available as a public API, but it is now the explicit or advanced form rather than the default recommendation.
+
+Use manual `Each` when you want to make the keyed-list behavior explicit in the source or when you are building an abstraction around its `items`, `key$`, and `item$` props.
+
 ### Rendering Conditionally
 
 Conditional rendering is done with the Javascipt [ternary operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator) `?`, the `&&` operator, or just by using `if` statements.

packages/docs/src/routes/docs/menu.md

@@ -16,8 +16,8 @@
 - [Tasks & Lifecycle](</docs/(qwik)/core/tasks/index.mdx>)
 - [Context](</docs/(qwik)/core/context/index.mdx>)
 - [Slots](</docs/(qwik)/core/slots/index.mdx>)
-- [Each](</docs/(qwik)/core/each/index.mdx>)
 - [Rendering](</docs/(qwik)/core/rendering/index.mdx>)
+- [Each (Reference)](</docs/(qwik)/core/each/index.mdx>)
 - [Styling](</docs/(qwik)/core/styles/index.mdx>)
 - [API Reference](/api/qwik/)