Restructure chat flow: hello shows clickable book list, then engaging Q&A.

app/api/chat.py

@@ -91,7 +91,7 @@ async def init_session(
                 }
                 for b in active_books
             ],
-            show_book_selector=len(active_books) > 1,
+            show_book_selector=len(active_books) > 0,
         )
     except HTTPException:
         raise

app/models/user.py

@@ -39,7 +39,7 @@ class User(Base, TimestampMixin):
     bot_avatar_path: Mapped[str | None] = mapped_column(String(500), nullable=True)
     welcome_message: Mapped[str] = mapped_column(
         String(500),
-        default="Hi! I'm here to help you find your next great read. What are you looking for?",
+        default="Hello! I'm here to help you explore the books. Pick one below to get started.",
         nullable=False,
     )
     fallback_message: Mapped[str] = mapped_column(

app/services/formatter.py

@@ -99,25 +99,30 @@ class ResponseFormatter:
 
         return text
 
-    def format_book_selector(self, books: list[dict]) -> dict:
+    def format_book_selector(
+        self,
+        books: list[dict],
+        intro: str = "Choose a book to get started:",
+    ) -> dict:
         """Format a book selector prompt response.
 
-        Shown when intent is ambiguous and the bot needs the user to pick a book.
+        Shown when the bot needs the user to pick a book before Q&A.
 
         Args:
             books: List of dicts with 'id', 'title', 'tagline', 'cover_path'.
+            intro: Short message shown above the clickable book list.
 
         Returns:
             Dict with 'text' and 'book_selector' list.
         """
         return {
-            "text": "I can help with any of these — which one are you curious about?",
+            "text": intro,
             "book_selector": [
                 {
                     "id": book["id"],
                     "title": book["title"],
-                    "tagline": book.get("tagline", ""),
-                    "cover_url": book.get("cover_path", ""),
+                    "tagline": book.get("tagline") or "",
+                    "cover_url": book.get("cover_path") or "",
                 }
                 for book in books
             ],

app/services/prompter.py

@@ -151,24 +151,26 @@ COMPETITOR_RESPONSE = """I'm specifically focused on {author_name}'s work, \
 so I can't speak to other authors. But I'd love to show you what makes \
 {author_name}'s approach different — what are you hoping a book will help you with?"""
 
-NO_CONTEXT_RESPONSE = """Hmm, I don't have that exact detail in front of me right now. \
-{book_hint}What would you like to know — the story, the themes, or who it's perfect for?"""
+NO_CONTEXT_RESPONSE = """I don't have that exact detail handy, but here's what I do know about {book_title}. \
+What part interests you most — the story, the themes, or who it's perfect for?"""
 
-HALLUCINATION_FALLBACK_RESPONSE = """I want to stay accurate rather than guess. \
-{book_hint}Ask me something specific — a character, a theme, or what the book helps with — \
+HALLUCINATION_FALLBACK_RESPONSE = """I'd rather stay accurate than guess. \
+Ask me something specific about {book_title} — a character, a theme, or what the book helps with — \
 and I'll answer from what's actually in the text."""
 
-GREETING_RESPONSE = """Hey! I'm {bot_name}, {author_name}'s book advisor.
+GREETING_RESPONSE = """Hello! I'm {bot_name}, {author_name}'s book advisor.
 
-{book_teaser}
+Pick a book below and I'll help you explore it."""
 
-What are you in the mood for — a quick recommendation, or curious about a specific book?"""
+CATALOG_RESPONSE = """Here are the books I can walk you through.
 
-CATALOG_RESPONSE = """Here's what's in the library right now:
+Tap one to get started."""
 
-{book_list}
+BOOK_SELECTED_RESPONSE = """Great choice — {book_title}.
 
-Tell me which one catches your eye, or describe what you're looking for and I'll point you to the best fit."""
+{hook}
+
+What would you like to know? Ask me anything about the story, characters, or themes."""
 
 TOKEN_EXHAUSTED_RESPONSE = "I'm taking a short break to recharge! Check back soon."
 

app/services/rag_pipeline.py

@@ -41,7 +41,7 @@ from app.services.prompter import (
     MASTER_SYSTEM_PROMPT,
     JAILBREAK_RESPONSE, OFF_TOPIC_RESPONSE,
     NO_CONTEXT_RESPONSE, HALLUCINATION_FALLBACK_RESPONSE,
-    GREETING_RESPONSE, CATALOG_RESPONSE,
+    GREETING_RESPONSE, CATALOG_RESPONSE, BOOK_SELECTED_RESPONSE,
 )
 from app.services.reranker import rerank_chunks
 from app.services.vector_store import retrieve_chunks
@@ -179,12 +179,27 @@ async def run_pipeline(
     if not active_books:
         return _no_books_response(start_ms)
 
-    # Short-circuit: greetings and catalog questions (no vector search needed)
+    # Short-circuit: greetings and catalog questions → show clickable book list
     if intent_result.intent == "greeting" or _is_greeting(query):
-        return _greeting_response(author, active_books, start_ms)
+        return _greeting_response(author, active_books, session_context, start_ms)
 
     if intent_result.intent in ("meta", "comparison") or _is_catalog_question(query):
-        return _catalog_response(author, active_books, start_ms)
+        return _catalog_response(author, active_books, session_context, start_ms)
+
+    # Book just selected — warm intro, then user asks freely
+    if _is_book_selection_turn(query, session_context.selected_book_id, active_books):
+        book = _find_book(active_books, session_context.selected_book_id)
+        if book:
+            return _book_selected_response(book, start_ms)
+
+    # Multiple books: require a selection before Q&A
+    if len(active_books) > 1 and not session_context.selected_book_id:
+        return _books_list_response(
+            "Pick a book below first — then ask me anything about it.",
+            active_books,
+            start_ms,
+            intent="comparison",
+        )
 
     # Resolve which book to search
     target_book_id = await _resolve_book(
@@ -216,7 +231,7 @@ async def run_pipeline(
 
     if not raw_chunks:
         log.warning("No chunks retrieved")
-        return _no_context_response(query, author, active_books, start_ms)
+        return _no_context_response(query, author, active_books, session_context, start_ms)
 
     # ── Step 6: Re-ranking ────────────────────────────────────────────────────
     top_chunks = await rerank_chunks(
@@ -231,7 +246,7 @@ async def run_pipeline(
         top_chunks = raw_chunks[: cfg.RAG_RERANK_TOP_N]
 
     if not top_chunks:
-        return _no_context_response(query, author, active_books, start_ms)
+        return _no_context_response(query, author, active_books, session_context, start_ms)
 
     # ── Step 7: Context Assembly ───────────────────────────────────────────────
     context_str, context_tokens = build_context(top_chunks)
@@ -275,9 +290,8 @@ async def run_pipeline(
 
         is_faithful2, faithfulness_score = await check_faithfulness(raw_response, top_chunks)
         if not is_faithful2:
-            raw_response = HALLUCINATION_FALLBACK_RESPONSE.format(
-                book_hint=_book_hint(active_books),
-            )
+            book_title = _selected_book_title(active_books, session_context.selected_book_id)
+            raw_response = HALLUCINATION_FALLBACK_RESPONSE.format(book_title=book_title)
 
     # ── Step 10: Scope Check ──────────────────────────────────────────────────
     if not is_response_in_scope(raw_response):
@@ -439,12 +453,90 @@ def _boundary_response(text: str, start_ms: float, violation_type: str) -> Pipel
 
 
 _CATALOG_PHRASES = (
-    "uploaded book", "your book", "what book", "which book", "list book",
-    "books do you", "books you have", "books available", "about the book",
-    "tell me about", "what is the book", "what's the book", "book about",
-    "in the catalog", "in your catalog",
+    "uploaded book", "your books", "what books", "which books", "list book",
+    "books do you", "books you have", "books available", "about the books",
+    "tell me about book", "tell me about your book", "tell me about the books",
+    "what is the book", "what's the book", "in the catalog", "in your catalog",
+    "show me the book", "show me your book",
 )
 
+
+def _find_book(books: list, book_id: str | None):
+    if not book_id:
+        return None
+    return next((b for b in books if b.id == book_id), None)
+
+
+def _selected_book_title(books: list, selected_book_id: str | None) -> str:
+    book = _find_book(books, selected_book_id)
+    if book:
+        return book.title
+    if len(books) == 1:
+        return books[0].title
+    return "the books"
+
+
+def _book_selector_items(books: list) -> list[dict]:
+    items = []
+    for book in books:
+        tagline = book.tagline
+        if not tagline and book.status != "ready":
+            tagline = "Getting ready..."
+        items.append({
+            "id": book.id,
+            "title": book.title,
+            "tagline": tagline,
+            "cover_path": book.cover_path,
+        })
+    return items
+
+
+def _books_list_response(
+    text: str,
+    books: list,
+    start_ms: float,
+    intent: str = "greeting",
+) -> PipelineResult:
+    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+    formatted = _formatter.format_book_selector(_book_selector_items(books), intro=text)
+    return PipelineResult(
+        response=formatted,
+        intent=intent,
+        response_ms=elapsed_ms,
+    )
+
+
+def _book_hook(book) -> str:
+    if book.tagline:
+        return book.tagline.strip()
+    if book.ai_summary:
+        summary = book.ai_summary.strip().replace("\n", " ")
+        if len(summary) > 220:
+            cut = summary[:220].rsplit(" ", 1)[0]
+            return cut + "..."
+        return summary
+    if book.description:
+        desc = book.description.strip().replace("\n", " ")
+        return desc[:220] + ("..." if len(desc) > 220 else "")
+    if book.status != "ready":
+        return "This one is still being indexed — you can ask general questions now, and I'll get sharper as it finishes."
+    return "Ask me anything — characters, themes, plot, or who it's perfect for."
+
+
+def _is_book_selection_turn(query: str, selected_book_id: str | None, books: list) -> bool:
+    if not selected_book_id:
+        return False
+    book = _find_book(books, selected_book_id)
+    if not book:
+        return False
+    q = query.lower().strip().strip("\"'")
+    title_lower = book.title.lower()
+    if q == title_lower:
+        return True
+    if q.startswith("tell me about") and title_lower in q:
+        return True
+    return q.startswith("i'm interested in") and title_lower in q
+
 _GREETINGS = frozenset({
     "hi", "hello", "hey", "hiya", "howdy", "yo", "sup",
     "good morning", "good afternoon", "good evening", "good day",
@@ -458,84 +550,74 @@ def _is_greeting(query: str) -> bool:
 
 def _is_catalog_question(query: str) -> bool:
     q = query.lower()
-    return any(phrase in q for phrase in _CATALOG_PHRASES)
+    if any(phrase in q for phrase in _CATALOG_PHRASES):
+        return True
+    return q in ("books", "tell me about books", "about books", "the books")
 
 
-def _format_book_list(books: list) -> str:
-    lines = []
-    for book in books:
-        line = f"📖 **{book.title}**"
-        if book.tagline:
-            line += f" — {book.tagline}"
-        elif book.ai_summary:
-            summary = book.ai_summary.strip().replace("\n", " ")
-            line += f" — {summary[:160]}{'…' if len(summary) > 160 else ''}"
-        elif book.description:
-            desc = book.description.strip().replace("\n", " ")
-            line += f" — {desc[:160]}{'…' if len(desc) > 160 else ''}"
-        if book.status != "ready":
-            line += " *(indexing in progress)*"
-        lines.append(line)
-    return "\n".join(lines)
+def _greeting_response(
+    author: User,
+    books: list,
+    session_context: SessionContext,
+    start_ms: float,
+) -> PipelineResult:
+    if session_context.selected_book_id:
+        book = _find_book(books, session_context.selected_book_id)
+        title = book.title if book else "your book"
+        text = f"Hello again! Still exploring {title}? Ask me anything — I'm here for it."
+        return PipelineResult(
+            response={"text": text, "links": [], "has_links": False},
+            intent="greeting",
+            response_ms=int((time.monotonic() - start_ms) * 1000),
+        )
 
+    text = "Hello! Which book would you like to explore?"
+    return _books_list_response(text, books, start_ms, intent="greeting")
 
-def _book_hint(books: list) -> str:
-    if not books:
-        return ""
-    if len(books) == 1:
-        return f"I do know **{books[0].title}** well. "
-    return f"I have {len(books)} books I can walk you through. "
 
+def _catalog_response(
+    author: User,
+    books: list,
+    session_context: SessionContext,
+    start_ms: float,
+) -> PipelineResult:
+    if session_context.selected_book_id:
+        book = _find_book(books, session_context.selected_book_id)
+        if book:
+            return _book_selected_response(book, start_ms)
 
-def _greeting_response(author: User, books: list, start_ms: float) -> PipelineResult:
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    if len(books) == 1:
-        book_teaser = f"I can tell you everything about **{books[0].title}** — themes, characters, who it's for, all of it."
-    else:
-        titles = ", ".join(b.title for b in books[:3])
-        extra = f" and {len(books) - 3} more" if len(books) > 3 else ""
-        book_teaser = f"I know {len(books)} books inside out — including {titles}{extra}."
-    text = GREETING_RESPONSE.format(
-        bot_name=author.bot_name,
-        author_name=author.full_name or "the author",
-        book_teaser=book_teaser,
-    )
-    return PipelineResult(
-        response={"text": text, "links": [], "has_links": False},
-        intent="greeting",
-        response_ms=elapsed_ms,
-    )
+    text = CATALOG_RESPONSE
+    return _books_list_response(text, books, start_ms, intent="meta")
 
 
-def _catalog_response(author: User, books: list, start_ms: float) -> PipelineResult:
+def _book_selected_response(book, start_ms: float) -> PipelineResult:
     elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    text = CATALOG_RESPONSE.format(book_list=_format_book_list(books))
+    text = BOOK_SELECTED_RESPONSE.format(
+        book_title=book.title,
+        hook=_book_hook(book),
+    )
     return PipelineResult(
         response={"text": text, "links": [], "has_links": False},
-        intent="meta",
+        intent="question",
         response_ms=elapsed_ms,
     )
 
 
-def _no_context_response(query: str, author: User, books: list, start_ms: float) -> PipelineResult:
+def _no_context_response(
+    query: str,
+    author: User,
+    books: list,
+    session_context: SessionContext,
+    start_ms: float,
+) -> PipelineResult:
     elapsed_ms = int((time.monotonic() - start_ms) * 1000)
+    book_title = _selected_book_title(books, session_context.selected_book_id)
 
-    # Prefer book metadata when vector search came up empty
     if len(books) == 1:
         book = books[0]
-        if book.ai_summary and _is_catalog_question(query):
-            text = (
-                f"**{book.title}** — here's the gist:\n\n{book.ai_summary.strip()}\n\n"
-                "Want to go deeper on characters, themes, or who it's best for?"
-            )
-            return PipelineResult(
-                response={"text": text, "links": [], "has_links": False},
-                intent="question",
-                response_ms=elapsed_ms,
-            )
         if book.status != "ready":
             text = (
-                f"**{book.title}** is still being indexed — give it a minute and ask again. "
+                f"{book.title} is still being indexed — give it a minute and ask again. "
                 "I'll be able to answer detailed questions once processing finishes."
             )
             return PipelineResult(
@@ -544,15 +626,15 @@ def _no_context_response(query: str, author: User, books: list, start_ms: float)
                 response_ms=elapsed_ms,
             )
 
-    if len(books) > 1 and _is_catalog_question(query):
-        return _catalog_response(author, books, start_ms)
+    if _is_catalog_question(query) and not session_context.selected_book_id:
+        return _catalog_response(author, books, session_context, start_ms)
 
     default_robotic = "I want to give you the most accurate answer"
     fallback = author.fallback_message or ""
     if fallback and default_robotic not in fallback:
         text = fallback
     else:
-        text = NO_CONTEXT_RESPONSE.format(book_hint=_book_hint(books))
+        text = NO_CONTEXT_RESPONSE.format(book_title=book_title)
 
     return PipelineResult(
         response={"text": text, "links": [], "has_links": False},
@@ -569,13 +651,9 @@ def _no_books_response(start_ms: float) -> PipelineResult:
 
 
 def _book_selector_response(books: list, start_ms: float) -> PipelineResult:
-    elapsed_ms = int((time.monotonic() - start_ms) * 1000)
-    formatted = _formatter.format_book_selector([
-        {"id": b.id, "title": b.title, "tagline": b.tagline, "cover_path": b.cover_path}
-        for b in books
-    ])
-    return PipelineResult(
-        response=formatted,
+    return _books_list_response(
+        "Which book are you curious about?",
+        books,
+        start_ms,
         intent="comparison",
-        response_ms=elapsed_ms,
     )

static/widget.js

@@ -127,6 +127,7 @@
 
     .ab-bubble-text {
       padding: 10px 14px; border-radius: 16px; font-size: 13.5px; line-height: 1.55;
+      white-space: pre-wrap; word-break: break-word;
     }
     .ab-bot .ab-bubble-text {
       background: ${T.surface}; border: 1px solid ${T.border}; color: ${T.text};
@@ -148,12 +149,17 @@
     .ab-book-selector { display: flex; flex-direction: column; gap: 6px; margin-top: 4px; }
     .ab-book-btn {
       display: flex; align-items: center; gap: 10px;
-      padding: 8px 12px; border-radius: 12px; cursor: pointer;
+      padding: 10px 12px; border-radius: 12px; cursor: pointer;
       background: ${T.surface}; border: 1px solid ${T.border};
       transition: all 0.15s; font-size: 13px; color: ${T.text};
+      text-align: left; width: 100%;
     }
     .ab-book-btn:hover { border-color: ${T.brand}; background: ${T.brand}15; }
-    .ab-book-thumb { font-size: 20px; flex-shrink: 0; }
+    .ab-book-btn.ab-selected { border-color: ${T.brand}; background: ${T.brand}15; opacity: 1 !important; }
+    .ab-book-btn:disabled { opacity: 0.45; cursor: default; }
+    .ab-book-thumb { font-size: 20px; flex-shrink: 0; width: 28px; text-align: center; }
+    .ab-book-title { font-weight: 600; font-size: 13px; line-height: 1.3; }
+    .ab-book-tagline { font-size: 11px; opacity: 0.75; margin-top: 2px; line-height: 1.35; }
 
     .ab-typing { display: flex; gap: 4px; padding: 12px 14px; }
     .ab-dot {
@@ -248,16 +254,22 @@
     $bubble.addEventListener('click', openChat);
     $close.addEventListener('click', closeChat);
 
+    function mapBooks(rawBooks) {
+      return (rawBooks || []).map(b => ({
+        id: b.id,
+        title: b.title,
+        tagline: b.tagline || (b.ai_summary ? '' : ''),
+      }));
+    }
+
     async function initSession() {
       try {
         const res = await apiPost(`/chat/${CONFIG.slug}/session/init`, {}, { 'X-Subscription-Token': CONFIG.token });
         sessionId = res.session_id;
-        books = res.books || [];
+        books = mapBooks(res.books);
         $botName.textContent = res.bot_name || 'Book Advisor';
-        addBotMessage(res.welcome_message || 'Hi! How can I help you today?', [], null);
-        if (res.show_book_selector && books.length > 1) {
-          addBotMessage("Which book are you curious about?", [], books);
-        }
+        const welcome = res.welcome_message || `Hello! I'm ${res.bot_name || 'your book advisor'}.`;
+        addBotMessage(welcome, [], books.length ? books : null);
         $input.focus();
       } catch (e) {
         addBotMessage("Sorry, I'm having trouble starting. Please refresh and try again.", [], null);
@@ -285,7 +297,7 @@
         }, { 'X-Subscription-Token': CONFIG.token });
 
         typingEl.remove();
-        addBotMessage(res.text, res.links || [], res.book_selector || null);
+        addBotMessage(res.text, res.links || [], mapBooks(res.book_selector));
       } catch (e) {
         typingEl.remove();
         addBotMessage("Sorry, something went wrong. Please try again.", [], null);
@@ -296,10 +308,14 @@
       }
     }
 
+    function formatBotText(text) {
+      return escHtml(text);
+    }
+
     function addUserMessage(text) {
       const el = document.createElement('div');
       el.className = 'ab-msg ab-user';
-      el.innerHTML = `<div class="ab-bubble-text">${escHtml(text)}</div>`;
+      el.innerHTML = `<div class="ab-bubble-text">${formatBotText(text)}</div>`;
       $messages.appendChild(el);
       scrollToBottom();
     }
@@ -308,7 +324,7 @@
       const el = document.createElement('div');
       el.className = 'ab-msg ab-bot';
 
-      let html = `<div class="ab-bubble-text">${escHtml(text)}</div>`;
+      let html = `<div class="ab-bubble-text">${formatBotText(text)}</div>`;
 
       if (links && links.length) {
         html += `<div class="ab-links">`;
@@ -321,11 +337,12 @@
       if (bookSelector && bookSelector.length) {
         html += `<div class="ab-book-selector">`;
         bookSelector.forEach(b => {
-          html += `<button class="ab-book-btn" data-book-id="${escAttr(b.id)}">
+          const selected = selectedBookId === b.id;
+          html += `<button type="button" class="ab-book-btn${selected ? ' ab-selected' : ''}" data-book-id="${escAttr(b.id)}"${selected ? ' disabled' : ''}>
           <span class="ab-book-thumb">📖</span>
-          <div style="text-align:left">
-            <div style="font-weight:600;font-size:13px">${escHtml(b.title)}</div>
-            ${b.tagline ? `<div style="font-size:11px;opacity:0.7;margin-top:1px">${escHtml(b.tagline)}</div>` : ''}
+          <div>
+            <div class="ab-book-title">${escHtml(b.title)}</div>
+            ${b.tagline ? `<div class="ab-book-tagline">${escHtml(b.tagline)}</div>` : ''}
           </div>
         </button>`;
         });
@@ -335,21 +352,7 @@
       el.innerHTML = html;
 
       el.querySelectorAll('.ab-book-btn').forEach(btn => {
-        btn.addEventListener('click', () => {
-          const bookId = btn.getAttribute('data-book-id');
-          selectedBookId = bookId;
-          const book = bookSelector.find(b => b.id === bookId);
-          addUserMessage(`Tell me about "${book?.title}"`);
-          apiPost(`/chat/${CONFIG.slug}`, {
-            session_id: sessionId,
-            message: `Tell me about "${book?.title}"`,
-            selected_book_id: bookId,
-          }, { 'X-Subscription-Token': CONFIG.token }).then(res => {
-            addBotMessage(res.text, res.links || [], null);
-          });
-          el.querySelectorAll('.ab-book-btn').forEach(b => b.style.opacity = '0.4');
-          btn.style.opacity = '1'; btn.style.borderColor = T.brand;
-        });
+        btn.addEventListener('click', () => selectBook(btn, bookSelector));
       });
 
       el.querySelectorAll('.ab-link-btn').forEach(a => {
@@ -367,6 +370,45 @@
       scrollToBottom();
     }
 
+    async function selectBook(btn, bookSelector) {
+      if (isLoading || btn.disabled) return;
+
+      const bookId = btn.getAttribute('data-book-id');
+      const book = bookSelector.find(b => b.id === bookId);
+      if (!book) return;
+
+      selectedBookId = bookId;
+      addUserMessage(book.title);
+
+      btn.closest('.ab-book-selector')?.querySelectorAll('.ab-book-btn').forEach(b => {
+        b.disabled = true;
+        b.style.opacity = '0.45';
+      });
+      btn.classList.add('ab-selected');
+      btn.style.opacity = '1';
+
+      const typingEl = addTypingIndicator();
+      isLoading = true;
+      $send.disabled = true;
+
+      try {
+        const res = await apiPost(`/chat/${CONFIG.slug}`, {
+          session_id: sessionId,
+          message: book.title,
+          selected_book_id: bookId,
+        }, { 'X-Subscription-Token': CONFIG.token });
+        typingEl.remove();
+        addBotMessage(res.text, res.links || [], null);
+      } catch (e) {
+        typingEl.remove();
+        addBotMessage("Sorry, something went wrong. Please try again.", [], null);
+      } finally {
+        isLoading = false;
+        $send.disabled = false;
+        $input.focus();
+      }
+    }
+
     function addTypingIndicator() {
       const el = document.createElement('div');
       el.className = 'ab-msg ab-bot';