feat(api): unified FTS search

Single GET /api/search?q=&space_id=&kinds=&limit=&offset= unions FTS
hits across pages / refs / source_docs / messages with a `kind`
discriminator and ts_rank ordering. Each branch's to_tsvector matches
the GIN index expression on its source table so indexes are used.
Messages have no space_id and are excluded when a space filter is set.
Hybrid vector / RRF lands in Plan 3.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tests/api/search.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import request from 'supertest';
+import { setup } from './helpers.js';
+import * as spacesRepo from '../../lib/db/repos/spaces.js';
+import * as pagesRepo from '../../lib/db/repos/pages.js';
+import * as refsRepo from '../../lib/db/repos/refs.js';
+
+let app, ownerHeaders, space;
+const owner = { kind: 'user', id: null };
+
+beforeAll(async () => { ({ app, ownerHeaders } = await setup()); });
+beforeEach(async () => {
+  space = await spacesRepo.create(
+    { slug: `s-${Date.now()}-${Math.random().toString(36).slice(2,5)}`, name: 'S' }, owner
+  );
+  await pagesRepo.create(
+    { space_id: space.id, slug: 'pg', title: 'blackflame page', body_md: 'body about blackflame' }, owner
+  );
+  await refsRepo.create(
+    {
+      space_id: space.id, kind: 'url', source_url: 'https://x',
+      title: 'blackflame ref', body_text: 'a ref about blackflame'
+    },
+    owner
+  );
+});
+
+describe('search api', () => {
+  it('401 without auth', async () => {
+    const res = await request(app).get('/api/search?q=blackflame');
+    expect(res.status).toBe(401);
+  });
+
+  it('200 with hits across kinds', async () => {
+    const res = await request(app).get('/api/search?q=blackflame').set(ownerHeaders);
+    expect(res.status).toBe(200);
+    expect(res.body.length).toBeGreaterThanOrEqual(2);
+    const kinds = new Set(res.body.map(h => h.kind));
+    expect(kinds.has('page')).toBe(true);
+    expect(kinds.has('ref')).toBe(true);
+  });
+
+  it('kinds filter narrows', async () => {
+    const res = await request(app)
+      .get('/api/search?q=blackflame&kinds=page').set(ownerHeaders);
+    expect(res.status).toBe(200);
+    expect(res.body.every(h => h.kind === 'page')).toBe(true);
+  });
+
+  it('space_id filter scopes results', async () => {
+    const res = await request(app)
+      .get(`/api/search?q=blackflame&space_id=${space.id}`).set(ownerHeaders);
+    expect(res.status).toBe(200);
+    expect(res.body.every(h => h.space_id === space.id)).toBe(true);
+  });
+
+  it('missing q → 400', async () => {
+    const res = await request(app).get('/api/search').set(ownerHeaders);
+    expect(res.status).toBe(400);
+  });
+
+  it('limit respected', async () => {
+    const res = await request(app)
+      .get('/api/search?q=blackflame&limit=1').set(ownerHeaders);
+    expect(res.body.length).toBe(1);
+  });
+});