The UUID generation for point IDs could lead to duplicate documents in the collection if the same file is learned multiple times. Each time "simili learn" is run for the same org/repo/file combination, it creates a new point with a new UUID, resulting in duplicate entries. Consider using a deterministic ID based on org/repo/file (e.g., hash or concatenation) to enable idempotent operations where re-learning the same file updates the existing entry rather than creating duplicates.

The learn command doesn't implement rate limiting for the Gemini embedding API. If users run multiple learn commands in quick succession or try to index many files, they could hit API rate limits and experience failures. Consider adding retry logic with exponential backoff or at least documenting the rate limit considerations in the command's help text. The index command likely has similar considerations since it's shown importing the same packages.

The same UTF-8 truncation issue exists here. When truncating the definition to 2000 characters using definition[:2000], you may split a multi-byte UTF-8 character, resulting in an invalid UTF-8 string. This could cause issues when the truncated definition is used in the prompt. Consider using a rune-aware truncation approach to ensure UTF-8 safety.

The code uses hardcoded file name matching logic that could be fragile. The special case for "README.md" (line 141) means that if the first file encountered is README.md, it gets no header, but if a non-README is encountered first, then README.md would get a header when added later. This inconsistency could make the output unpredictable. Consider either always including file headers for consistency, or ordering the results to ensure README.md is always processed first if present.

Missing error handling for Qdrant client initialization. If qdrant.NewClient returns an error but the client is still non-nil (though this is unlikely), the defer statement could attempt to close a partially initialized client. While the current Qdrant client likely handles this correctly, it would be more defensive to check the error before setting up the defer.

The truncate function may split multi-byte UTF-8 characters, resulting in invalid UTF-8 strings. When slicing a string in Go by byte index (s[:maxLen]), if maxLen falls in the middle of a multi-byte character, the resulting string will be corrupted. This could cause issues when the truncated text is used in prompts or stored in the database. Consider using a rune-aware truncation approach or the strings.Cut function to ensure you don't break UTF-8 characters.

The code lacks test coverage for the new hybrid routing functionality. While there are existing tests for prompts (gemini_test.go), there are no tests for: (1) the new learn command, (2) the enhanced LLM router with semantic search and multi-file support, (3) the new helper functions (indentText), or (4) the updated routing prompt with weighting guidance. Adding tests would help ensure the hybrid routing feature works correctly and prevent regressions.

Potential unbounded memory growth when concatenating multiple documentation files for the same repository. If a repository has many documentation files that match the semantic search (e.g., 10 files with 2000 characters each), the concatenated definition could grow to 20,000+ characters. While individual files are truncated to 2000 characters, there's no limit on the total concatenated size. Consider adding a maximum total size limit for concatenated definitions to prevent token explosion and memory issues.

The semantic search for repository definitions only searches in the repo collection, which means repositories that haven't been indexed via the learn command won't be found. However, all enabled repositories from the config are included in the candidates list (lines 70-80), so unindexed repositories will still be considered for routing but will only have their short config descriptions available. This is by design for graceful degradation, but it might be worth documenting this behavior more clearly in the code comments to help future maintainers understand the fallback logic.

The code doesn't validate whether the specified file path is within the repository bounds, potentially allowing path traversal attempts. While the GitHub API itself likely validates this, adding explicit validation that the file path doesn't contain patterns like "../" would make the security boundary clearer and prevent potential issues if the GitHub client implementation changes. Consider adding path validation before calling GetFileContent.

⚠️ Potential issue | 🟡 Minor

Use rune-based truncation for UTF-8 safety.

The truncation here uses byte-length (len(definition)) and byte slicing (definition[:2000]), which can corrupt multi-byte UTF-8 characters. The truncate() helper defined at lines 13-20 already handles this correctly.

-			definition := r.Definition
-			if len(definition) > 2000 {
-				definition = definition[:2000] + "\n... (truncated)"
-			}
+			definition := truncate(r.Definition, 2000)
+			if definition != r.Definition {
+				definition += "\n(truncated)"
+			}

In `@internal/integrations/gemini/prompts.go` around lines 138 - 141, The
truncation of r.Definition uses byte-length and slicing which can break UTF-8;
replace the manual byte-based check and slice (len(definition) and
definition[:2000]) with the existing rune-safe helper truncate(), e.g. call
truncate(definition, 2000) (or adjust truncate to accept a custom suffix if you
want "... (truncated)" instead of its default) so that Definition is truncated
safely without corrupting multibyte characters.

⚠️ Potential issue | 🟡 Minor

Byte-based truncation may corrupt UTF-8 characters.

The truncation at lines 145-148 and 153-154 uses byte slicing (combined[:maxTotalSizePerRepo]), which can split multi-byte UTF-8 characters. This is the same issue as in prompts.go.

+// truncateRunes safely truncates a string to maxLen runes.
+func truncateRunes(s string, maxLen int) string {
+	runes := []rune(s)
+	if len(runes) <= maxLen {
+		return s
+	}
+	return string(runes[:maxLen])
+}

 // Inside the enrichment loop:
 						// Enforce max total size per repo
-						if len(combined) > maxTotalSizePerRepo {
+						if len([]rune(combined)) > maxTotalSizePerRepo {
 							log.Printf("[llm_router] Truncating %s definition (size: %d > %d)",
 								repoKey, len(combined), maxTotalSizePerRepo)
-							combined = combined[:maxTotalSizePerRepo] + "\n... (truncated)"
+							combined = truncateRunes(combined, maxTotalSizePerRepo) + "\n... (truncated)"
 						}

In `@internal/steps/llm_router.go` around lines 141 - 158, The code currently
truncates strings with byte slicing (combined[:maxTotalSizePerRepo] and
newDoc[:maxTotalSizePerRepo]) which can split multi-byte UTF-8 runes; replace
those slices with a rune-safe truncation helper (e.g.,
truncateToByteLimitSafely) that iterates runes and accumulates byte length until
adding the next rune would exceed maxTotalSizePerRepo, then returns the
substring up to the last whole rune plus the "\n... (truncated)" suffix; call
this helper for both the combined and newDoc truncation branches (referencing
repoDefinitions, combined, newDoc, and maxTotalSizePerRepo to locate the
changes).