Implementation Plan: Workspace-Wide Vector Database with Kong AI Gateway¶

                    +------------------+
                    |    Architect      |
                    |  (VS Code User)  |
                    +--------+---------+
                             |
                    +--------v---------+
                    |    Roo Code /    |
                    |  Continue.dev /  |
                    |     Copilot      |
                    +--------+---------+
                             | MCP Protocol
                    +--------v---------+
                    | MCP Vector Server|
                    |  (Python, local) |
                    +---+----+----+----+
                        |    |    |
            +-----------+    |    +------------+
            |                |                 |
   +--------v-------+  +----v--------+  +-----v----------+
   |   ChromaDB     |  | Kong AI GW  |  |  File Watcher  |
   | (local vector  |  | (API proxy) |  |  (fswatch /    |
   |   database)    |  +----+--------+  |   watchdog)    |
   +----------------+       |           +----------------+
                        +---+---+
                        |       |
               +--------v+  +--v----------+
               | Embedding|  | LLM Inference|
               | Provider |  | Provider     |
               | (OpenAI/ |  | (Anthropic/  |
               |  Ollama) |  |  OpenAI)     |
               +----------+  +-------------+

File saved in workspace
  -> File watcher detects change
  -> Chunking pipeline splits file (format-aware)
  -> Chunks sent to Kong AI Gateway /embeddings endpoint
  -> Kong routes to embedding provider (OpenAI or Ollama)
  -> Kong logs: model, tokens, cost, latency
  -> Embedding vectors returned
  -> ChromaDB upserts vectors with metadata (file path, line range, content type)

AI agent calls MCP tool: search("which services call svc-guest-profiles?")
  -> MCP server embeds query via Kong AI Gateway /embeddings
  -> MCP server queries ChromaDB for top-k similar chunks
  -> MCP server returns ranked results with file paths + content snippets
  -> AI agent uses retrieved context in its reasoning
  -> AI agent's LLM call routes through Kong AI Gateway /chat/completions
  -> Kong logs: full request cost, latency, model, token counts

{
    "file_path": "architecture/specs/svc-check-in.yaml",
    "file_type": "openapi",
    "chunk_type": "endpoint",           # endpoint | schema | section | method | definition
    "section_heading": "POST /check-ins",
    "line_start": 45,
    "line_end": 98,
    "service": "svc-check-in",          # extracted from path or spec content
    "domain": "Operations",             # from DOMAINS mapping
    "last_modified": "2026-03-12T14:30:00Z"
}

# scripts/vector-db/chunker.py

import os
import yaml
import re
from dataclasses import dataclass
from typing import Generator
from pathlib import Path

@dataclass
class Chunk:
    content: str
    file_path: str
    file_type: str
    chunk_type: str
    section_heading: str
    line_start: int
    line_end: int
    metadata: dict

SKIP_DIRS = {'.git', 'node_modules', '.venv', 'site', '__pycache__', '.mypy_cache'}
SKIP_FILES = {'.DS_Store', '.gitignore', '.env'}

def chunk_markdown(file_path: str, content: str) -> Generator[Chunk, None, None]:
    """Split Markdown by H2 headers."""
    lines = content.split('\n')
    current_section = []
    current_heading = "Preamble"
    section_start = 1

    for i, line in enumerate(lines, 1):
        if line.startswith('## ') and current_section:
            yield Chunk(
                content='\n'.join(current_section),
                file_path=file_path,
                file_type='markdown',
                chunk_type='section',
                section_heading=current_heading,
                line_start=section_start,
                line_end=i - 1,
                metadata={}
            )
            current_section = [line]
            current_heading = line.lstrip('# ').strip()
            section_start = i
        else:
            current_section.append(line)

    if current_section:
        yield Chunk(
            content='\n'.join(current_section),
            file_path=file_path,
            file_type='markdown',
            chunk_type='section',
            section_heading=current_heading,
            line_start=section_start,
            line_end=len(lines),
            metadata={}
        )

def chunk_openapi(file_path: str, content: str) -> Generator[Chunk, None, None]:
    """Split OpenAPI YAML by path+operation."""
    try:
        spec = yaml.safe_load(content)
    except yaml.YAMLError:
        yield Chunk(
            content=content,
            file_path=file_path,
            file_type='openapi',
            chunk_type='full_file',
            section_heading=os.path.basename(file_path),
            line_start=1,
            line_end=content.count('\n') + 1,
            metadata={}
        )
        return

    # Info block
    if 'info' in spec:
        info_yaml = yaml.dump({'info': spec['info']}, default_flow_style=False)
        yield Chunk(
            content=info_yaml,
            file_path=file_path,
            file_type='openapi',
            chunk_type='info',
            section_heading=spec.get('info', {}).get('title', 'API Info'),
            line_start=1,
            line_end=1,
            metadata={'service': _extract_service(file_path)}
        )

    # Each path+operation
    for path, methods in (spec.get('paths') or {}).items():
        for method, operation in methods.items():
            if method.startswith('x-'):
                continue
            op_yaml = yaml.dump(
                {path: {method: operation}},
                default_flow_style=False
            )
            summary = operation.get('summary', f'{method.upper()} {path}')
            yield Chunk(
                content=op_yaml,
                file_path=file_path,
                file_type='openapi',
                chunk_type='endpoint',
                section_heading=f'{method.upper()} {path} -- {summary}',
                line_start=1,
                line_end=1,
                metadata={'service': _extract_service(file_path)}
            )

    # Schemas
    schemas = (spec.get('components') or {}).get('schemas') or {}
    for name, schema in schemas.items():
        schema_yaml = yaml.dump({name: schema}, default_flow_style=False)
        yield Chunk(
            content=schema_yaml,
            file_path=file_path,
            file_type='openapi',
            chunk_type='schema',
            section_heading=f'Schema: {name}',
            line_start=1,
            line_end=1,
            metadata={'service': _extract_service(file_path)}
        )

def chunk_java(file_path: str, content: str) -> Generator[Chunk, None, None]:
    """Split Java by method boundaries."""
    # Simplified: split on method-level patterns
    lines = content.split('\n')
    method_pattern = re.compile(
        r'^\s+(public|private|protected)\s+\S+\s+\w+\s*\('
    )
    current_block = []
    block_start = 1
    current_heading = os.path.basename(file_path)

    for i, line in enumerate(lines, 1):
        if method_pattern.match(line) and current_block:
            yield Chunk(
                content='\n'.join(current_block),
                file_path=file_path,
                file_type='java',
                chunk_type='method',
                section_heading=current_heading,
                line_start=block_start,
                line_end=i - 1,
                metadata={}
            )
            current_block = [line]
            current_heading = line.strip()
            block_start = i
        else:
            current_block.append(line)

    if current_block:
        yield Chunk(
            content='\n'.join(current_block),
            file_path=file_path,
            file_type='java',
            chunk_type='method',
            section_heading=current_heading,
            line_start=block_start,
            line_end=len(lines),
            metadata={}
        )

def _extract_service(file_path: str) -> str:
    """Extract service name from file path."""
    parts = Path(file_path).parts
    for part in parts:
        if part.startswith('svc-'):
            return part
    stem = Path(file_path).stem
    if stem.startswith('svc-'):
        return stem
    return ''

def chunk_workspace(workspace_root: str) -> Generator[Chunk, None, None]:
    """Walk workspace and yield all chunks."""
    for dirpath, dirnames, filenames in os.walk(workspace_root):
        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]

        for filename in filenames:
            if filename in SKIP_FILES:
                continue

            file_path = os.path.join(dirpath, filename)
            rel_path = os.path.relpath(file_path, workspace_root)

            try:
                with open(file_path, 'r', encoding='utf-8', errors='ignore') as f:
                    content = f.read()
            except (PermissionError, IsADirectoryError):
                continue

            if not content.strip():
                continue

            ext = Path(filename).suffix.lower()

            if ext == '.md':
                yield from chunk_markdown(rel_path, content)
            elif ext in ('.yaml', '.yml'):
                # Detect OpenAPI vs plain YAML
                if 'openapi:' in content[:500]:
                    yield from chunk_openapi(rel_path, content)
                else:
                    # Plain YAML: single chunk
                    yield Chunk(
                        content=content,
                        file_path=rel_path,
                        file_type='yaml',
                        chunk_type='full_file',
                        section_heading=filename,
                        line_start=1,
                        line_end=content.count('\n') + 1,
                        metadata={}
                    )
            elif ext == '.java':
                yield from chunk_java(rel_path, content)
            elif ext in ('.puml', '.plantuml'):
                yield Chunk(
                    content=content,
                    file_path=rel_path,
                    file_type='plantuml',
                    chunk_type='full_file',
                    section_heading=filename,
                    line_start=1,
                    line_end=content.count('\n') + 1,
                    metadata={}
                )

# scripts/vector-db/store.py

import chromadb
import hashlib
from pathlib import Path

DB_PATH = ".vector-db"
COLLECTION_NAME = "novatrek-workspace"

def get_collection():
    client = chromadb.PersistentClient(path=DB_PATH)
    return client.get_or_create_collection(
        name=COLLECTION_NAME,
        metadata={"hnsw:space": "cosine"}
    )

def chunk_id(file_path: str, line_start: int, section_heading: str) -> str:
    """Deterministic ID for upsert idempotency."""
    raw = f"{file_path}:{line_start}:{section_heading}"
    return hashlib.sha256(raw.encode()).hexdigest()[:16]

def upsert_chunks(chunks, embeddings):
    """Upsert chunk embeddings into ChromaDB."""
    collection = get_collection()
    ids = []
    documents = []
    metadatas = []

    for chunk in chunks:
        ids.append(chunk_id(chunk.file_path, chunk.line_start, chunk.section_heading))
        documents.append(chunk.content)
        metadatas.append({
            "file_path": chunk.file_path,
            "file_type": chunk.file_type,
            "chunk_type": chunk.chunk_type,
            "section_heading": chunk.section_heading,
            "line_start": chunk.line_start,
            "line_end": chunk.line_end,
            **chunk.metadata
        })

    # ChromaDB handles batching internally
    collection.upsert(
        ids=ids,
        embeddings=embeddings,
        documents=documents,
        metadatas=metadatas
    )

def query(embedding, top_k=5, where_filter=None):
    """Query ChromaDB for similar chunks."""
    collection = get_collection()
    kwargs = {
        "query_embeddings": [embedding],
        "n_results": top_k,
        "include": ["documents", "metadatas", "distances"]
    }
    if where_filter:
        kwargs["where"] = where_filter

    return collection.query(**kwargs)

def delete_by_file(file_path: str):
    """Remove all chunks for a file (before re-indexing)."""
    collection = get_collection()
    collection.delete(where={"file_path": file_path})

def get_stats():
    """Return collection statistics."""
    collection = get_collection()
    return {
        "total_chunks": collection.count(),
        "collection": COLLECTION_NAME
    }

  # ---------------------------------------------------------------------------
  # Kong AI Gateway (manages embedding + LLM API traffic)
  # ---------------------------------------------------------------------------
  kong:
    image: kong/kong-gateway:3.9
    container_name: novatrek-kong-ai
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml
      KONG_PROXY_LISTEN: "0.0.0.0:8000"
      KONG_ADMIN_LISTEN: "0.0.0.0:8001"
      KONG_LOG_LEVEL: info
    ports:
      - "8000:8000"   # Proxy (AI API calls go here)
      - "8001:8001"   # Admin API
    volumes:
      - ./config/kong/kong.yml:/etc/kong/kong.yml:ro
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s
      timeout: 5s
      retries: 5

_format_version: "3.0"

services:
  # ===== Embedding Provider: OpenAI =====
  - name: openai-embeddings
    url: https://api.openai.com/v1
    routes:
      - name: embeddings-route
        paths:
          - /ai/embeddings
        strip_path: true
    plugins:
      - name: ai-proxy
        config:
          route_type: llm/v1/embeddings
          auth:
            header_name: Authorization
            header_value: "Bearer ${OPENAI_API_KEY}"
          model:
            provider: openai
            name: text-embedding-3-small
      - name: rate-limiting
        config:
          minute: 500
          policy: local
      - name: ai-prompt-decorator
        config:
          prepend:
            - role: system
              content: >
                You are indexing an architecture workspace for the NovaTrek
                Adventures platform. Embeddings are used for semantic search
                over OpenAPI specs, ADRs, solution designs, and service metadata.

  # ===== Embedding Provider: Ollama (local fallback) =====
  - name: ollama-embeddings
    url: http://host.docker.internal:11434/v1
    routes:
      - name: embeddings-local-route
        paths:
          - /ai/embeddings/local
        strip_path: true
    plugins:
      - name: rate-limiting
        config:
          minute: 1000
          policy: local

  # ===== LLM Inference: Anthropic (for Roo Code RAG-augmented calls) =====
  - name: anthropic-chat
    url: https://api.anthropic.com/v1
    routes:
      - name: chat-route
        paths:
          - /ai/chat
        strip_path: true
    plugins:
      - name: ai-proxy
        config:
          route_type: llm/v1/chat
          auth:
            header_name: x-api-key
            header_value: "${ANTHROPIC_API_KEY}"
          model:
            provider: anthropic
            name: claude-sonnet-4-20250514
      - name: rate-limiting
        config:
          minute: 100
          policy: local
      - name: ai-prompt-decorator
        config:
          prepend:
            - role: system
              content: >
                You have access to a workspace vector search tool via MCP.
                When investigating architecture questions, query the vector
                database before reading files directly. The workspace contains
                19 microservice OpenAPI specs, 11 ADRs, event schemas, and
                solution designs for the NovaTrek Adventures platform.

  # ===== LLM Inference: OpenAI (fallback) =====
  - name: openai-chat
    url: https://api.openai.com/v1
    routes:
      - name: chat-fallback-route
        paths:
          - /ai/chat/openai
        strip_path: true
    plugins:
      - name: ai-proxy
        config:
          route_type: llm/v1/chat
          auth:
            header_name: Authorization
            header_value: "Bearer ${OPENAI_API_KEY}"
          model:
            provider: openai
            name: gpt-4.1
      - name: rate-limiting
        config:
          minute: 100
          policy: local

{
  "request.model": "text-embedding-3-small",
  "request.provider": "openai",
  "response.tokens.input": 1523,
  "response.tokens.output": 0,
  "response.latency_ms": 142,
  "response.cost_usd": 0.0000305,
  "consumer": "vector-indexer",
  "route": "embeddings-route",
  "timestamp": "2026-03-14T15:30:42Z"
}

# scripts/vector-db/embedder.py

import os
import requests
from typing import Optional

KONG_BASE_URL = os.environ.get("KONG_AI_URL", "http://localhost:8000")

def embed_texts(texts: list[str], provider: str = "openai") -> list[list[float]]:
    """Generate embeddings via Kong AI Gateway."""
    if provider == "local":
        url = f"{KONG_BASE_URL}/ai/embeddings/local"
        payload = {
            "model": "nomic-embed-text",
            "input": texts
        }
    else:
        url = f"{KONG_BASE_URL}/ai/embeddings"
        payload = {
            "model": "text-embedding-3-small",
            "input": texts
        }

    response = requests.post(url, json=payload, timeout=30)
    response.raise_for_status()

    data = response.json()
    return [item["embedding"] for item in data["data"]]

def embed_query(query: str, provider: str = "openai") -> list[float]:
    """Embed a single query string."""
    return embed_texts([query], provider=provider)[0]

{
  "name": "workspace_search",
  "description": "Semantic search across the entire NovaTrek architecture workspace. Searches OpenAPI specs, ADRs, solution designs, event schemas, capability metadata, and Java source code. Returns the top-k most relevant chunks with file paths and line numbers. Use this BEFORE reading files to find relevant context efficiently.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
      },
      "top_k": {
        "type": "integer",
        "default": 5,
        "description": "Number of results to return (1-20)"
      },
      "file_type": {
        "type": "string",
        "enum": ["markdown", "openapi", "yaml", "java", "plantuml"],
        "description": "Optional filter to restrict search to a specific file type"
      },
      "service": {
        "type": "string",
        "description": "Optional filter to restrict search to a specific service (e.g., 'svc-check-in')"
      }
    },
    "required": ["query"]
  }
}

# scripts/vector-db/mcp_server.py

import asyncio
import json
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

from store import query as vector_query, get_stats
from embedder import embed_query

app = Server("novatrek-workspace-search")

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="workspace_search",
            description=(
                "Semantic search across the entire NovaTrek architecture workspace. "
                "Searches OpenAPI specs, ADRs, solution designs, event schemas, "
                "capability metadata, and Java source code. Returns the top-k most "
                "relevant chunks with file paths and line numbers. "
                "Use this BEFORE reading files to find relevant context efficiently."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Natural language search query"
                    },
                    "top_k": {
                        "type": "integer",
                        "default": 5,
                        "description": "Number of results to return (1-20)"
                    },
                    "file_type": {
                        "type": "string",
                        "enum": ["markdown", "openapi", "yaml", "java", "plantuml"],
                        "description": "Optional: restrict to file type"
                    },
                    "service": {
                        "type": "string",
                        "description": "Optional: restrict to service (e.g., svc-check-in)"
                    }
                },
                "required": ["query"]
            }
        ),
        Tool(
            name="workspace_index_stats",
            description="Get statistics about the workspace vector index",
            inputSchema={
                "type": "object",
                "properties": {}
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "workspace_search":
        query_text = arguments["query"]
        top_k = min(arguments.get("top_k", 5), 20)

        # Build metadata filter
        where_filter = {}
        if "file_type" in arguments:
            where_filter["file_type"] = arguments["file_type"]
        if "service" in arguments:
            where_filter["service"] = arguments["service"]

        # Embed query via Kong AI Gateway
        query_embedding = embed_query(query_text)

        # Search ChromaDB
        results = vector_query(
            embedding=query_embedding,
            top_k=top_k,
            where_filter=where_filter if where_filter else None
        )

        # Format results
        output_lines = [f"## Search Results for: \"{query_text}\"\n"]
        for i, (doc, meta, dist) in enumerate(zip(
            results["documents"][0],
            results["metadatas"][0],
            results["distances"][0]
        )):
            score = 1 - dist  # cosine distance to similarity
            output_lines.append(
                f"### Result {i+1} (similarity: {score:.3f})\n"
                f"**File:** {meta['file_path']} "
                f"(lines {meta['line_start']}-{meta['line_end']})\n"
                f"**Type:** {meta['file_type']} / {meta['chunk_type']}\n"
                f"**Section:** {meta['section_heading']}\n\n"
                f"```\n{doc[:500]}{'...' if len(doc) > 500 else ''}\n```\n"
            )

        return [TextContent(type="text", text='\n'.join(output_lines))]

    elif name == "workspace_index_stats":
        stats = get_stats()
        return [TextContent(
            type="text",
            text=json.dumps(stats, indent=2)
        )]

    return [TextContent(type="text", text=f"Unknown tool: {name}")]

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream)

if __name__ == "__main__":
    asyncio.run(main())

# scripts/vector-db/watcher.py

import time
from watchdog.observers import Observer
from watchdog.events import FileSystemEventHandler
from pathlib import Path

from chunker import chunk_markdown, chunk_openapi, chunk_java, SKIP_DIRS
from embedder import embed_texts
from store import upsert_chunks, delete_by_file

WATCH_EXTENSIONS = {'.md', '.yaml', '.yml', '.java', '.puml'}

class WorkspaceHandler(FileSystemEventHandler):
    def __init__(self, workspace_root: str):
        self.workspace_root = workspace_root

    def on_modified(self, event):
        if event.is_directory:
            return
        self._reindex(event.src_path)

    def on_created(self, event):
        if event.is_directory:
            return
        self._reindex(event.src_path)

    def on_deleted(self, event):
        if event.is_directory:
            return
        rel_path = str(Path(event.src_path).relative_to(self.workspace_root))
        delete_by_file(rel_path)

    def _reindex(self, abs_path: str):
        path = Path(abs_path)
        if path.suffix not in WATCH_EXTENSIONS:
            return
        if any(skip in path.parts for skip in SKIP_DIRS):
            return

        rel_path = str(path.relative_to(self.workspace_root))

        try:
            content = path.read_text(encoding='utf-8', errors='ignore')
        except (PermissionError, FileNotFoundError):
            return

        if not content.strip():
            return

        # Delete old chunks for this file
        delete_by_file(rel_path)

        # Re-chunk
        if path.suffix == '.md':
            chunks = list(chunk_markdown(rel_path, content))
        elif path.suffix in ('.yaml', '.yml') and 'openapi:' in content[:500]:
            chunks = list(chunk_openapi(rel_path, content))
        elif path.suffix == '.java':
            chunks = list(chunk_java(rel_path, content))
        else:
            return

        if not chunks:
            return

        # Embed via Kong AI
        texts = [c.content for c in chunks]
        embeddings = embed_texts(texts)

        # Upsert
        upsert_chunks(chunks, embeddings)
        print(f"Re-indexed {rel_path}: {len(chunks)} chunks")

def watch(workspace_root: str):
    handler = WorkspaceHandler(workspace_root)
    observer = Observer()
    observer.schedule(handler, workspace_root, recursive=True)
    observer.start()
    print(f"Watching {workspace_root} for changes...")
    try:
        while True:
            time.sleep(1)
    except KeyboardInterrupt:
        observer.stop()
    observer.join()

# scripts/vector-db/index.py

import sys
import time
from chunker import chunk_workspace
from embedder import embed_texts
from store import upsert_chunks, get_stats

BATCH_SIZE = 50  # Chunks per embedding API call

def index_workspace(workspace_root: str):
    print(f"Indexing workspace: {workspace_root}")
    start = time.time()

    all_chunks = list(chunk_workspace(workspace_root))
    print(f"Chunked {len(all_chunks)} chunks from workspace")

    # Batch embed
    for i in range(0, len(all_chunks), BATCH_SIZE):
        batch = all_chunks[i:i + BATCH_SIZE]
        texts = [c.content for c in batch]
        embeddings = embed_texts(texts)
        upsert_chunks(batch, embeddings)
        print(f"  Indexed batch {i//BATCH_SIZE + 1}/{(len(all_chunks) + BATCH_SIZE - 1)//BATCH_SIZE}")

    elapsed = time.time() - start
    stats = get_stats()
    print(f"Done. {stats['total_chunks']} chunks indexed in {elapsed:.1f}s")

if __name__ == "__main__":
    root = sys.argv[1] if len(sys.argv) > 1 else "."
    index_workspace(root)

{
  "mcpServers": {
    "novatrek-workspace": {
      "command": "python3",
      "args": ["scripts/vector-db/mcp_server.py"],
      "env": {
        "KONG_AI_URL": "http://localhost:8000"
      }
    }
  }
}

scripts/vector-db/
├── README.md                 # Setup and usage instructions
├── requirements.txt          # Python dependencies
├── chunker.py                # Format-aware document chunking
├── store.py                  # ChromaDB vector storage (supports Qdrant backend)
├── embedder.py               # Embedding client (via Kong AI Gateway)
├── mcp_server.py             # MCP server for Roo Code integration
├── watcher.py                # File watcher for incremental re-indexing
├── reindex-file.py           # Single-file re-indexer (called by VS Code extension)
├── index.py                  # Full workspace indexer
└── test_chunker.py           # Unit tests for chunking logic

config/kong/
└── kong.yml                  # Kong AI Gateway declarative configuration

.vscode/
└── tasks.json                # Auto-start watcher on workspace open

.githooks/
├── post-merge                # Auto-reindex after git pull
└── post-checkout             # Auto-reindex after branch switch

.vector-db/                   # ChromaDB persistent storage (gitignored)

chromadb>=0.5,<1.0
mcp>=1.0,<2.0
watchdog>=4.0,<5.0
requests>=2.31,<3.0
pyyaml>=6.0,<7.0

export OPENAI_API_KEY=sk-...          # For text-embedding-3-small
export ANTHROPIC_API_KEY=sk-ant-...    # For Claude (if routing LLM calls through Kong)

# ===========================================================================
# Vector Database (Workspace Search)
# ===========================================================================

vector-index: ## Full re-index of workspace into vector DB
    python3 scripts/vector-db/index.py .

vector-watch: ## Watch workspace and re-index on file changes
    python3 scripts/vector-db/watcher.py

vector-stats: ## Show vector DB statistics
    python3 -c "from scripts.vector_db.store import get_stats; import json; print(json.dumps(get_stats(), indent=2))"

vector-search: ## Search vector DB: make vector-search Q="your query"
    python3 -c "from scripts.vector_db.embedder import embed_query; from scripts.vector_db.store import query; import json; r=query(embed_query('$(Q)')); [print(f'{m[\"file_path\"]}:{m[\"line_start\"]} ({m[\"section_heading\"]})') for m in r['metadatas'][0]]"

kong-up: ## Start Kong AI Gateway
    docker compose up kong -d

kong-logs: ## Tail Kong AI Gateway logs
    docker compose logs kong -f

kong-routes: ## List Kong AI routes
    curl -s http://localhost:8001/routes | python3 -m json.tool

Architect opens VS Code
  -> Roo Code auto-starts MCP server (from .roo/mcp.json config)
  -> MCP server connects to local ChromaDB

First time (or after git pull with many changes):
  -> Run: make vector-index          # ~60 seconds, full re-index

Ongoing:
  -> Run: make vector-watch          # background, re-indexes on save
  -> (Or: VS Code task that auto-starts watcher on workspace open)

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Vector DB: Watch for Changes",
      "type": "shell",
      "command": "python3",
      "args": ["scripts/vector-db/watcher.py"],
      "isBackground": true,
      "problemMatcher": [],
      "runOptions": {
        "runOn": "folderOpen"
      },
      "presentation": {
        "reveal": "silent",
        "panel": "dedicated"
      }
    },
    {
      "label": "Vector DB: Full Re-index",
      "type": "shell",
      "command": "python3",
      "args": ["scripts/vector-db/index.py", "."],
      "problemMatcher": [],
      "presentation": {
        "reveal": "always"
      }
    }
  ]
}

#!/bin/sh
# .githooks/post-merge
# Auto-reindex vector DB after git pull

if [ -d "scripts/vector-db" ] && command -v python3 >/dev/null 2>&1; then
    echo "Re-indexing workspace vector DB..."
    python3 scripts/vector-db/index.py . &
fi

#!/bin/sh
# .githooks/post-checkout
# Auto-reindex vector DB after branch switch

# Only run for branch checkouts (flag=1), not file checkouts (flag=0)
if [ "$3" = "1" ] && [ -d "scripts/vector-db" ] && command -v python3 >/dev/null 2>&1; then
    echo "Re-indexing workspace vector DB..."
    python3 scripts/vector-db/index.py . &
fi

git config core.hooksPath .githooks

# Addition to docker-compose.yml (or team-hosted VM)
  qdrant:
    image: qdrant/qdrant:v1.12
    container_name: novatrek-qdrant
    ports:
      - "6333:6333"   # REST API
      - "6334:6334"   # gRPC
    volumes:
      - qdrant-data:/qdrant/storage
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6333/healthz"]
      interval: 10s
      timeout: 5s
      retries: 5

# .github/workflows/vector-index.yml
name: Reindex Vector DB
on:
  push:
    branches: [main]
    paths:
      - 'architecture/**'
      - 'decisions/**'
      - 'portal/docs/**'
      - 'config/**'
      - 'services/**'

jobs:
  reindex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: pip install -r scripts/vector-db/requirements.txt
      - run: python3 scripts/vector-db/index.py .
        env:
          QDRANT_URL: ${{ vars.QDRANT_URL }}
          KONG_AI_URL: ${{ vars.KONG_AI_URL }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

BACKEND = os.environ.get("VECTOR_BACKEND", "chromadb")  # chromadb | qdrant

if BACKEND == "qdrant":
    from qdrant_client import QdrantClient
    client = QdrantClient(url=os.environ.get("QDRANT_URL", "http://localhost:6333"))
else:
    import chromadb
    client = chromadb.PersistentClient(path=".vector-db")

VS Code Extension (TypeScript, ~200 lines)
  |-- onStartupFinished -> spawn `python3 scripts/vector-db/index.py`
  |-- onDidSaveTextDocument -> spawn `python3 scripts/vector-db/reindex-file.py <path>`
  |-- Status bar item -> reads `.vector-db/stats.json`
  |-- Command: "Reindex Workspace" -> spawns full `index.py`
  +-- Extension settings -> Kong URL, embedding provider, top-k

Python scripts (unchanged from this plan)
  |-- chunker.py, store.py, embedder.py -> actual work
  |-- mcp_server.py -> Roo Code integration
  +-- index.py, watcher.py -> invoked by extension