feat(api): /api/js-apps with LLM-inferred categories

Add a curated route that filters the catalog to JS-embeddable apps
(`reachy_mini_js_app` tag) and enriches each entry with categories
inferred by Llama-3.1-8B-Instruct via HF Inference Providers, from
a closed taxonomy of 8 slugs (music, dance, voice, storytelling,
kids, vision, companion, dev-tools).

Inference results are persisted in a HF dataset
(`tfrere/reachy-mini-app-categories` by default, override via
HF_CATEGORIES_DATASET) and re-loaded at boot, so cold starts only
re-classify what actually changed (lastModified-keyed staleness).

Pre-existing /api/apps payload is unchanged: this is purely
additive. Mobile shell can adopt /api/js-apps incrementally.

- server/categories.js: 8-slug taxonomy + LLM-friendly descriptions
- server/categorize.js: README fetch/clean + chat-completion call
- server/categoryCache.js: in-mem map + dataset commit/load
- server/index.js: route, warmup batch, manual refresh endpoint
- .env.example: HF_TOKEN + HF_CATEGORIES_DATASET docs
- .gitignore: ignore local .env

Co-authored-by: Cursor <cursoragent@cursor.com>

.env.example

@@ -0,0 +1,35 @@
+# Reachy Mini Website server env vars
+#
+# Copy this file to `.env` and fill in the values for local dev.
+# In production (HF Space), set these from the Space's "Settings →
+# Variables and secrets" panel, NOT from a committed `.env`.
+# (`.env` is gitignored.)
+
+# -----------------------------------------------------------------------------
+# Server
+# -----------------------------------------------------------------------------
+# Port the Express server listens on. Defaults to 7860 (HF Space convention).
+# PORT=7860
+
+# -----------------------------------------------------------------------------
+# OAuth (used by /api/oauth-config and the in-iframe sign-in flow)
+# -----------------------------------------------------------------------------
+# Set in the Space when `hf_oauth: true` is in README.md.
+# OAUTH_CLIENT_ID=
+# OAUTH_SCOPES=openid profile
+
+# -----------------------------------------------------------------------------
+# HF Inference Providers (used by /api/js-apps category inference)
+# -----------------------------------------------------------------------------
+# Required for category inference. A standard READ token is enough -
+# Inference Providers access is on by default for FREE/PRO tokens.
+# Without this, /api/js-apps still works but every entry will have
+# `categories: null` (the route logs a warning at startup).
+HF_TOKEN=
+
+# Dataset where the inferred-categories cache is persisted.
+# Defaults to `tfrere/reachy-mini-app-categories` (per-user namespace,
+# auto-created on first commit). Override to e.g.
+# `pollen-robotics/reachy-mini-app-categories` once the org dataset
+# exists and the HF_TOKEN has write access to it.
+# HF_CATEGORIES_DATASET=tfrere/reachy-mini-app-categories

.gitignore

@@ -22,3 +22,5 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+
+.env

server/categories.js

@@ -0,0 +1,145 @@
+/**
+ * Predefined taxonomy for JS Reachy Mini apps.
+ *
+ * These slugs are the ONLY valid output values for the LLM
+ * inference step (anything else is dropped at parse time) and
+ * the values consumers (mobile shell, website) filter on.
+ *
+ * Why a closed list instead of free-form tags
+ * ──────────────────────────────────────────
+ * The HF Spaces catalog has no usable categorization for the
+ * reachy_mini_js_app subset (only platform/SDK tags). We bridge
+ * the gap by inferring categories with an LLM, but we have to
+ * constrain the model's output: a closed list keeps category
+ * pages stable, lets us pre-pick emojis/labels, and avoids the
+ * "30 near-duplicate slugs" problem you'd get with free-form.
+ *
+ * Bumping the taxonomy
+ * ────────────────────
+ * Adding, removing or renaming a slug changes the meaning of
+ * cached entries. Bump TAXONOMY_VERSION when you do that: the
+ * cache layer compares each entry's `taxonomyVersion` against
+ * the live one and recomputes stale ones on the next pass.
+ */
+
+export const TAXONOMY_VERSION = 1;
+
+/**
+ * Canonical category list. Keep slugs short, kebab-case, and
+ * memorable: they end up in URLs (e.g. `?cat=music`) and in
+ * filter chips on mobile.
+ *
+ * The `description` field is the SOLE source of truth the LLM
+ * sees - keep them factual, scope-bounded, and example-led so
+ * the model has signal for both inclusion and exclusion.
+ */
+export const CATEGORIES = [
+  {
+    slug: 'music',
+    label: 'Music & Beats',
+    emoji: '🎵',
+    description:
+      'Apps where Reachy plays, mixes, generates, or reacts to music ' +
+      '(DJ sets, beat-makers, blind-tests). NOT for apps that just ' +
+      'happen to use audio cues.',
+  },
+  {
+    slug: 'dance',
+    label: 'Dance & Motion',
+    emoji: '💃',
+    description:
+      'Apps centered on dance choreographies, motion replay, ' +
+      'kinetic shows, or recording/replaying robot movements.',
+  },
+  {
+    slug: 'voice',
+    label: 'Voice & Conversation',
+    emoji: '🗣️',
+    description:
+      'Apps where Reachy talks, listens, or holds a real-time voice ' +
+      'conversation: TTS players, LLM-driven chat (OpenAI Realtime, ' +
+      'Claude, Perplexity, etc.), wake-word demos.',
+  },
+  {
+    slug: 'storytelling',
+    label: 'Stories',
+    emoji: '📖',
+    description:
+      'Apps that tell, generate, or guide narrative stories ' +
+      '(interactive fiction, bedtime stories, narrated adventures).',
+  },
+  {
+    slug: 'kids',
+    label: 'For Kids',
+    emoji: '🧒',
+    description:
+      'Apps explicitly designed for children: encyclopedias, ' +
+      'kid-friendly stories, learning games, simple Q&A.',
+  },
+  {
+    slug: 'vision',
+    label: 'Vision & Camera',
+    emoji: '👁️',
+    description:
+      "Apps that consume Reachy's camera feed: face/hand tracking, " +
+      'image classification, mimicry, gesture detection.',
+  },
+  {
+    slug: 'companion',
+    label: 'Companion',
+    emoji: '🤝',
+    description:
+      'Apps positioned as life/emotional companions, mood support, ' +
+      'or friendly buddies that develop a personality over time.',
+  },
+  {
+    slug: 'dev-tools',
+    label: 'Dev & Demos',
+    emoji: '🛠️',
+    description:
+      'Technical demos, debugging tools, remote-control utilities, ' +
+      'minimal proof-of-concepts, and dev-only experiments meant to ' +
+      'showcase a single API or behaviour.',
+  },
+];
+
+export const ALLOWED_SLUGS = new Set(CATEGORIES.map((c) => c.slug));
+
+export function isValidSlug(slug) {
+  return ALLOWED_SLUGS.has(slug);
+}
+
+/**
+ * Render the taxonomy as a bulleted list for the LLM prompt.
+ * Format mirrors what the model is asked to output (slug first)
+ * to nudge it towards copying the exact string back.
+ */
+export function buildLlmCategoryList() {
+  return CATEGORIES.map((c) => `- ${c.slug}: ${c.description}`).join('\n');
+}
+
+/**
+ * Sanitize a raw LLM-returned list of slugs:
+ * - drop non-strings
+ * - lowercase + trim
+ * - drop unknown slugs (hallucinations)
+ * - dedupe while preserving order (the model orders by relevance)
+ * - cap to MAX_CATEGORIES
+ *
+ * Returns a fresh array; never mutates input.
+ */
+export function sanitizeSlugs(raw, maxCategories = 3) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const v of raw) {
+    if (typeof v !== 'string') continue;
+    const slug = v.trim().toLowerCase();
+    if (!slug || seen.has(slug)) continue;
+    if (!ALLOWED_SLUGS.has(slug)) continue;
+    seen.add(slug);
+    out.push(slug);
+    if (out.length >= maxCategories) break;
+  }
+  return out;
+}

server/categorize.js

@@ -0,0 +1,292 @@
+/**
+ * LLM-based category inference for JS Reachy Mini apps.
+ *
+ * Pipeline (`categorizeApp`)
+ * ──────────────────────────
+ *   1. Fetch the Space's README from HF Hub (raw)
+ *   2. Strip frontmatter, images, badges, raw HTML, then truncate
+ *   3. Call a chat LLM via HF Inference Providers (OpenAI-compatible)
+ *      with the predefined taxonomy + the app's name/description
+ *   4. Parse JSON, validate against ALLOWED_SLUGS, keep up to 3
+ *
+ * Robustness contract
+ * ───────────────────
+ * `categorizeApp` NEVER throws on transient failure (network,
+ * 429, malformed JSON). It returns `null`, which the cache layer
+ * interprets as "not yet categorized; retry on the next pass".
+ * Hard errors (HF_TOKEN missing) are signalled by a thrown
+ * `HfTokenMissingError` so the caller can short-circuit the
+ * whole batch.
+ */
+
+import {
+  buildLlmCategoryList,
+  sanitizeSlugs,
+} from './categories.js';
+
+// HF Inference Providers - OpenAI-compatible router. Auto-routes
+// the request to whichever provider currently serves the model
+// (Together, Nebius, Fireworks, Sambanova...). The token must
+// have `Inference Providers` access (default for all PRO and
+// most FREE tokens since 2025).
+const HF_INFERENCE_URL = 'https://router.huggingface.co/v1/chat/completions';
+
+// 8B model: cheap, fast (~1 s per call), more than enough for a
+// closed-list multi-label classification with good descriptions.
+// If quality drifts we can swap to 70B without touching anything
+// else - the prompt is generic.
+const DEFAULT_MODEL = 'meta-llama/Llama-3.1-8B-Instruct';
+
+// README budget
+const README_MAX_CHARS = 3000;
+const MAX_CATEGORIES_PER_APP = 3;
+
+// LLM call budget
+const LLM_TIMEOUT_MS = 30_000;
+const LLM_MAX_TOKENS = 120;
+const LLM_TEMPERATURE = 0;
+
+export class HfTokenMissingError extends Error {
+  constructor() {
+    super('HF_TOKEN env var is not set; cannot call HF Inference Providers.');
+    this.name = 'HfTokenMissingError';
+  }
+}
+
+/**
+ * Fetch a Space's README from HF Hub. Returns the raw markdown
+ * string, or `null` if the request fails (404, network, etc.) -
+ * the caller falls back to "name + description only" in that case,
+ * which is still enough signal for the LLM on most apps.
+ */
+export async function fetchSpaceReadme(spaceId, { signal } = {}) {
+  if (!spaceId || typeof spaceId !== 'string') return null;
+  // The README of a HF Space lives at /spaces/<id>/raw/main/README.md.
+  // The `raw` endpoint returns the file as-is (no Hub UI wrapping)
+  // and is anonymous-friendly, so no auth is needed here.
+  const url = `https://huggingface.co/spaces/${spaceId}/raw/main/README.md`;
+  try {
+    const res = await fetch(url, { signal });
+    if (!res.ok) return null;
+    return await res.text();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Lightly clean a raw README so the LLM doesn't burn tokens on
+ * boilerplate (HF frontmatter, badges, images) and so the actual
+ * prose surfaces above the truncation budget.
+ *
+ * We keep transformations conservative: we never edit the
+ * surrounding prose, we just delete decorative tokens. Anything
+ * cosmetic-only that clearly isn't signal for classification
+ * (badges, images, raw HTML).
+ */
+export function cleanReadme(raw) {
+  if (!raw || typeof raw !== 'string') return '';
+  let txt = raw;
+
+  // 1. Strip the YAML frontmatter at the very top (HF Spaces
+  //    ship a mandatory `---\n...metadata...\n---` block whose
+  //    fields are already exposed to us via the catalog payload,
+  //    so feeding them to the LLM is pure noise).
+  txt = txt.replace(/^---\n[\s\S]*?\n---\n?/, '');
+
+  // 2. Drop image markdown (`![alt](url)`) and HTML <img> tags.
+  //    Vision apps tend to load up READMEs with screenshots and
+  //    GIFs; the alt text is sometimes useful but more often it's
+  //    "demo.gif" - low signal/noise ratio.
+  txt = txt.replace(/!\[[^\]]*\]\([^)]+\)/g, '');
+  txt = txt.replace(/<img\b[^>]*>/gi, '');
+
+  // 3. Strip shields.io / GitHub badges (markdown links that
+  //    wrap an image). They survive (2) only when nested.
+  txt = txt.replace(/\[!\[[^\]]*\]\([^)]+\)\]\([^)]+\)/g, '');
+
+  // 4. Generic HTML stripping. Most READMEs are pure markdown,
+  //    but some authors embed `<details>`, `<sub>`, `<center>`
+  //    blocks. Keep the inner text, drop the tags.
+  txt = txt.replace(/<\/?[a-zA-Z][^>]*>/g, '');
+
+  // 5. Collapse runs of blank lines so trimming doesn't waste
+  //    tokens on the gap.
+  txt = txt.replace(/\n{3,}/g, '\n\n');
+
+  // 6. Truncate. We slice at the paragraph boundary closest to
+  //    the budget so we don't end mid-sentence.
+  if (txt.length > README_MAX_CHARS) {
+    const cut = txt.lastIndexOf('\n\n', README_MAX_CHARS);
+    txt = txt.slice(0, cut > README_MAX_CHARS / 2 ? cut : README_MAX_CHARS);
+  }
+
+  return txt.trim();
+}
+
+/**
+ * Build the chat messages handed to the LLM. The system prompt
+ * pins the closed taxonomy + the output shape; the user prompt
+ * is the app context.
+ *
+ * We deliberately spell out the JSON-only constraint twice
+ * (system + user) because mid-tier 8B models tend to drift into
+ * conversational replies on classification tasks otherwise.
+ */
+function buildMessages({ name, description, readme }) {
+  const taxonomy = buildLlmCategoryList();
+  const system = [
+    'You classify a Reachy Mini robot app into a closed list of categories.',
+    '',
+    'Output ONLY a single JSON object with this exact shape:',
+    '{"categories": ["slug1", "slug2"]}',
+    '',
+    `Pick 1 to ${MAX_CATEGORIES_PER_APP} categories from the list below, ` +
+      'ordered from most to least relevant. Use the EXACT slug.',
+    'If none of the categories clearly fits, output {"categories": []}.',
+    '',
+    'Available categories:',
+    taxonomy,
+    '',
+    'Do not include any text outside the JSON object. No prose, no code fences.',
+  ].join('\n');
+
+  const user = [
+    `App name: ${name || '(unknown)'}`,
+    `Short description: ${description || '(none)'}`,
+    '',
+    'README excerpt:',
+    readme || '(no README available)',
+    '',
+    'Return the JSON now.',
+  ].join('\n');
+
+  return [
+    { role: 'system', content: system },
+    { role: 'user', content: user },
+  ];
+}
+
+/**
+ * Best-effort JSON extraction. Some 8B models still wrap the
+ * answer in ``` fences or prepend "Sure, here you go:". We grab
+ * the first balanced `{...}` block and parse that.
+ */
+function extractJsonObject(text) {
+  if (!text || typeof text !== 'string') return null;
+  const start = text.indexOf('{');
+  if (start === -1) return null;
+  let depth = 0;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) {
+        const slice = text.slice(start, i + 1);
+        try {
+          return JSON.parse(slice);
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Call the HF Inference Providers chat endpoint. Returns the
+ * raw assistant message string, or `null` on any error.
+ */
+async function callLlm({ messages, model, signal }) {
+  const token = process.env.HF_TOKEN;
+  if (!token) throw new HfTokenMissingError();
+
+  const body = {
+    model,
+    messages,
+    temperature: LLM_TEMPERATURE,
+    max_tokens: LLM_MAX_TOKENS,
+    // `response_format` is honoured by some providers (Nebius,
+    // Together) but ignored by others. It's a free upgrade when
+    // present, harmless otherwise; the JSON-extractor below is
+    // the real safety net.
+    response_format: { type: 'json_object' },
+  };
+
+  let res;
+  try {
+    res = await fetch(HF_INFERENCE_URL, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+  } catch (err) {
+    console.warn(`[categorize] LLM fetch failed: ${err.message}`);
+    return null;
+  }
+
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '');
+    console.warn(
+      `[categorize] LLM HTTP ${res.status}: ${detail.slice(0, 200)}`,
+    );
+    return null;
+  }
+
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    return null;
+  }
+  return json?.choices?.[0]?.message?.content ?? null;
+}
+
+/**
+ * Public entry point.
+ *
+ * Returns a string[] of validated slugs (0-3 items), or `null`
+ * on transient failure so the caller can mark the entry "needs
+ * retry" without writing a misleading empty list.
+ *
+ * Treat an empty array `[]` as "the LLM looked and concluded
+ * none fit" - that's a valid, cacheable outcome.
+ */
+export async function categorizeApp({
+  name,
+  description,
+  spaceId,
+  model = DEFAULT_MODEL,
+} = {}) {
+  if (!spaceId) return null;
+
+  const ctrl = new AbortController();
+  const timeoutId = setTimeout(() => ctrl.abort(), LLM_TIMEOUT_MS);
+
+  try {
+    const rawReadme = await fetchSpaceReadme(spaceId, { signal: ctrl.signal });
+    const readme = cleanReadme(rawReadme);
+
+    const messages = buildMessages({ name, description, readme });
+    const reply = await callLlm({ messages, model, signal: ctrl.signal });
+    if (reply == null) return null;
+
+    const obj = extractJsonObject(reply);
+    if (!obj || !Array.isArray(obj.categories)) {
+      console.warn(
+        `[categorize] ${spaceId}: malformed LLM reply (truncated): ` +
+          `${reply.slice(0, 120)}`,
+      );
+      return null;
+    }
+    return sanitizeSlugs(obj.categories, MAX_CATEGORIES_PER_APP);
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}

server/categoryCache.js

@@ -0,0 +1,290 @@
+/**
+ * Persistent cache for inferred app categories, backed by a
+ * HuggingFace dataset.
+ *
+ * Why a dataset (not a local file)
+ * ────────────────────────────────
+ * The website runs in a Docker HF Space. The container's
+ * filesystem is wiped on every rebuild (and rebuilds happen
+ * on every push, every model update, every Space restart).
+ * Re-running 200 LLM calls every cold start would be wasteful
+ * and slow the user-visible /api/js-apps for the first 30 s.
+ *
+ * Pushing the cache to a dataset gives us:
+ *   1. Persistence across rebuilds and machine moves
+ *   2. A versioned audit log of how categories evolve
+ *   3. A single source of truth other tooling can consume
+ *      (the mobile shell could even read the dataset directly
+ *      if it ever wanted to bypass the website).
+ *
+ * Storage shape
+ * ─────────────
+ *   <dataset>/categories.json
+ *
+ *   {
+ *     "version": 1,
+ *     "taxonomyVersion": 1,
+ *     "updatedAt": "2026-05-10T11:08:42Z",
+ *     "entries": {
+ *       "<spaceId>": {
+ *         "lastModified": "2026-05-08T22:13:01Z",
+ *         "categories": ["storytelling", "kids", "voice"],
+ *         "categorizedAt": "2026-05-10T11:08:42Z",
+ *         "taxonomyVersion": 1
+ *       }
+ *     }
+ *   }
+ *
+ * In-memory tier
+ * ──────────────
+ * The Map<spaceId, entry> is the hot path. The dataset is
+ * loaded once at boot and only flushed when entries actually
+ * change (the warmup batch buffers writes and flushes once
+ * at the end). All synchronous access goes through the Map.
+ */
+
+import { commit, createRepo } from '@huggingface/hub';
+
+import { TAXONOMY_VERSION } from './categories.js';
+
+// Default location: a per-user dataset that the HF_TOKEN owner
+// definitely has write access to. Override with the env var
+// when promoting to the org-owned `pollen-robotics/...` dataset.
+const DEFAULT_DATASET = 'tfrere/reachy-mini-app-categories';
+
+const CACHE_FILE_PATH = 'categories.json';
+const CACHE_FORMAT_VERSION = 1;
+
+class CategoryCache {
+  constructor() {
+    this.entries = new Map();
+    this.repoName = process.env.HF_CATEGORIES_DATASET || DEFAULT_DATASET;
+    this.loaded = false;
+    this.dirty = false;
+    // Concurrency guard for `flush()` - we never want two
+    // commit() calls fighting for the same parent commit.
+    this.flushing = false;
+  }
+
+  /**
+   * Load the dataset cache into memory. Best-effort: a missing
+   * dataset, a 404, or a malformed JSON all collapse to "start
+   * fresh, the warmup will repopulate". We never let cache load
+   * failure block the server boot.
+   */
+  async load() {
+    if (this.loaded) return;
+    this.loaded = true;
+
+    const url = `https://huggingface.co/datasets/${this.repoName}/resolve/main/${CACHE_FILE_PATH}`;
+    try {
+      const res = await fetch(url, {
+        // Send the token even on a public dataset: it lets HF
+        // bump our rate limit and keeps the path identical for
+        // a future private dataset migration.
+        headers: process.env.HF_TOKEN
+          ? { Authorization: `Bearer ${process.env.HF_TOKEN}` }
+          : undefined,
+      });
+      if (!res.ok) {
+        if (res.status === 404) {
+          console.log(
+            `[CategoryCache] Dataset ${this.repoName} or ${CACHE_FILE_PATH} ` +
+              `not found yet - starting empty.`,
+          );
+        } else {
+          console.warn(
+            `[CategoryCache] HTTP ${res.status} loading cache from ` +
+              `${this.repoName}, starting empty.`,
+          );
+        }
+        return;
+      }
+      const data = await res.json();
+      const entries = data?.entries || {};
+      let kept = 0;
+      let staleTaxonomy = 0;
+      for (const [id, raw] of Object.entries(entries)) {
+        if (!raw || typeof raw !== 'object') continue;
+        // Drop entries from a previous taxonomy: their slugs
+        // may no longer exist or may have shifted meaning.
+        // The warmup will re-run them.
+        if (raw.taxonomyVersion !== TAXONOMY_VERSION) {
+          staleTaxonomy++;
+          continue;
+        }
+        this.entries.set(id, {
+          lastModified: raw.lastModified || null,
+          categories: Array.isArray(raw.categories) ? raw.categories : [],
+          categorizedAt: raw.categorizedAt || null,
+          taxonomyVersion: raw.taxonomyVersion,
+        });
+        kept++;
+      }
+      console.log(
+        `[CategoryCache] Loaded ${kept} entries from ${this.repoName}` +
+          (staleTaxonomy ? ` (dropped ${staleTaxonomy} stale taxonomy)` : ''),
+      );
+    } catch (err) {
+      console.warn(
+        `[CategoryCache] Load failed (${err.message}); starting empty.`,
+      );
+    }
+  }
+
+  get(spaceId) {
+    return this.entries.get(spaceId) || null;
+  }
+
+  /**
+   * Decide whether `spaceId` needs a fresh classification call.
+   * It does when:
+   *   - we have no entry at all, OR
+   *   - the Space's `lastModified` has moved past our cached one
+   *     (the README may have changed - re-classify), OR
+   *   - the taxonomy version moved (handled at load() time, but
+   *     belt-and-braces for hot reloads).
+   */
+  needsCategorization(spaceId, lastModified) {
+    const entry = this.entries.get(spaceId);
+    if (!entry) return true;
+    if (entry.taxonomyVersion !== TAXONOMY_VERSION) return true;
+    if (lastModified && entry.lastModified !== lastModified) return true;
+    return false;
+  }
+
+  set(spaceId, { categories, lastModified }) {
+    if (!Array.isArray(categories)) return;
+    const next = {
+      lastModified: lastModified || null,
+      categories: [...categories],
+      categorizedAt: new Date().toISOString(),
+      taxonomyVersion: TAXONOMY_VERSION,
+    };
+    const prev = this.entries.get(spaceId);
+    // Skip the dirty flag if nothing actually changed - avoids
+    // a useless commit when a refresh confirms the same labels.
+    if (
+      prev &&
+      prev.lastModified === next.lastModified &&
+      prev.taxonomyVersion === next.taxonomyVersion &&
+      JSON.stringify(prev.categories) === JSON.stringify(next.categories)
+    ) {
+      return;
+    }
+    this.entries.set(spaceId, next);
+    this.dirty = true;
+  }
+
+  /**
+   * Persist the in-memory cache to the dataset (one commit, one
+   * file). No-op if nothing has changed since the last flush.
+   *
+   * Auto-creates the dataset on first write if it doesn't exist
+   * yet (so a brand-new `HF_CATEGORIES_DATASET` value bootstraps
+   * cleanly without manual setup).
+   */
+  async flush() {
+    if (!this.dirty || this.flushing) return;
+    if (!process.env.HF_TOKEN) {
+      console.warn('[CategoryCache] HF_TOKEN missing; skipping flush.');
+      return;
+    }
+    this.flushing = true;
+    try {
+      const payload = this.serialize();
+      const blob = new Blob([JSON.stringify(payload, null, 2)], {
+        type: 'application/json',
+      });
+
+      const repo = { type: 'dataset', name: this.repoName };
+      const credentials = { accessToken: process.env.HF_TOKEN };
+
+      // First attempt: plain commit. If the dataset doesn't
+      // exist yet, the SDK throws and we fall through to
+      // create-then-commit. We never assume the dataset exists
+      // - that lets a fresh deploy auto-bootstrap.
+      try {
+        await commit({
+          repo,
+          credentials,
+          title: `Update categories (${this.entries.size} apps)`,
+          operations: [
+            {
+              operation: 'addOrUpdate',
+              path: CACHE_FILE_PATH,
+              content: blob,
+            },
+          ],
+        });
+      } catch (err) {
+        const msg = err?.message || '';
+        const looksMissing =
+          msg.includes('404') ||
+          msg.toLowerCase().includes('not found') ||
+          msg.toLowerCase().includes('does not exist');
+        if (!looksMissing) throw err;
+        console.log(
+          `[CategoryCache] Dataset ${this.repoName} missing - creating it.`,
+        );
+        await createRepo({
+          repo,
+          credentials,
+          private: false,
+          // Re-using the same blob so the initial commit ships
+          // the cache content (instead of an empty repo
+          // followed by a no-op commit).
+          files: [
+            {
+              path: CACHE_FILE_PATH,
+              content: await blob.arrayBuffer(),
+            },
+          ],
+        });
+      }
+
+      this.dirty = false;
+      console.log(
+        `[CategoryCache] Flushed ${this.entries.size} entries to ${this.repoName}`,
+      );
+    } catch (err) {
+      // We deliberately swallow flush errors so a HF outage
+      // doesn't break the running server. The next set() will
+      // re-flag dirty=true and the next flush() will retry.
+      console.error(
+        `[CategoryCache] Flush failed: ${err?.message || err}`,
+      );
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  serialize() {
+    const entries = {};
+    for (const [id, entry] of this.entries) {
+      entries[id] = entry;
+    }
+    return {
+      version: CACHE_FORMAT_VERSION,
+      taxonomyVersion: TAXONOMY_VERSION,
+      updatedAt: new Date().toISOString(),
+      entries,
+    };
+  }
+
+  /**
+   * Diagnostic snapshot for /api/js-apps's `categorization`
+   * sub-payload. Lets the mobile shell decide whether to show
+   * "loading categories..." or to render the chips immediately.
+   */
+  stats() {
+    return {
+      total: this.entries.size,
+      dataset: this.repoName,
+      taxonomyVersion: TAXONOMY_VERSION,
+    };
+  }
+}
+
+// Singleton: there's only one cache per server process.
+export const categoryCache = new CategoryCache();

server/index.js

@@ -1,9 +1,42 @@
 import express from 'express';
+import { existsSync, readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 
+import { categorizeApp, HfTokenMissingError } from './categorize.js';
+import { categoryCache } from './categoryCache.js';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
+// Load `.env` from the repo root in dev. In production (HF Space)
+// the platform already injects the secrets as env vars, so this
+// loader silently no-ops. We avoid the `dotenv` dep on purpose -
+// the format is trivial, and reproducing it inline keeps the
+// runtime closure tiny.
+(function loadDotenv() {
+  try {
+    const envPath = path.join(__dirname, '..', '.env');
+    if (!existsSync(envPath)) return;
+    const text = readFileSync(envPath, 'utf8');
+    for (const line of text.split(/\r?\n/)) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/i);
+      if (!m) continue;
+      const [, key, raw] = m;
+      let value = raw;
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+      // Existing env wins (so `HF_TOKEN=foo node …` overrides .env).
+      if (process.env[key] === undefined) process.env[key] = value;
+    }
+  } catch {
+    /* best-effort - missing or malformed .env never blocks boot */
+  }
+})();
+
 const app = express();
 const PORT = process.env.PORT || 7860;
 
@@ -14,6 +47,18 @@ const HF_SPACES_API = 'https://huggingface.co/api/spaces';
 // Note: HF API doesn't support pagination with filter=, so we use a high limit
 const HF_SPACES_LIMIT = 1000;
 
+// Tag that gates the JS-only subset surfaced by /api/js-apps and
+// fed to the LLM categorizer. Mirrors the filter the mobile shell
+// applies today client-side; the route lets us retire that filter
+// from the mobile codebase down the line.
+const JS_APP_TAG = 'reachy_mini_js_app';
+
+// Serialised LLM batch concurrency: we want at most one
+// categorization sweep running at a time, regardless of how many
+// /api/js-apps requests come in. The flag also prevents the
+// startup warm-up and an on-demand refresh from racing each other.
+let categorizationBatchRunning = false;
+
 // In-memory cache
 let appsCache = {
   data: null,
@@ -183,6 +228,221 @@ app.get('/api/apps', async (req, res) => {
   }
 });
 
+// =====================================================================
+// JS apps + LLM-inferred categories
+// =====================================================================
+//
+// `/api/js-apps` is a curated view on top of `/api/apps`:
+//   1. Filter on the `reachy_mini_js_app` tag (the mobile-embeddable subset).
+//   2. Enrich each entry with `categories` + `categories_source`,
+//      sourced from a persistent dataset cache (see categoryCache.js).
+//
+// Categories are inferred lazily by an LLM from each Space's
+// README. The first request after a cold start may see entries
+// with `categories: null` while the warmup batch is still in
+// flight; subsequent requests pick them up as the cache fills.
+
+/**
+ * Pull the JS-app subset out of the global apps cache and fold
+ * in cached categories. Pure, synchronous-ish (the only async
+ * call is to the upstream `getApps()` which has its own cache).
+ */
+async function getJsApps() {
+  const apps = await getApps();
+  const jsApps = apps.filter((a) => {
+    const tags = a?.extra?.tags;
+    return Array.isArray(tags) && tags.includes(JS_APP_TAG);
+  });
+
+  return jsApps.map((app) => {
+    const cached = categoryCache.get(app.id);
+    return {
+      ...app,
+      categories: cached ? cached.categories : null,
+      categories_source: cached ? 'inferred' : null,
+      categorized_at: cached ? cached.categorizedAt : null,
+    };
+  });
+}
+
+/**
+ * Run one classification pass over `jsApps`. Skips entries whose
+ * cache is still fresh (same `lastModified`, same taxonomy).
+ *
+ * Serial on purpose: HF Inference Providers don't love bursts
+ * from a single token, and total throughput on ~50 apps stays
+ * well under a minute. We slip a small jitter between calls to
+ * smooth the curve further.
+ */
+async function runCategorizationBatch(jsApps) {
+  if (categorizationBatchRunning) {
+    console.log('[Categorize] Batch already running, skipping.');
+    return;
+  }
+  if (!process.env.HF_TOKEN) {
+    console.warn(
+      '[Categorize] HF_TOKEN not set; skipping batch. Set it in .env ' +
+        'or the Space secrets to enable category inference.',
+    );
+    return;
+  }
+
+  const todo = jsApps.filter((app) =>
+    categoryCache.needsCategorization(app.id, app?.extra?.lastModified),
+  );
+
+  if (todo.length === 0) {
+    console.log(
+      `[Categorize] All ${jsApps.length} JS apps are already categorized.`,
+    );
+    return;
+  }
+
+  categorizationBatchRunning = true;
+  console.log(
+    `[Categorize] Starting batch: ${todo.length}/${jsApps.length} app(s) need classification.`,
+  );
+
+  let success = 0;
+  let failed = 0;
+  let aborted = false;
+
+  for (let i = 0; i < todo.length; i++) {
+    const app = todo[i];
+    const desc =
+      app.description ||
+      app.extra?.cardData?.short_description ||
+      '';
+    try {
+      const slugs = await categorizeApp({
+        spaceId: app.id,
+        name: app.name,
+        description: desc,
+      });
+      if (slugs == null) {
+        failed++;
+        console.log(
+          `[Categorize]   (${i + 1}/${todo.length}) ${app.id}: transient failure, will retry next pass`,
+        );
+      } else {
+        categoryCache.set(app.id, {
+          categories: slugs,
+          lastModified: app.extra?.lastModified || null,
+        });
+        success++;
+        console.log(
+          `[Categorize]   (${i + 1}/${todo.length}) ${app.id}: ${
+            slugs.length ? slugs.join(', ') : '(no fit)'
+          }`,
+        );
+      }
+    } catch (err) {
+      if (err instanceof HfTokenMissingError) {
+        console.warn(
+          '[Categorize] HF_TOKEN missing mid-batch; aborting cleanly.',
+        );
+        aborted = true;
+        break;
+      }
+      failed++;
+      console.warn(
+        `[Categorize]   (${i + 1}/${todo.length}) ${app.id}: error - ${err.message}`,
+      );
+    }
+
+    // 250 ms cooldown between calls. Below this, the HF Provider
+    // router occasionally rate-limits a hot token.
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+
+  console.log(
+    `[Categorize] Batch done: ${success} ok, ${failed} failed${aborted ? ' (aborted)' : ''}.`,
+  );
+  // Persist the new entries even if some failed - partial
+  // progress is strictly better than none, and the failed
+  // entries will be retried on the next pass.
+  await categoryCache.flush();
+
+  categorizationBatchRunning = false;
+}
+
+/**
+ * Wrap the diagnostic snapshot for the API payload. Lets
+ * consumers (mobile shell, website) decide whether to show
+ * "loading categories..." or render chips immediately.
+ */
+function buildCategorizationStats(jsApps) {
+  let withCategories = 0;
+  for (const app of jsApps) {
+    if (app.categories && app.categories.length >= 0 && app.categories_source) {
+      withCategories++;
+    }
+  }
+  return {
+    enabled: !!process.env.HF_TOKEN,
+    total: jsApps.length,
+    classified: withCategories,
+    pending: jsApps.length - withCategories,
+    inProgress: categorizationBatchRunning,
+    ...categoryCache.stats(),
+  };
+}
+
+app.get('/api/js-apps', async (req, res) => {
+  try {
+    const apps = await getJsApps();
+
+    // Background top-up: if any entry is still uncategorized
+    // (or a Space's lastModified moved since we last looked),
+    // fire off a batch. We DO NOT await it - the response goes
+    // out immediately with whatever the cache currently knows.
+    const needsWork = apps.some(
+      (a) =>
+        !a.categories_source ||
+        categoryCache.needsCategorization(a.id, a.extra?.lastModified),
+    );
+    if (needsWork) {
+      // `void` to make it crystal clear we don't expect a value;
+      // the batch logs its own progress.
+      void runCategorizationBatch(apps).catch((err) => {
+        console.error('[Categorize] Background batch crashed:', err);
+      });
+    }
+
+    res.json({
+      apps,
+      cached: true,
+      cacheAge: appsCache.lastFetch
+        ? Math.round((Date.now() - appsCache.lastFetch) / 1000)
+        : 0,
+      count: apps.length,
+      categorization: buildCategorizationStats(apps),
+    });
+  } catch (err) {
+    console.error('[API] /api/js-apps error:', err);
+    res.status(500).json({ error: 'Failed to fetch JS apps' });
+  }
+});
+
+// Manual trigger for a categorization sweep, useful when
+// hand-tuning the taxonomy or testing the LLM prompt without
+// waiting for the next /api/js-apps hit.
+app.post('/api/js-apps/refresh-categories', async (req, res) => {
+  try {
+    const apps = await getJsApps();
+    void runCategorizationBatch(apps).catch((err) => {
+      console.error('[Categorize] Manual batch crashed:', err);
+    });
+    res.json({
+      ok: true,
+      message: `Categorization batch kicked off for ${apps.length} JS apps.`,
+      stats: buildCategorizationStats(apps),
+    });
+  } catch (err) {
+    res.status(500).json({ error: 'Failed to trigger refresh' });
+  }
+});
+
 // OAuth config endpoint - expose public OAuth variables to the frontend
 // (Docker Spaces don't auto-inject window.huggingface.variables like static Spaces)
 app.get('/api/oauth-config', (req, res) => {
@@ -235,8 +495,29 @@ app.get('*', (req, res) => {
 async function warmCache() {
   console.log('[Startup] Pre-warming cache...');
   try {
-    await getApps();
+    const apps = await getApps();
     console.log('[Startup] Cache warmed successfully');
+
+    // Categorization warm-up: fire the JS-app batch in the
+    // background so the first /api/js-apps caller doesn't
+    // shoulder the cold-start cost. Order: load the dataset
+    // cache first (cheap, one HTTP call), then run the batch
+    // for stale entries only.
+    void (async () => {
+      try {
+        await categoryCache.load();
+        const jsApps = apps.filter((a) => {
+          const tags = a?.extra?.tags;
+          return Array.isArray(tags) && tags.includes(JS_APP_TAG);
+        });
+        console.log(
+          `[Startup] Found ${jsApps.length} JS apps; checking categories...`,
+        );
+        await runCategorizationBatch(jsApps);
+      } catch (err) {
+        console.error('[Startup] Categorization warm-up failed:', err);
+      }
+    })();
   } catch (err) {
     console.error('[Startup] Failed to warm cache:', err);
   }