1. Add New Topic Category

Purpose: Add a new root, subcategory, or depth-3 detail category to the taxonomy, propagate to all dependent tables, and seed entries.

Prerequisites:

  • Supabase credentials (for migration and type generation)
  • Understanding of current taxonomy (run Test Taxonomy Categories first to verify)

Cost / Duration: $0 (migration only) | 10-15 minutes

Hierarchy Levels

DepthRoleExampleSchema Source
0RootsportsOwn schema (e.g., sports_fact)
1BranchbasketballInherits root or has own schema
2Leafnba-legends-historyInherits parent, may have extensions
3Detailall-star-recordsInherits parent (+ optional 2-key extension)

Prompt

Add a new topic category to the Eko taxonomy.

I need to add:
- **Category name:** [specify]
- **Depth:** 0 (root) / 1 (branch) / 2 (leaf) / 3 (detail)?
- **Parent:** [parent slug, required for depth 1-3]
- **Description:** [brief description of the topic scope]

Steps to execute:

1. **Write the migration SQL:**

   For a **root category** (depth 0), insert into:
   - `topic_categories` (slug, name, depth=0, path=slug, icon, color, quota)
   - `fact_record_schemas` (domain-specific schema with fact_keys JSONB array)
   - `topic_category_aliases` (any alternate names/abbreviations)

   For a **subcategory** (depth 1-3), insert into:
   - `topic_categories` only — the trigger `fn_inherit_parent_schema_and_formats`
     auto-copies parent schema on INSERT.

   ```sql
   -- Subcategory pattern (depth 1-3):
   INSERT INTO topic_categories (slug, name, parent_id, depth, path)
   VALUES ('my-subcategory', 'My Subcategory',
     (SELECT id FROM topic_categories WHERE slug = 'parent-slug'),
     2, 'root/parent/my-subcategory')
   ON CONFLICT (slug) DO NOTHING;
   ```

   For **schema extensions** (enriching inherited schemas):
   ```sql
   UPDATE fact_record_schemas
   SET fact_keys = fact_keys || '[
     {"key": "extra_field", "label": "Extra Field", "type": "text", "required": false}
   ]'::jsonb
   WHERE topic_category_id = (SELECT id FROM topic_categories WHERE slug = 'my-subcategory');
   ```

2. **Apply the migration:**
   Use the Supabase MCP `apply_migration` tool, or create a local
   migration file in `supabase/migrations/`.

3. **Regenerate migrations index:**
   ```bash
   bun run migrations:index
   ```

4. **Update seed configuration** (for new roots or branches):
   - Add a `CategorySpec` to `packages/ai/src/config/categories.ts`
   - Add keyword patterns to `scripts/seed/lib/category-mapper.ts` PATH_CATEGORY_MAP
   - Generate seed entries:
     ```bash
     bun scripts/seed/generate-curated-entries.ts --category [slug] --insert
     ```

5. **Verify the new category appears:**
   Query `getActiveTopicCategories()` from
   `packages/db/src/drizzle/fact-engine-queries.ts` and confirm
   the new category is present with its schema.

Key schema reference: `packages/db/src/drizzle/schema.ts`
Taxonomy rules: `packages/ai/src/taxonomy-content-rules.ts`

Verification

  • Migration applied successfully
  • bun run migrations:index passes
  • bun run migrations:check passes
  • New category appears in getActiveTopicCategories() results
  • Schema assigned (inherited via trigger or explicitly set)
  • For roots: fact_record_schemas entry exists with domain-specific keys
  • For roots: CategorySpec added to categories.ts
  • For roots: PATH_CATEGORY_MAP entries added to category-mapper.ts
  • Taxonomy drift tests still pass (Test Taxonomy Categories)

Back to index