pilothub 0.0.1

package/src/lib/gravatar.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest'
+import { gravatarUrl } from './gravatar'
+
+describe('gravatarUrl', () => {
+  it('generates a stable hash', () => {
+    const url = gravatarUrl('MyEmailAddress@example.com ')
+    expect(url).toContain('0bc83cb571cd1c50ba6f3e8a78ef1346')
+  })
+})

package/src/lib/gravatar.ts

@@ -0,0 +1,158 @@
+function md5cycle(x: number[], k: number[]) {
+  let [a, b, c, d] = x
+
+  a = ff(a, b, c, d, k[0], 7, -680876936)
+  d = ff(d, a, b, c, k[1], 12, -389564586)
+  c = ff(c, d, a, b, k[2], 17, 606105819)
+  b = ff(b, c, d, a, k[3], 22, -1044525330)
+  a = ff(a, b, c, d, k[4], 7, -176418897)
+  d = ff(d, a, b, c, k[5], 12, 1200080426)
+  c = ff(c, d, a, b, k[6], 17, -1473231341)
+  b = ff(b, c, d, a, k[7], 22, -45705983)
+  a = ff(a, b, c, d, k[8], 7, 1770035416)
+  d = ff(d, a, b, c, k[9], 12, -1958414417)
+  c = ff(c, d, a, b, k[10], 17, -42063)
+  b = ff(b, c, d, a, k[11], 22, -1990404162)
+  a = ff(a, b, c, d, k[12], 7, 1804603682)
+  d = ff(d, a, b, c, k[13], 12, -40341101)
+  c = ff(c, d, a, b, k[14], 17, -1502002290)
+  b = ff(b, c, d, a, k[15], 22, 1236535329)
+
+  a = gg(a, b, c, d, k[1], 5, -165796510)
+  d = gg(d, a, b, c, k[6], 9, -1069501632)
+  c = gg(c, d, a, b, k[11], 14, 643717713)
+  b = gg(b, c, d, a, k[0], 20, -373897302)
+  a = gg(a, b, c, d, k[5], 5, -701558691)
+  d = gg(d, a, b, c, k[10], 9, 38016083)
+  c = gg(c, d, a, b, k[15], 14, -660478335)
+  b = gg(b, c, d, a, k[4], 20, -405537848)
+  a = gg(a, b, c, d, k[9], 5, 568446438)
+  d = gg(d, a, b, c, k[14], 9, -1019803690)
+  c = gg(c, d, a, b, k[3], 14, -187363961)
+  b = gg(b, c, d, a, k[8], 20, 1163531501)
+  a = gg(a, b, c, d, k[13], 5, -1444681467)
+  d = gg(d, a, b, c, k[2], 9, -51403784)
+  c = gg(c, d, a, b, k[7], 14, 1735328473)
+  b = gg(b, c, d, a, k[12], 20, -1926607734)
+
+  a = hh(a, b, c, d, k[5], 4, -378558)
+  d = hh(d, a, b, c, k[8], 11, -2022574463)
+  c = hh(c, d, a, b, k[11], 16, 1839030562)
+  b = hh(b, c, d, a, k[14], 23, -35309556)
+  a = hh(a, b, c, d, k[1], 4, -1530992060)
+  d = hh(d, a, b, c, k[4], 11, 1272893353)
+  c = hh(c, d, a, b, k[7], 16, -155497632)
+  b = hh(b, c, d, a, k[10], 23, -1094730640)
+  a = hh(a, b, c, d, k[13], 4, 681279174)
+  d = hh(d, a, b, c, k[0], 11, -358537222)
+  c = hh(c, d, a, b, k[3], 16, -722521979)
+  b = hh(b, c, d, a, k[6], 23, 76029189)
+  a = hh(a, b, c, d, k[9], 4, -640364487)
+  d = hh(d, a, b, c, k[12], 11, -421815835)
+  c = hh(c, d, a, b, k[15], 16, 530742520)
+  b = hh(b, c, d, a, k[2], 23, -995338651)
+
+  a = ii(a, b, c, d, k[0], 6, -198630844)
+  d = ii(d, a, b, c, k[7], 10, 1126891415)
+  c = ii(c, d, a, b, k[14], 15, -1416354905)
+  b = ii(b, c, d, a, k[5], 21, -57434055)
+  a = ii(a, b, c, d, k[12], 6, 1700485571)
+  d = ii(d, a, b, c, k[3], 10, -1894986606)
+  c = ii(c, d, a, b, k[10], 15, -1051523)
+  b = ii(b, c, d, a, k[1], 21, -2054922799)
+  a = ii(a, b, c, d, k[8], 6, 1873313359)
+  d = ii(d, a, b, c, k[15], 10, -30611744)
+  c = ii(c, d, a, b, k[6], 15, -1560198380)
+  b = ii(b, c, d, a, k[13], 21, 1309151649)
+  a = ii(a, b, c, d, k[4], 6, -145523070)
+  d = ii(d, a, b, c, k[11], 10, -1120210379)
+  c = ii(c, d, a, b, k[2], 15, 718787259)
+  b = ii(b, c, d, a, k[9], 21, -343485551)
+
+  x[0] = add32(a, x[0])
+  x[1] = add32(b, x[1])
+  x[2] = add32(c, x[2])
+  x[3] = add32(d, x[3])
+}
+
+function cmn(q: number, a: number, b: number, x: number, s: number, t: number) {
+  a = add32(add32(a, q), add32(x, t))
+  return add32((a << s) | (a >>> (32 - s)), b)
+}
+
+function ff(a: number, b: number, c: number, d: number, x: number, s: number, t: number) {
+  return cmn((b & c) | (~b & d), a, b, x, s, t)
+}
+
+function gg(a: number, b: number, c: number, d: number, x: number, s: number, t: number) {
+  return cmn((b & d) | (c & ~d), a, b, x, s, t)
+}
+
+function hh(a: number, b: number, c: number, d: number, x: number, s: number, t: number) {
+  return cmn(b ^ c ^ d, a, b, x, s, t)
+}
+
+function ii(a: number, b: number, c: number, d: number, x: number, s: number, t: number) {
+  return cmn(c ^ (b | ~d), a, b, x, s, t)
+}
+
+function md51(s: string) {
+  const n = s.length
+  const state = [1732584193, -271733879, -1732584194, 271733878]
+  let i = 0
+  for (i = 64; i <= n; i += 64) {
+    md5cycle(state, md5blk(s.substring(i - 64, i)))
+  }
+  s = s.substring(i - 64)
+  const tail = Array(16).fill(0) as number[]
+  for (i = 0; i < s.length; i += 1) {
+    tail[i >> 2] |= s.charCodeAt(i) << ((i % 4) << 3)
+  }
+  tail[i >> 2] |= 0x80 << ((i % 4) << 3)
+  if (i > 55) {
+    md5cycle(state, tail)
+    for (let j = 0; j < 16; j += 1) tail[j] = 0
+  }
+  tail[14] = n * 8
+  md5cycle(state, tail)
+  return state
+}
+
+function md5blk(s: string) {
+  const md5blks: number[] = []
+  for (let i = 0; i < 64; i += 4) {
+    md5blks[i >> 2] =
+      s.charCodeAt(i) +
+      (s.charCodeAt(i + 1) << 8) +
+      (s.charCodeAt(i + 2) << 16) +
+      (s.charCodeAt(i + 3) << 24)
+  }
+  return md5blks
+}
+
+function rhex(n: number) {
+  const s = '0123456789abcdef'
+  let j = 0
+  let out = ''
+  for (; j < 4; j += 1) {
+    out += s.charAt((n >> (j * 8 + 4)) & 0x0f) + s.charAt((n >> (j * 8)) & 0x0f)
+  }
+  return out
+}
+
+function hex(x: number[]) {
+  for (let i = 0; i < x.length; i += 1) {
+    x[i] = Number(x[i])
+  }
+  return x.map(rhex).join('')
+}
+
+function add32(a: number, b: number) {
+  return (a + b) & 0xffffffff
+}
+
+export function gravatarUrl(email: string, size = 160) {
+  const normalized = email.trim().toLowerCase()
+  const hash = hex(md51(normalized))
+  return `https://www.gravatar.com/avatar/${hash}?d=identicon&s=${size}`
+}

package/src/lib/og.test.ts

@@ -0,0 +1,142 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { buildSkillMeta, buildSoulMeta, fetchSkillMeta, fetchSoulMeta } from './og'
+
+describe('og helpers', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('builds metadata with owner and summary', () => {
+    const meta = buildSkillMeta({
+      slug: 'weather',
+      owner: 'steipete',
+      displayName: 'Weather',
+      summary: 'Forecasts for your area.',
+      version: '1.2.3',
+    })
+    expect(meta.title).toBe('Weather — PilotHub')
+    expect(meta.description).toBe('Forecasts for your area.')
+    expect(meta.url).toContain('/steipete/weather')
+    expect(meta.owner).toBe('steipete')
+    expect(meta.image).toContain('/og/skill.png?')
+    expect(meta.image).toContain('v=5')
+    expect(meta.image).toContain('slug=weather')
+    expect(meta.image).toContain('owner=steipete')
+    expect(meta.image).toContain('version=1.2.3')
+    expect(meta.image).not.toContain('title=')
+    expect(meta.image).not.toContain('description=')
+  })
+
+  it('builds soul metadata with summary', () => {
+    const meta = buildSoulMeta({
+      slug: 'north-star',
+      owner: 'someone',
+      displayName: 'North Star',
+      summary: 'Personal north star notes.',
+      version: '0.1.0',
+    })
+    expect(meta.title).toBe('North Star — SoulHub')
+    expect(meta.description).toBe('Personal north star notes.')
+    expect(meta.url).toContain('/souls/north-star')
+    expect(meta.owner).toBe('someone')
+    expect(meta.image).toContain('/og/soul.png?')
+    expect(meta.image).toContain('v=1')
+    expect(meta.image).toContain('slug=north-star')
+    expect(meta.image).toContain('owner=someone')
+    expect(meta.image).toContain('version=0.1.0')
+  })
+
+  it('uses defaults when owner and summary are missing', () => {
+    const meta = buildSkillMeta({ slug: 'parser' })
+    expect(meta.title).toBe('parser — PilotHub')
+    expect(meta.description).toMatch(/PilotHub — a fast skill registry/i)
+    expect(meta.url).toContain('/unknown/parser')
+    expect(meta.owner).toBeNull()
+    expect(meta.image).toContain('slug=parser')
+  })
+
+  it('uses soul defaults when owner and summary are missing', () => {
+    const meta = buildSoulMeta({ slug: 'signal' })
+    expect(meta.title).toBe('signal — SoulHub')
+    expect(meta.description).toMatch(/SoulHub — the home for SOUL.md/i)
+    expect(meta.url).toContain('/souls/signal')
+    expect(meta.owner).toBeNull()
+    expect(meta.image).toContain('slug=signal')
+  })
+
+  it('truncates long descriptions', () => {
+    const longSummary = 'a'.repeat(240)
+    const meta = buildSkillMeta({ slug: 'long', summary: longSummary })
+    expect(meta.description.length).toBe(200)
+    expect(meta.description.endsWith('…')).toBe(true)
+  })
+
+  it('fetches skill metadata when response is ok', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        skill: { displayName: 'Weather', summary: 'Forecasts' },
+        owner: { handle: 'steipete', userId: 'users:1' },
+        latestVersion: { version: '1.2.3' },
+      }),
+    }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const meta = await fetchSkillMeta('weather')
+    expect(meta).toEqual({
+      displayName: 'Weather',
+      summary: 'Forecasts',
+      owner: 'steipete',
+      ownerId: 'users:1',
+      version: '1.2.3',
+    })
+  })
+
+  it('fetches soul metadata when response is ok', async () => {
+    const fetchMock = vi.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        soul: { displayName: 'North Star', summary: 'Signal' },
+        owner: { handle: 'steipete' },
+        latestVersion: { version: '0.1.0' },
+      }),
+    }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const meta = await fetchSoulMeta('north-star')
+    expect(meta).toEqual({
+      displayName: 'North Star',
+      summary: 'Signal',
+      owner: 'steipete',
+      version: '0.1.0',
+    })
+  })
+
+  it('returns null when response is not ok', async () => {
+    const fetchMock = vi.fn(async () => ({ ok: false }))
+    vi.stubGlobal('fetch', fetchMock)
+
+    const meta = await fetchSkillMeta('weather')
+    expect(meta).toBeNull()
+  })
+
+  it('returns null when fetch throws', async () => {
+    const fetchMock = vi.fn(async () => {
+      throw new Error('network')
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const meta = await fetchSkillMeta('weather')
+    expect(meta).toBeNull()
+  })
+
+  it('returns null when soul fetch throws', async () => {
+    const fetchMock = vi.fn(async () => {
+      throw new Error('network')
+    })
+    vi.stubGlobal('fetch', fetchMock)
+
+    const meta = await fetchSoulMeta('north-star')
+    expect(meta).toBeNull()
+  })
+})

package/src/lib/og.ts

@@ -0,0 +1,156 @@
+import { getPilotHubSiteUrl, getOnlyCrabsSiteUrl } from './site'
+
+type SkillMetaSource = {
+  slug: string
+  owner?: string | null
+  ownerId?: string | null
+  displayName?: string | null
+  summary?: string | null
+  version?: string | null
+}
+
+type SkillMeta = {
+  title: string
+  description: string
+  image: string
+  url: string
+  owner: string | null
+}
+
+type SoulMetaSource = {
+  slug: string
+  owner?: string | null
+  displayName?: string | null
+  summary?: string | null
+  version?: string | null
+}
+
+type SoulMeta = {
+  title: string
+  description: string
+  image: string
+  url: string
+  owner: string | null
+}
+
+const DEFAULT_DESCRIPTION = 'PilotHub — a fast skill registry for agents, with vector search.'
+const DEFAULT_SOUL_DESCRIPTION = 'SoulHub — the home for SOUL.md bundles and personal system lore.'
+const OG_SKILL_IMAGE_LAYOUT_VERSION = '5'
+const OG_SOUL_IMAGE_LAYOUT_VERSION = '1'
+
+export function getSiteUrl() {
+  return getPilotHubSiteUrl()
+}
+
+export function getSoulSiteUrl() {
+  return getOnlyCrabsSiteUrl()
+}
+
+export function getApiBase() {
+  const explicit = import.meta.env.VITE_CONVEX_SITE_URL?.trim()
+  return explicit || getSiteUrl()
+}
+
+export async function fetchSkillMeta(slug: string) {
+  try {
+    const apiBase = getApiBase()
+    const url = new URL(`/api/v1/skills/${encodeURIComponent(slug)}`, apiBase)
+    const response = await fetch(url.toString(), { headers: { Accept: 'application/json' } })
+    if (!response.ok) return null
+    const payload = (await response.json()) as {
+      skill?: { displayName?: string; summary?: string | null } | null
+      owner?: { handle?: string | null; userId?: string | null } | null
+      latestVersion?: { version?: string | null } | null
+    }
+    return {
+      displayName: payload.skill?.displayName ?? null,
+      summary: payload.skill?.summary ?? null,
+      owner: payload.owner?.handle ?? null,
+      ownerId: payload.owner?.userId ?? null,
+      version: payload.latestVersion?.version ?? null,
+    }
+  } catch {
+    return null
+  }
+}
+
+export async function fetchSoulMeta(slug: string) {
+  try {
+    const apiBase = getApiBase()
+    const url = new URL(`/api/v1/souls/${encodeURIComponent(slug)}`, apiBase)
+    const response = await fetch(url.toString(), { headers: { Accept: 'application/json' } })
+    if (!response.ok) return null
+    const payload = (await response.json()) as {
+      soul?: { displayName?: string; summary?: string | null } | null
+      owner?: { handle?: string | null } | null
+      latestVersion?: { version?: string | null } | null
+    }
+    return {
+      displayName: payload.soul?.displayName ?? null,
+      summary: payload.soul?.summary ?? null,
+      owner: payload.owner?.handle ?? null,
+      version: payload.latestVersion?.version ?? null,
+    }
+  } catch {
+    return null
+  }
+}
+
+export function buildSkillMeta(source: SkillMetaSource): SkillMeta {
+  const siteUrl = getSiteUrl()
+  const owner = clean(source.owner)
+  const ownerId = clean(source.ownerId)
+  const displayName = clean(source.displayName) || clean(source.slug)
+  const summary = clean(source.summary)
+  const version = clean(source.version)
+  const title = `${displayName} — PilotHub`
+  const description =
+    summary || (owner ? `Agent skill by @${owner} on PilotHub.` : DEFAULT_DESCRIPTION)
+  const ownerPath = owner || ownerId || 'unknown'
+  const url = `${siteUrl}/${ownerPath}/${source.slug}`
+  const imageParams = new URLSearchParams()
+  imageParams.set('v', OG_SKILL_IMAGE_LAYOUT_VERSION)
+  imageParams.set('slug', source.slug)
+  if (owner) imageParams.set('owner', owner)
+  if (version) imageParams.set('version', version)
+  return {
+    title,
+    description: truncate(description, 200),
+    image: `${siteUrl}/og/skill.png?${imageParams.toString()}`,
+    url,
+    owner: owner || null,
+  }
+}
+
+export function buildSoulMeta(source: SoulMetaSource): SoulMeta {
+  const siteUrl = getSoulSiteUrl()
+  const owner = clean(source.owner)
+  const displayName = clean(source.displayName) || clean(source.slug)
+  const summary = clean(source.summary)
+  const version = clean(source.version)
+  const title = `${displayName} — SoulHub`
+  const description =
+    summary || (owner ? `Soul by @${owner} on SoulHub.` : DEFAULT_SOUL_DESCRIPTION)
+  const url = `${siteUrl}/souls/${source.slug}`
+  const imageParams = new URLSearchParams()
+  imageParams.set('v', OG_SOUL_IMAGE_LAYOUT_VERSION)
+  imageParams.set('slug', source.slug)
+  if (owner) imageParams.set('owner', owner)
+  if (version) imageParams.set('version', version)
+  return {
+    title,
+    description: truncate(description, 200),
+    image: `${siteUrl}/og/soul.png?${imageParams.toString()}`,
+    url,
+    owner: owner || null,
+  }
+}
+
+function clean(value?: string | null) {
+  return value?.trim() ?? ''
+}
+
+function truncate(value: string, max: number) {
+  if (value.length <= max) return value
+  return `${value.slice(0, max - 1).trim()}…`
+}

package/src/lib/publicUser.ts

@@ -0,0 +1,39 @@
+import type { Doc } from '../../convex/_generated/dataModel'
+
+export type PublicUser = Pick<
+  Doc<'users'>,
+  '_id' | '_creationTime' | 'handle' | 'name' | 'displayName' | 'image' | 'bio'
+>
+
+export type PublicSkill = Pick<
+  Doc<'skills'>,
+  | '_id'
+  | '_creationTime'
+  | 'slug'
+  | 'displayName'
+  | 'summary'
+  | 'ownerUserId'
+  | 'canonicalSkillId'
+  | 'forkOf'
+  | 'latestVersionId'
+  | 'tags'
+  | 'badges'
+  | 'stats'
+  | 'createdAt'
+  | 'updatedAt'
+>
+
+export type PublicSoul = Pick<
+  Doc<'souls'>,
+  | '_id'
+  | '_creationTime'
+  | 'slug'
+  | 'displayName'
+  | 'summary'
+  | 'ownerUserId'
+  | 'latestVersionId'
+  | 'tags'
+  | 'stats'
+  | 'createdAt'
+  | 'updatedAt'
+>

package/src/lib/roles.ts

@@ -0,0 +1,19 @@
+import type { Doc } from '../../convex/_generated/dataModel'
+import type { PublicSkill } from './publicUser'
+
+type User = Doc<'users'> | null | undefined
+
+type Skill = PublicSkill | null | undefined
+
+export function isAdmin(user: User) {
+  return user?.role === 'admin'
+}
+
+export function isModerator(user: User) {
+  return user?.role === 'admin' || user?.role === 'moderator'
+}
+
+export function canManageSkill(user: User, skill: Skill) {
+  if (!user || !skill) return false
+  return user._id === skill.ownerUserId || isModerator(user)
+}

package/src/lib/site.test.ts

@@ -0,0 +1,130 @@
+/* @vitest-environment node */
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import {
+  detectSiteMode,
+  detectSiteModeFromUrl,
+  getPilotHubSiteUrl,
+  getOnlyCrabsHost,
+  getOnlyCrabsSiteUrl,
+  getSiteDescription,
+  getSiteMode,
+  getSiteName,
+  getSiteUrlForMode,
+} from './site'
+
+function withMetaEnv<T>(values: Record<string, string | undefined>, run: () => T): T {
+  const env = import.meta.env as unknown as Record<string, unknown>
+  const previous = new Map<string, unknown>()
+  for (const [key, value] of Object.entries(values)) {
+    previous.set(key, env[key])
+    if (value === undefined) {
+      delete env[key]
+    } else {
+      env[key] = value
+    }
+  }
+  try {
+    return run()
+  } finally {
+    for (const [key, value] of previous.entries()) {
+      if (value === undefined) delete env[key]
+      else env[key] = value
+    }
+  }
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.unstubAllEnvs()
+})
+
+describe('site helpers', () => {
+  it('returns default and env configured site URLs', () => {
+    expect(getPilotHubSiteUrl()).toBe('https://pilothub.com')
+    withMetaEnv({ VITE_SITE_URL: 'https://example.com' }, () => {
+      expect(getPilotHubSiteUrl()).toBe('https://example.com')
+    })
+  })
+
+  it('picks SoulHub URL from explicit env', () => {
+    withMetaEnv({ VITE_SOULHUB_SITE_URL: 'https://souls.example.com' }, () => {
+      expect(getOnlyCrabsSiteUrl()).toBe('https://souls.example.com')
+    })
+  })
+
+  it('derives SoulHub URL from local VITE_SITE_URL', () => {
+    withMetaEnv({ VITE_SITE_URL: 'http://localhost:3000' }, () => {
+      expect(getOnlyCrabsSiteUrl()).toBe('http://localhost:3000')
+    })
+    withMetaEnv({ VITE_SITE_URL: 'http://127.0.0.1:3000' }, () => {
+      expect(getOnlyCrabsSiteUrl()).toBe('http://127.0.0.1:3000')
+    })
+    withMetaEnv({ VITE_SITE_URL: 'http://0.0.0.0:3000' }, () => {
+      expect(getOnlyCrabsSiteUrl()).toBe('http://0.0.0.0:3000')
+    })
+  })
+
+  it('falls back to default SoulHub URL for invalid VITE_SITE_URL', () => {
+    withMetaEnv({ VITE_SITE_URL: 'not a url' }, () => {
+      expect(getOnlyCrabsSiteUrl()).toBe('https://onlycrabs.ai')
+    })
+  })
+
+  it('detects site mode from host and URLs', () => {
+    expect(detectSiteMode(null)).toBe('skills')
+
+    withMetaEnv({ VITE_SOULHUB_HOST: 'souls.example.com' }, () => {
+      expect(getOnlyCrabsHost()).toBe('souls.example.com')
+      expect(detectSiteMode('souls.example.com')).toBe('souls')
+      expect(detectSiteMode('sub.souls.example.com')).toBe('souls')
+      expect(detectSiteMode('pilothub.com')).toBe('skills')
+
+      expect(detectSiteModeFromUrl('https://souls.example.com/x')).toBe('souls')
+      expect(detectSiteModeFromUrl('souls.example.com')).toBe('souls')
+      expect(detectSiteModeFromUrl('https://pilothub.com')).toBe('skills')
+    })
+  })
+
+  it('detects site mode from window when available', () => {
+    withMetaEnv({ VITE_SOULHUB_HOST: 'onlycrabs.ai' }, () => {
+      vi.stubGlobal('window', { location: { hostname: 'onlycrabs.ai' } } as unknown as Window)
+      expect(getSiteMode()).toBe('souls')
+    })
+  })
+
+  it('detects site mode from env on the server', () => {
+    withMetaEnv({ VITE_SITE_MODE: 'souls', VITE_SOULHUB_HOST: 'onlycrabs.ai' }, () => {
+      expect(getSiteMode()).toBe('souls')
+    })
+    withMetaEnv({ VITE_SITE_MODE: 'skills', VITE_SOULHUB_HOST: 'onlycrabs.ai' }, () => {
+      expect(getSiteMode()).toBe('skills')
+    })
+  })
+
+  it('detects site mode from VITE_SOULHUB_SITE_URL and SITE_URL fallback', () => {
+    withMetaEnv(
+      { VITE_SITE_MODE: undefined, VITE_SOULHUB_SITE_URL: 'https://onlycrabs.ai' },
+      () => {
+        expect(getSiteMode()).toBe('souls')
+      },
+    )
+
+    withMetaEnv({ VITE_SOULHUB_SITE_URL: undefined, VITE_SITE_URL: undefined }, () => {
+      vi.stubEnv('SITE_URL', 'https://onlycrabs.ai')
+      expect(getSiteMode()).toBe('souls')
+    })
+  })
+
+  it('derives site metadata from mode', () => {
+    expect(getSiteName('skills')).toBe('PilotHub')
+    expect(getSiteName('souls')).toBe('SoulHub')
+
+    expect(getSiteDescription('skills')).toContain('PilotHub')
+    expect(getSiteDescription('souls')).toContain('SoulHub')
+
+    expect(getSiteUrlForMode('skills')).toBe('https://pilothub.com')
+    expect(getSiteUrlForMode('souls')).toBe('https://onlycrabs.ai')
+  })
+})