feat(gemini): multimodal content embedding via shared Content API (#459)

* docs(06): capture phase context

* docs(state): record phase 6 context session

* docs(06): research gemini multimodal adoption phase

* docs(phase-6): add validation strategy

* docs(06): create phase plan

* feat(06-01): add content.go with conversion helpers and capability derivation

- neutralIntentToTaskType map for 5 shared neutral intents to Gemini task types
- extToMIME map for file extension MIME inference
- capabilitiesForModel: full 5-modality caps for gemini-embedding-2-preview, text-only for others
- resolveBytes: handles bytes, base64, file, and URL source kinds
- resolveMIME: falls back from BinarySource.MIMEType to file extension
- validateMIMEModality: rejects mismatched MIME/modality combinations
- convertToGenaiContent / convertToGenaiContents: converts shared Content to genai.Content
- resolveTaskTypeForContent: ProviderHints > intent mapper > default

* feat(06-01): implement ContentEmbeddingFunction+CapabilityAware+IntentMapper on GeminiEmbeddingFunction

- DefaultEmbeddingModel updated to gemini-embedding-2-preview; LegacyEmbeddingModel added for gemini-embedding-001
- Compile-time assertions for ContentEmbeddingFunction, CapabilityAware, IntentMapper
- Client.CreateContentEmbedding: per-item task type resolution for single items, batch uses default
- GeminiEmbeddingFunction.EmbedContent and EmbedContents: validate against caps then delegate to CreateContentEmbedding
- GeminiEmbeddingFunction.Capabilities: delegates to capabilitiesForModel
- GeminiEmbeddingFunction.MapIntent: translates 5 neutral intents, rejects non-neutral with escape-hatch hint
- RegisterContent("google_genai") added to init() alongside existing RegisterDense

* docs(06-01): complete gemini multimodal content interface plan

- 06-01-SUMMARY.md: full plan summary with task commits, decisions, and patterns
- STATE.md: advanced to plan 2, recorded metrics, added key decisions
- ROADMAP.md: updated phase 6 plan progress (1/2 summaries)
- REQUIREMENTS.md: marked GEM-01, GEM-02, GEM-03 complete

* test(06-02): add unit tests for gemini multimodal content implementation

- TestCapabilitiesForModel: 3 model variants (preview, legacy, unknown)
- TestGeminiCapabilities: interface method on GeminiEmbeddingFunction
- TestMapIntent: all 5 neutral intents map to correct Gemini task types
- TestMapIntentRejectsNonNeutral: non-neutral intents rejected with ProviderHints hint
- TestResolveMIME: explicit MIME, extension fallback, error cases
- TestValidateMIMEModality: valid and invalid MIME-modality combinations
- TestResolveBytesKinds: bytes, base64, file kinds (URL skipped)
- TestConvertToGenaiContent*: text, binary, mixed, error cases
- TestResolveTaskTypeForContent: priority chain (hints > intent > default)
- TestEmbedContentLegacyModelRejectsMultimodal: D-03/D-04 negative case
- TestGeminiContentRegistration: GEM-03 HasContent + BuildContent round-trip
- TestGeminiContentConfigRoundTrip: Name + GetConfig -> BuildContent
- TestDefaultModelChanged: D-01 constant verification

* docs(06-02): complete gemini multimodal content tests plan

- 06-02-SUMMARY.md: 19-function unit test suite proving GEM-01/GEM-02/GEM-03
- STATE.md: advanced to last-plan, 16/16 plans complete, decisions recorded
- ROADMAP.md: phase 06 marked Complete (2/2 summaries)

* docs(phase-06): complete phase execution

* docs(phase-06): evolve PROJECT.md after phase completion

* test(gemini): add multimodal content integration tests and mock-based coverage

- Add testdata/ with 5 modality assets (PNG, MP3, MP4, PDF, text)
- Add gemini_content_integration_test.go (ef tag): text, image, audio,
  video, PDF, mixed-part, batch, intent, ProviderHints, dimension tests
- Add mock-based unit tests for CreateContentEmbedding, EmbedContent,
  EmbedContents defensive paths (empty response, API error, validation)
- Add convertToGenaiContents, resolveBytes URL, unsupported kind tests
- Trim MP3 to 60s (Gemini 80s audio limit)
- Fix lint: gci import ordering on compile-time assertions
- Coverage: 57.9% → 84.7% (unit-only: 72.9%)

* docs: add phase 8 for Gemini/Nemotron documentation

* fix(gemini): add nil source guards, structural validation, and configurable file size limit

* refactor(gemini): use genai.NewPartFromURI for URL sources instead of client-side fetch

* feat(gemini): honor Content.Dimension in single-content embedding requests

* fix(gemini): derive capabilities from effective model when context override is set

* fix(gemini): enforce MaxBatchSize on EmbedContents and default to 250

* fix(gemini): validate IntentMapper result with IsValid() for consistency

* fix(gemini): add path traversal guard, use LimitReader for file reads, validate in CreateContentEmbedding

- Reject file paths containing ".." to prevent path traversal
- Replace os.Stat+os.ReadFile with os.Open+io.LimitReader to eliminate TOCTOU race
- Add ValidateContents call in CreateContentEmbedding for defense-in-depth

* fix(gemini): reject per-item overrides in batch requests and check nil embedding values

- Error when batch contents have per-item Intent, Dimension, or ProviderHints
  since Gemini applies one config per batch (prevents silent data corruption)
- Check for nil embedding Values in API response (aligns with Voyage pattern)

* fix(gemini): enforce MaxFileSize on bytes and base64 payloads

The genai SDK performs no client-side size validation. Enforce the
configurable limit (default 100MB) on all inline payload types
consistently, not just file reads.

* docs(gemini): document batch limitations for per-item Content overrides

* docs(phase-06): update validation strategy with Nyquist audit results

* fix(gemini): pre-check base64 payload size before decoding to avoid OOM allocation

Author: tazarov

.planning/PROJECT.md

@@ -60,4 +60,4 @@ Go applications can use Chroma and embedding providers through a stable, portabl
 | Add vLLM/Nemotron as Phase 7 | Second provider (nvidia/omni-embed-nemotron-3b via vLLM) proves portability beyond a single provider | ✓ Good |
 
 ---
-*Last updated: 2026-03-20 — Phase 5 complete, Content API documented, DOCS-02 test coverage verified*
+*Last updated: 2026-03-20 — Phase 6 complete, Gemini natively implements ContentEmbeddingFunction+CapabilityAware+IntentMapper for 5 modalities, registered in content factory*

.planning/REQUIREMENTS.md

@@ -34,9 +34,9 @@
 
 ### Gemini Multimodal Adoption
 
-- [ ] **GEM-01**: Gemini implements `SharedContentEmbeddingFunction` and `CapabilityAware` for text, image, audio, video, and PDF modalities
-- [ ] **GEM-02**: Neutral intents map to Gemini task types with explicit errors for unsupported combinations
-- [ ] **GEM-03**: Gemini is registered in the multimodal factory/registry path with config round-trip support
+- [x] **GEM-01**: Gemini implements `SharedContentEmbeddingFunction` and `CapabilityAware` for text, image, audio, video, and PDF modalities
+- [x] **GEM-02**: Neutral intents map to Gemini task types with explicit errors for unsupported combinations
+- [x] **GEM-03**: Gemini is registered in the multimodal factory/registry path with config round-trip support
 
 ### vLLM/Nemotron Provider Validation
 
@@ -83,9 +83,9 @@
 | MAP-02 | Phase 4 | Complete |
 | DOCS-01 | Phase 5 | Complete |
 | DOCS-02 | Phase 5 | Complete |
-| GEM-01 | Phase 6 | Pending |
-| GEM-02 | Phase 6 | Pending |
-| GEM-03 | Phase 6 | Pending |
+| GEM-01 | Phase 6 | Complete |
+| GEM-02 | Phase 6 | Complete |
+| GEM-03 | Phase 6 | Complete |
 | VLLM-01 | Phase 7 | Pending |
 | VLLM-02 | Phase 7 | Pending |
 

.planning/ROADMAP.md

@@ -19,7 +19,7 @@ This roadmap initializes GSD planning for the current brownfield milestone focus
 - [x] **Phase 3: Registry and Config Integration** - Extend registry/build-from-config and collection auto-wiring for richer multimodal interfaces. (completed 2026-03-20)
 - [x] **Phase 4: Provider Mapping and Explicit Failures** - Define neutral intent mapping and surface unsupported combinations explicitly. (completed 2026-03-20)
 - [x] **Phase 5: Documentation and Verification** - Update docs, examples, and tests around portable multimodal usage and compatibility. (completed 2026-03-20)
-- [ ] **Phase 6: Gemini Multimodal Adoption** - Wire Gemini into the shared multimodal contract with full modality support. (issue #443)
+- [x] **Phase 6: Gemini Multimodal Adoption** - Wire Gemini into the shared multimodal contract with full modality support. (issue #443) (completed 2026-03-20)
 - [ ] **Phase 7: vLLM/Nemotron Provider Validation** - Add vLLM OpenAI-compatible provider targeting nvidia/omni-embed-nemotron-3b to validate the foundation end-to-end.
 
 ## Phase Details
@@ -110,8 +110,11 @@ Plans:
   3. Existing `EmbedDocuments`/`EmbedQuery` behavior remains unchanged.
   4. Gemini is registered in the multimodal factory/registry path with config round-trip support.
   5. Unit tests cover request construction, intent mapping, and backward-compatible wrappers.
+**Plans**: 2 plans
 
-Plans: TBD during planning
+Plans:
+- [x] 06-01-PLAN.md — Implement content helpers, interface methods, CreateContentEmbedding, registration, and default model update
+- [x] 06-02-PLAN.md — Add unit tests for capability derivation, intent mapping, MIME resolution, content conversion, negative cases, and config round-trip
 
 ### Phase 7: vLLM/Nemotron Provider Validation
 **Goal:** Add a vLLM OpenAI-compatible embedding provider targeting nvidia/omni-embed-nemotron-3b to validate the shared multimodal contract against a second real multimodal model beyond Gemini.
@@ -134,5 +137,15 @@ Plans: TBD during planning
 | 3. Registry and Config Integration | 3/3 | Complete   | 2026-03-20 |
 | 4. Provider Mapping and Explicit Failures | 2/2 | Complete   | 2026-03-20 |
 | 5. Documentation and Verification | 2/2 | Complete   | 2026-03-20 |
-| 6. Gemini Multimodal Adoption | - | Not started | - |
+| 6. Gemini Multimodal Adoption | 2/2 | Complete   | 2026-03-20 |
 | 7. vLLM/Nemotron Provider Validation | - | Not started | - |
+
+### Phase 8: Document Gemini and Nemotron multimodal embedding functions
+
+**Goal:** [To be planned]
+**Requirements**: TBD
+**Depends on:** Phase 7
+**Plans:** 0 plans
+
+Plans:
+- [ ] TBD (run /gsd:plan-phase 8 to break down)

.planning/STATE.md

@@ -1,15 +1,15 @@
 ---
 gsd_state_version: 1.0
-milestone: v0.4
-milestone_name: milestone
+milestone: v0.4.1
+milestone_name: Provider-Neutral Multimodal Foundations
 status: unknown
-stopped_at: Completed 05-01-PLAN.md
-last_updated: "2026-03-20T16:55:29.356Z"
+stopped_at: Completed 06-02-PLAN.md
+last_updated: "2026-03-20T20:11:45.881Z"
 progress:
   total_phases: 7
-  completed_phases: 5
-  total_plans: 14
-  completed_plans: 14
+  completed_phases: 6
+  total_plans: 16
+  completed_plans: 16
 ---
 
 # Project State
@@ -19,12 +19,12 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-18)
 
 **Core value:** Go applications can use Chroma and embedding providers through a stable, portable API that minimizes provider-specific friction.
-**Current focus:** Phase 05 — documentation-and-verification
+**Current focus:** Phase 06 — gemini-multimodal-adoption
 
 ## Current Position
 
-Phase: 05 (documentation-and-verification) — EXECUTING
-Plan: 1 of 2
+Phase: 7
+Plan: Not started
 
 ## Performance Metrics
 
@@ -58,6 +58,8 @@ Plan: 1 of 2
 | Phase 04 P02 | 4 | 2 tasks | 2 files |
 | Phase 05 P02 | 2 | 1 tasks | 1 files |
 | Phase 05 P01 | 2 | 2 tasks | 2 files |
+| Phase 06 P01 | 5 | 2 tasks | 2 files |
+| Phase 06 P02 | 10min | 1 tasks | 1 files |
 
 ## Accumulated Context
 
@@ -90,13 +92,19 @@ Recent decisions affecting current work:
 - [Phase 05-01]: Show mixed-part Roboflow example with separate Content items via EmbedContents (one Part per Content due to adapter constraint)
 - [Phase 05-01]: Frame both EmbedDocuments and Content API as coexisting indefinitely — no deprecation signal in docs
 - [Phase 05-01]: Escape-hatch admonition for ProviderHints references godoc rather than documenting mechanism inline
+- [Phase 06-01]: Default model updated to gemini-embedding-2-preview; LegacyEmbeddingModel constant added for gemini-embedding-001
+- [Phase 06-01]: Batch requests use default task type for all items; single-item requests allow per-item ProviderHints override
+- [Phase 06-01]: resolveMIME falls back from BinarySource.MIMEType to file extension; fails explicitly when neither resolves
+- [Phase 06-02]: Construct GeminiEmbeddingFunction via struct literal in unit tests to avoid genai.NewClient network calls while keeping tests hermetic
+- [Phase 06-02]: EmbedContentLegacyModelRejectsMultimodal uses dual-string check because ValidateContentSupport produces message with 'does not support' not 'unsupported'
 
 ### Roadmap Evolution
 
 - Project initialized around provider-neutral multimodal embedding foundations (#442).
 - Rebranded milestone v0.5 → v0.4.1 (all changes additive, no public API breakage).
 - Added Phase 6: Gemini Multimodal Adoption (#443).
 - Added Phase 7: vLLM/Nemotron Provider Validation (nvidia/omni-embed-nemotron-3b).
+- Added Phase 8: Document Gemini and Nemotron multimodal embedding functions.
 
 ### Pending Todos
 
@@ -122,6 +130,6 @@ None yet.
 
 ## Session
 
-**Last Date:** 2026-03-20T16:37:59.612Z
-**Stopped At:** Completed 05-01-PLAN.md
+**Last Date:** 2026-03-20T20:05:03.640Z
+**Stopped At:** Completed 06-02-PLAN.md
 **Resume File:** None

.planning/config.json

@@ -3,7 +3,7 @@
   "granularity": "standard",
   "parallelization": true,
   "commit_docs": true,
-  "model_profile": "balanced",
+  "model_profile": "quality",
   "workflow": {
     "research": true,
     "plan_check": true,