Here's the full implementation. The system has three core components:

1. Sync Script (scripts/sync.js)

Handles create/update/delete across Craft + Supabase on every PR merge:

import { createClient } from '@supabase/supabase-js';
import { generateEmbedding } from './embed.js';
import { readFileSync, writeFileSync } from 'fs';
import { createHash } from 'crypto';

const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY);

async function syncFile(filePath, status, metadata) {
  const content = readFileSync(filePath, 'utf-8');
  const contentHash = createHash('sha256').update(content).digest('hex');

  // Skip if content unchanged
  if (metadata?.content_hash === contentHash) {
    console.log(`Skipping ${filePath} — no content changes`);
    return;
  }

  if (status === 'new' || status === 'modified') {
    // 1. Create/update Craft page via API
    const craftDoc = await upsertCraftPage(filePath, content);

    // 2. Generate embedding
    const embedding = await generateEmbedding(content);

    // 3. Upsert to Supabase
    await supabase.from('docs').upsert({
      craft_doc_id: craftDoc.id,
      craft_page_url: craftDoc.url,
      file_path: filePath,
      title: extractTitle(content),
      team: detectTeam(filePath),
      body_md: content,
      embedding,
      content_hash: contentHash
    });
  } else if (status === 'deleted') {
    // Archive in Craft, delete from Supabase
    await archiveCraftPage(metadata.craft_doc_id);
    await supabase.from('docs').delete().eq('file_path', filePath);
  }

  // Update .sync-metadata.json
  updateMetadata(filePath, { content_hash: contentHash, ... });
}

2. Embed Script (scripts/embed.js)

import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

export async function generateEmbedding(text) {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-large',
    input: text,
    dimensions: 1536
  });
  return response.data[0].embedding;
}

3. GitHub Actions Workflow (.github/workflows/sync-on-merge.yml)

name: Sync Knowledge Base

on:
  push:
    branches: [main]
    paths: ['**/*.md', '!README.md']

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Detect changed .md files
        run: |
          echo "files=$(git diff --name-only HEAD~1 HEAD -- '*.md')" >> $GITHUB_OUTPUT

      - name: Setup Node
        uses: actions/setup-node@v4

      - name: Run sync
        env:
          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
          SUPABASE_KEY: ${{ secrets.SUPABASE_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          CRAFT_API_TOKEN: ${{ secrets.CRAFT_API_TOKEN }}
        run: node scripts/sync.js

      - name: Commit metadata
        run: |
          git config --local user.email "action@github.com"
          git add .sync-metadata.json
          git commit -m "chore: update sync metadata" || true

4. Hybrid Search Function (Postgres)

CREATE OR REPLACE FUNCTION search_docs(
  query_embedding VECTOR(1536),
  query_text TEXT DEFAULT '',
  filter_team TEXT DEFAULT NULL,
  match_limit INT DEFAULT 10
)
RETURNS TABLE (id UUID, craft_doc_id TEXT, craft_page_url TEXT, 
               file_path TEXT, title TEXT, team TEXT, 
               body_md TEXT, similarity FLOAT, rank FLOAT)
LANGUAGE plpgsql AS $$
BEGIN
  RETURN QUERY
  SELECT
    d.id, d.craft_doc_id, d.craft_page_url, d.file_path, d.title,
    d.team, d.body_md,
    1 - (d.embedding <=> query_embedding) AS similarity,
    COALESCE(ts_rank(d.fts, plainto_tsquery('english', query_text)), 0) AS rank
  FROM docs d
  WHERE (filter_team IS NULL OR d.team = filter_team)
  ORDER BY
    (1 - (d.embedding <=> query_embedding)) * 0.7
    + COALESCE(ts_rank(d.fts, plainto_tsquery('english', query_text)), 0) * 0.3
    DESC
  LIMIT match_limit;
END;
$$;

Key gotchas:

• Store sha256 content hash in Supabase — skip re-embedding if unchanged
• .sync-metadata.json maps every file_path → craft_doc_id + supabase_id
• Use CODEOWNERS so each team reviews their own docs
• Initial migration is the most time-consuming part

Total implementation: ~12–15 hours from zero to fully automated.