---

name: bible-lookup-helper description: Expert assistant for Bible reference lookups, full-text search, topic search, Strong's lookups, Q&A search, and AI-powered semantic search in the Raamattu Nyt project. Use when (1) fetching specific verses by reference (Joh 3:16), (2) building or modifying the search experience (SearchPage with 7 tabs: jakeet/aiheet/Strong's/kysymykset/videot/muut/comparison), (3) calling search RPCs (search_text, search_topics_with_aliases, search_verses_by_strongs, get_approved_ai_summary), (4) classifying user queries (verse vs topic vs Strong's vs free-text), (5) working with anchor questions, AI summaries, or topic synonyms, (6) validating OSIS references, or (7) choosing the right lookup pattern across modalities.

Bible Lookup Helper

Covers two related but distinct workflows:

• Lookup — fetch a specific verse / chapter / range when the reference is already known
• Search — surface results across verses, topics, Strong's, questions, and AI summaries when the user types a free-form query

When in doubt which one applies: a known reference (Joh 3:16) → lookup; a free-form query (rakkaus, armo ja totuus) → search. The search path itself classifies the query and picks the right backend.

Context Files (Read First)

For schema and API details, read from Docs/context/:

• Docs/context/db-schema-short.md - Bible schema tables
• Docs/context/supabase-map.md - RPC functions list

Detailed Search Reference

For the full search architecture — 7 tabs, per-modality RPCs, query classification, AI-summary caching/feedback, anchor questions, recent additions — read references/search-system.md.

Read it when the task touches:

• The SearchPage UI or any *SearchSection.tsx component
• A search RPC that's not in the basic lookup list below
• AI semantic search, summary caching, or thumbs-up/down feedback
• Topic aliases / synonyms / translation
• Anchor questions or similar-questions sections
• Query classification logic (classifyQuery, isReference, intent routing)

Capabilities

• Generate correct RPC function calls for Bible lookups
• Validate OSIS reference formats
• Suggest optimal lookup patterns (verse vs chapter vs range vs search)
• Provide book name aliases and normalization
• Convert between different reference formats
• Route free-form queries to the right search RPC (verses / topics / Strong's / Q&A / AI)
• Reason about the AI-semantic-search flow end-to-end: cache key (normalizeQueryKey), ai_summary_feedback table, ai-semantic vs ai-search feature_key, quality circuit-breaker (thumbs_down ratio), and the verse-text rendering chain (AISemanticResults → fetchVerseTexts → mapFinnishToOsis → get_verses_by_ref)

When to delegate to other skills

This skill owns the SEARCH side of AI semantic search (cache, routing, rendering, feature_key selection at the call site). For deeper AI configuration, hand off to ai-prompt-manager:

Question / task	Skill
"Why is the AI summary card blank for <book> <ch>:<v>?"	This skill (verseTextService mapping)
"Cache miss when I expected a hit for <query>"	This skill (normalizeQueryKey, prefixed-key rule)
"Add a new AI feature key for X"	ai-prompt-manager (registration SQL pattern)
"Change which model runs ai_semantic_search"	ai-prompt-manager (ai_feature_bindings)
"Getting feature_locked / operation_not_found / 429"	ai-prompt-manager (quota + plan_feature_access)
"Edit the prompt template that generates summaries"	ai-prompt-manager (ai_prompt_versions)
"Build a new AI UI panel"	ai-prompt-manager (AIProcessingPanel/AIProgressBar/AIErrorBanner)

Usage Examples

Example 1: Generate RPC call for single verse

User: "How do I fetch John 3:16 in Finnish?" Assistant:

const { data } = await supabase.rpc('get_verse_by_ref', {
  p_ref_book: 'John',
  p_chapter: 3,
  p_verse: 16,
  p_version_code: 'finstlk201',
  p_language_code: 'fi'
});

Example 2: Generate RPC call for chapter

User: "Get all verses from Genesis chapter 1" Assistant:

const { data: verses } = await supabase.rpc('get_chapter_by_ref', {
  p_ref_book: 'Genesis',
  p_chapter: 1,
  p_version_code: 'finstlk201',
  p_language_code: 'fi'
});

Example 3: Validate reference format

User: "Is '1. Joh.4:8' a valid reference?" Assistant: Yes, this is valid. It follows the Finnish format for numbered books:

• Book: 1. Johannes (1 John)
• Chapter: 4
• Verse: 8

Alternative valid formats:

• 1 Joh.4:8 (without period after number)
• 1.Joh.4:8 (no space)
• 1 John 4:8 (English)

Example 4: Convert reference formats

User: "Convert 'Joh.3:16' to OSIS format" Assistant: OSIS format: John.3.16

Finnish formats accepted:

• Joh.3:16 (with colon)
• Joh.3.16 (with period)
• Johannes 3:16 (full name)

Available RPC Functions

Single Verse

get_verse_by_ref(p_ref_book, p_chapter, p_verse, p_version_code, p_language_code)
→ {osis, text_content, verse_id}

Full Chapter

get_chapter_by_ref(p_ref_book, p_chapter, p_version_code, p_language_code)
→ [{book_code, book_name, chapter_number, verse_number, osis, text_content, verse_id, version_code}]

Verse Range

get_verses_by_ref(p_ref_book, p_chapter, p_verses[], p_version_code, p_language_code)
→ Same as chapter but filtered

Verse Study (with Strong's)

get_verse_study_data(p_version_code, p_book_name, p_chapter, p_verse)
→ Full study data including KJV Strong's tags

Text Search

search_text(p_query, p_version_code, p_limit)
search_text_extended(p_query, p_version_code, p_limit)
→ [{book_name, chapter_number, verse_number, osis, text_content, verse_id}]

Supported Bible Versions

Code	Name	Language
finstlk201	Pyhä Raamattu (STLK 2017) - DEFAULT	Finnish
finpr_finn	Pyhä Raamattu (1933/1938)	Finnish
KJV	King James Version with Strong's	English

Book Name Aliases

The system recognizes multiple formats:

• Finnish: Joh, Johannes, Johanneksen evankeliumi
• English: John, Jn, Gospel of John
• Numbered books: 1. Joh, 1 Joh, 1Joh, 1 John
• Moses books: 1. Moos, 1 Moos, Gen, Genesis

Best Practices

1. Always use RPC functions - Never query tables directly
2. Default version - Use finstlk201 for Finnish content
3. Cache results - Use React Query to cache lookups
4. Preload - Load next chapter for better UX
5. Error handling - Check for empty results
6. OSIS format - Use for cross-version references

Performance Tips

• Single verse: ~20ms
• Full chapter: ~50ms
• Text search: ~100ms
• Use indexed fields for best performance
• Limit search results with p_limit parameter

Reference Format Patterns

Valid Formats

• Book.Chapter:Verse - e.g., Joh.3:16
• Book.Chapter.Verse - e.g., Joh.3.16
• Book Chapter:Verse - e.g., John 3:16
• Number. Book.Chapter:Verse - e.g., 1. Joh.4:8

Range Formats

• Book.Chapter:Verse-Verse - e.g., Joh.3:16-17
• Book.Chapter:Verse-Chapter:Verse - e.g., Joh.3:16-4:2

Related Documentation

• See Docs/03-API.md for complete API reference