feat(vector): add Deck card vector search with visualization support

Adds comprehensive vector search support for Nextcloud Deck cards,
including semantic search indexing, chunk preview in the vector viz UI,
and proper deep linking to cards.

**Vector Search Indexing**
- Add deck_card scanning in scanner.py (scan_deck_cards function)
- Index cards from non-archived, non-deleted boards
- Store metadata: board_id, board_title, stack_id, stack_title, card_type, duedate, owner
- Content structure: title + "\n\n" + description (matches indexing format)
- Incremental sync based on lastModified timestamp
- Deletion tracking with grace period

**Vector Visualization Support**
- Add deck_card handler in context.py for chunk preview expansion
- Include board_id in search result metadata (bm25_hybrid.py, semantic.py)
- Expose metadata in viz_routes.py JSON responses
- Update vector-viz.js to construct proper Deck URLs: /apps/deck/board/{board_id}/card/{card_id}
- Update vector_viz.html filter label from "Deck" to "Deck Cards"

**Bug Fixes**
- Skip soft-deleted boards (deletedAt > 0) to prevent 403 Forbidden errors
- Applies to scanner, processor, and context expansion code paths
- Deck API returns deleted boards but rejects stack access with 403

**Testing**
- Add integration tests in test_deck_vector_search.py:
  - test_deck_card_semantic_search: Filtered search with doc_type="deck_card"
  - test_deck_card_appears_in_cross_app_search: Cross-app search includes deck cards
  - test_deck_card_chunk_context: Chunk context fetching for viz preview

**Documentation**
- Update README.md: Add Deck cards to semantic search feature list
- Update semantic-search-architecture.md: Document deck_card support
- Update nc_semantic_search tool documentation

**Type Safety**
- Fix type narrowing for page_boundaries (could be None) using cast()
- Fix scanner.py payload None check for type safety

Resolves vector search for Deck cards across indexing, search, and visualization.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

nextcloud_mcp_server/search/bm25_hybrid.py

@@ -219,6 +219,18 @@ class BM25HybridSearchAlgorithm(SearchAlgorithm):
 
                 seen_chunks.add(chunk_key)
 
+                # Build metadata dict with common fields
+                metadata = {
+                    "chunk_index": result.payload.get("chunk_index"),
+                    "total_chunks": result.payload.get("total_chunks"),
+                    "search_method": f"bm25_hybrid_{self.fusion_name}",
+                }
+
+                # Add deck_card-specific metadata for frontend URL construction
+                if doc_type == "deck_card":
+                    if board_id := result.payload.get("board_id"):
+                        metadata["board_id"] = board_id
+
                 # Return unverified results (verification happens at output stage)
                 results.append(
                     SearchResult(
@@ -227,11 +239,7 @@ class BM25HybridSearchAlgorithm(SearchAlgorithm):
                         title=result.payload.get("title", "Untitled"),
                         excerpt=result.payload.get("excerpt", ""),
                         score=result.score,  # Fusion score (RRF or DBSF)
-                        metadata={
-                            "chunk_index": result.payload.get("chunk_index"),
-                            "total_chunks": result.payload.get("total_chunks"),
-                            "search_method": f"bm25_hybrid_{self.fusion_name}",
-                        },
+                        metadata=metadata,
                         chunk_start_offset=result.payload.get("chunk_start_offset"),
                         chunk_end_offset=result.payload.get("chunk_end_offset"),
                         page_number=result.payload.get("page_number"),

nextcloud_mcp_server/search/context.py

@@ -544,6 +544,46 @@ async def _fetch_document_text(
             content_parts.append("")  # Blank line
             content_parts.append(body_markdown)
             return "\n".join(content_parts)
+        elif doc_type == "deck_card":
+            # Fetch card from Deck API
+            # Note: Deck API requires board_id and stack_id, but we don't store those
+            # We need to search through boards to find the card (same as processor.py)
+            boards = await nc_client.deck.get_boards()
+            card_found = False
+
+            for board in boards:
+                if card_found:
+                    break
+
+                # Skip deleted boards (soft delete: deletedAt > 0)
+                if board.deletedAt > 0:
+                    logger.debug(
+                        f"Skipping deleted board {board.id} while searching for card {doc_id}"
+                    )
+                    continue
+
+                stacks = await nc_client.deck.get_stacks(board.id)
+
+                for stack in stacks:
+                    if card_found:
+                        break
+                    if stack.cards:
+                        for card in stack.cards:
+                            if card.id == int(doc_id):
+                                # Reconstruct full content as indexed: title + "\n\n" + description
+                                # This ensures chunk offsets align with indexed content structure
+                                content_parts = [card.title]
+                                if card.description:
+                                    content_parts.append(card.description)
+                                card_found = True
+                                logger.debug(
+                                    f"Found deck card {doc_id} in board {board.id}, stack {stack.id}"
+                                )
+                                return "\n\n".join(content_parts)
+
+            # Card not found (might be archived or deleted)
+            logger.warning(f"Deck card {doc_id} not found in any board/stack")
+            return None
         else:
             logger.warning(f"Unsupported doc_type for context expansion: {doc_type}")
             return None

nextcloud_mcp_server/search/semantic.py

@@ -151,6 +151,17 @@ class SemanticSearchAlgorithm(SearchAlgorithm):
 
             seen_chunks.add(chunk_key)
 
+            # Build metadata dict with common fields
+            metadata = {
+                "chunk_index": result.payload.get("chunk_index"),
+                "total_chunks": result.payload.get("total_chunks"),
+            }
+
+            # Add deck_card-specific metadata for frontend URL construction
+            if doc_type == "deck_card":
+                if board_id := result.payload.get("board_id"):
+                    metadata["board_id"] = board_id
+
             # Return unverified results (verification happens at output stage)
             results.append(
                 SearchResult(
@@ -159,10 +170,7 @@ class SemanticSearchAlgorithm(SearchAlgorithm):
                     title=result.payload.get("title", "Untitled"),
                     excerpt=result.payload.get("excerpt", ""),
                     score=result.score,
-                    metadata={
-                        "chunk_index": result.payload.get("chunk_index"),
-                        "total_chunks": result.payload.get("total_chunks"),
-                    },
+                    metadata=metadata,
                     chunk_start_offset=result.payload.get("chunk_start_offset"),
                     chunk_end_offset=result.payload.get("chunk_end_offset"),
                     page_number=result.payload.get("page_number"),