docs: update GEMINI setup (#968)

# Description
Updated gemini setup. It is applicable to other models as well.


Example of `ai_learnings.md` entries:

```

## 2026-04-13 — Using extend() on a str return value

**Mistake**: Used `response_parts.extend(get_message_text(...))` and
`response_parts.extend(get_artifact_text(...))` where both functions
return `str`. `list.extend()` on a string iterates its characters,
producing `['H', 'e', 'l', 'l', 'o']` instead of `['Hello']`.

**Root cause**: Assumed the utility functions returned an iterable of
strings rather than a single string, and did not check their signatures
or run the tests before presenting the code.

**Rule**: Before calling `extend()`, verify the return type of the
expression. If it returns `str`, use `append()`. Run the tests after
any change to aggregation logic.

---

## 2026-04-13 — Assuming streaming event order without verifying across transports

**Mistake**: Added a strict check that the first streaming event must be
a `Task` or `Message`, raising a `RuntimeError` otherwise. Also used
`event.WhichOneof("event")` which fails because `StreamResponse` has no
oneof named "event" — its fields are independent message fields.
The REST transport sends a `status_update` as its first event, not a
`Task`, so the guard rejected valid responses.

**Root cause**: Assumed spec wording ("first event should be a Task")
held across all transport implementations without testing it. Did not
check the `StreamResponse` proto definition before calling `WhichOneof`.

**Rule**: Before adding ordering assumptions about streaming events,
verify the behaviour against every transport (JSONRPC, HTTP+JSON, GRPC).
Before calling `WhichOneof`, confirm the oneof name exists in the proto.

---

## 2026-04-13 — Assuming extras without checking dev dependencies

**Mistake**: Told the user that `http-server` and `grpc` extras needed
to be specified explicitly in the samples README prerequisites.

**Root cause**: Looked at the SDK's optional extras list and reasoned
from imports in the sample files, without checking whether the dev
dependency group already covered them. The dev group includes
`a2a-sdk[all]`, so a plain `uv sync` installs everything. Checking the
actual installed environment with one command would have revealed this
immediately.

**Rule**: Before writing installation instructions, verify what is
already provided by the project's dev dependencies (`uv sync` with no
flags). Do not recommend extra flags unless confirmed they are absent
from the dev group.

---

## 2026-04-13 — Proposing unverified code

**Mistake**: Proposed `_GRPC_ERROR = None` as a way to make `grpc`
optional in an `except` clause. `None` is not a valid exception type
in Python; the code would have crashed at runtime.

**Root cause**: The fix was reasoned about at a high level ("set it to
None when grpc is absent") without tracing through whether Python
actually accepts `None` in an `except` tuple. No verification step was
performed before presenting it to the user.

**Rule**: Before presenting any code change, trace through its
execution explicitly. For `except` clauses specifically: every element
in the tuple must be an exception class, never `None` or any other
non-exception value.

---

## 2026-04-14 — Race condition when reading state from DB in stream

**Mistake**: Used `active_task.get_task()` in `on_message_send_stream` to fetch the task state for the initial response. This caused a race condition where `get_task()` returned a task state that was ahead of the stream events, leading to test failures.

**Root cause**: Assumed `get_task()` would return the state corresponding to the event being processed, overlooking that the consumer loop runs independently and may have already processed subsequent events and updated the DB.

**Rule**: When processing a stream of events, do not rely on reading the current state from a shared store (like DB) to represent the state at the time of a specific event. Use state snapshots passed with the event if available.

```

Author: sokoliva

.gitignore

@@ -12,6 +12,7 @@ coverage.xml
 spec.json
 docker-compose.yaml
 .geminiignore
+docs/ai/ai_learnings.md
 
 # ITK Integration Test Artifacts
 itk/a2a-samples/

GEMINI.md

@@ -23,3 +23,20 @@
 1. **Required Reading**: You MUST read the contents of @./docs/ai/coding_conventions.md and @./docs/ai/mandatory_checks.md at the very beginning of EVERY coding task.
 2. **Initial Checklist**: Every `task.md` you create MUST include a section for **Mandatory Checks** from @./docs/ai/mandatory_checks.md.
 3. **Verification Requirement**: You MUST run all mandatory checks before declaring any task finished.
+
+## 5. Mistake Reflection Protocol
+
+When you realise you have made a mistake — whether caught by the user,
+by a tool, or by your own reasoning — you MUST:
+
+1. **Acknowledge the mistake explicitly** and explain what went wrong.
+2. **Reflect on the root cause**: was it a missing check, a false
+   assumption, skipped verification, or a gap in the workflow?
+3. **Immediately append a new entry to @./docs/ai/ai_learnings.md**
+   following the format defined in that file. This is not optional and
+   does not require user confirmation. Do it before continuing. Update user
+   about the changes to the workflow in the current chat.
+
+The goal is to treat every mistake as a signal that the workflow is
+incomplete, and to improve it in place so the same mistake cannot
+happen again.

docs/ai/ai_learnings.md

@@ -0,0 +1,19 @@
+> [!NOTE] for Users:
+> This document is meant to be read by an AI assistant (Gemini) in order to 
+> learn from its mistakes and improve its behavior on this project. Use
+> its findings to improve GEMINI.md setup.
+
+# AI Learnings
+
+A living record of mistakes made during this project and the rules
+derived from them. Every entry must follow the format below. 
+
+---
+
+## Entry format
+
+**Mistake**: What went wrong.
+**Root cause**: Why it happened.
+**Rule**: The concrete rule added to prevent recurrence.
+
+---