feat: brain taxonomy — DB-backed folders/tags, sidebar, CRUD API

Backend:
- New Folder/Tag/ItemTag models with proper relational tables
- Taxonomy CRUD endpoints: list, create, rename, delete, merge tags
- Sidebar endpoint with folder/tag counts
- AI classification reads live folders/tags from DB, not hardcoded
- Default folders/tags seeded on first request per user
- folder_id FK on items for relational integrity

Frontend:
- Left sidebar with Folders/Tags tabs (like Karakeep)
- Click folder/tag to filter items
- "Manage" mode: add new folders/tags, delete existing
- Counts next to each folder/tag
- "All items" option to clear filter
- Replaces the old signal-strip cards

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

frontend-v2/src/lib/pages/brain/AtelierBrainPage.svelte

@@ -23,17 +23,25 @@
     assets: { id: string; asset_type: string; filename: string; content_type: string | null }[];
   }
 
+  interface SidebarFolder { id: string; name: string; slug: string; is_active: boolean; item_count: number; }
+  interface SidebarTag { id: string; name: string; slug: string; is_active: boolean; item_count: number; }
+
   let loading = $state(true);
   let items = $state<BrainItem[]>([]);
   let total = $state(0);
   let activeFolder = $state<string | null>(null);
+  let activeFolderId = $state<string | null>(null);
+  let activeTag = $state<string | null>(null);
+  let activeTagId = $state<string | null>(null);
   let searchQuery = $state('');
   let searching = $state(false);
-  let folders = $state<string[]>([]);
-  let tags = $state<string[]>([]);
 
-  // Filter
+  // Sidebar
-  let activeTag = $state<string | null>(null);
+  let sidebarFolders = $state<SidebarFolder[]>([]);
+  let sidebarTags = $state<SidebarTag[]>([]);
+  let sidebarView = $state<'folders' | 'tags'>('folders');
+  let showManage = $state(false);
+  let newTaxName = $state('');
 
   // Capture
   let captureInput = $state('');
@@ -46,20 +54,18 @@
   let editingNote = $state(false);
   let editNoteContent = $state('');
 
-  // Folder counts
-  let folderCounts = $state<Record<string, number>>({});
-
   async function api(path: string, opts: RequestInit = {}) {
     const res = await fetch(`/api/brain${path}`, { credentials: 'include', ...opts });
     if (!res.ok) throw new Error(`${res.status}`);
     return res.json();
   }
 
-  async function loadConfig() {
+  async function loadSidebar() {
     try {
-      const data = await api('/config');
+      const data = await api('/taxonomy/sidebar');
-      folders = data.folders || [];
+      sidebarFolders = data.folders || [];
-      tags = data.tags || [];
+      sidebarTags = data.tags || [];
+      total = data.total_items || 0;
     } catch { /* silent */ }
   }
 
@@ -72,18 +78,59 @@
       const data = await api(`/items?${params}`);
       items = data.items || [];
       total = data.total || 0;
-
-      // Count items per folder
-      const counts: Record<string, number> = {};
-      for (const item of items) {
-        const f = item.folder || 'Uncategorized';
-        counts[f] = (counts[f] || 0) + 1;
-      }
-      folderCounts = counts;
     } catch { /* silent */ }
     loading = false;
   }
 
+  async function addTaxonomy() {
+    if (!newTaxName.trim()) return;
+    try {
+      const endpoint = sidebarView === 'folders' ? '/taxonomy/folders' : '/taxonomy/tags';
+      await api(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: newTaxName.trim() }),
+      });
+      newTaxName = '';
+      await loadSidebar();
+    } catch { /* silent */ }
+  }
+
+  async function deleteTaxonomy(id: string) {
+    try {
+      const endpoint = sidebarView === 'folders' ? `/taxonomy/folders/${id}` : `/taxonomy/tags/${id}`;
+      await api(endpoint, { method: 'DELETE' });
+      await loadSidebar();
+      await loadItems();
+    } catch { /* silent */ }
+  }
+
+  function selectFolder(folder: SidebarFolder | null) {
+    if (folder) {
+      activeFolder = folder.name;
+      activeFolderId = folder.id;
+    } else {
+      activeFolder = null;
+      activeFolderId = null;
+    }
+    activeTag = null;
+    activeTagId = null;
+    loadItems();
+  }
+
+  function selectTag(tag: SidebarTag | null) {
+    if (tag) {
+      activeTag = tag.name;
+      activeTagId = tag.id;
+    } else {
+      activeTag = null;
+      activeTagId = null;
+    }
+    activeFolder = null;
+    activeFolderId = null;
+    loadItems();
+  }
+
   async function capture() {
     if (!captureInput.trim()) return;
     capturing = true;
@@ -260,7 +307,7 @@
   });
 
   onMount(async () => {
-    await loadConfig();
+    await loadSidebar();
     await loadItems();
   });
 
@@ -309,58 +356,90 @@
       {/if}
     </section>
 
-    <!-- ═══ Folder signal strip ═══ -->
+    <!-- ═══ Sidebar + Main layout ═══ -->
-    <section class="signal-strip stagger">
+    <div class="brain-layout">
-      <button class="signal-card" class:active={activeFolder === null} onclick={() => { activeFolder = null; loadItems(); }}>
+
-        <div class="signal-topline">
+      <!-- Sidebar -->
-          <div class="signal-label">All</div>
+      <aside class="brain-sidebar">
-          <div class="signal-value">{total}</div>
+        <div class="sidebar-tabs">
+          <button class="sidebar-tab" class:active={sidebarView === 'folders'} onclick={() => sidebarView = 'folders'}>Folders</button>
+          <button class="sidebar-tab" class:active={sidebarView === 'tags'} onclick={() => sidebarView = 'tags'}>Tags</button>
         </div>
-        <div class="signal-note">Everything saved across all folders.</div>
-      </button>
-      {#each folders.slice(0, 5) as folder}
-        <button class="signal-card" class:active={activeFolder === folder} onclick={() => { activeFolder = folder; loadItems(); }}>
-          <div class="signal-topline">
-            <div class="signal-label">{folder}</div>
-            <div class="signal-value">{folderCounts[folder] || 0}</div>
-          </div>
-          <div class="signal-note">Items classified under {folder.toLowerCase()}.</div>
-        </button>
-      {/each}
-    </section>
 
-    <!-- ═══ Active tag filter ═══ -->
+        <!-- All items -->
-    {#if activeTag}
+        <button class="sidebar-item" class:active={!activeFolder && !activeTag} onclick={() => { selectFolder(null); selectTag(null); }}>
-      <div class="active-filter">
+          <span class="sidebar-item-name">All items</span>
-        <span class="filter-label">Filtered by tag:</span>
+          <span class="sidebar-item-count">{total}</span>
-        <span class="filter-tag">{activeTag}</span>
-        <button class="filter-clear" onclick={() => { activeTag = null; loadItems(); }}>
-          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
-          Clear
         </button>
-      </div>
-    {/if}
 
-    <!-- ═══ Search bar ═══ -->
+        {#if sidebarView === 'folders'}
-    <section class="search-section">
+          {#each sidebarFolders.filter(f => f.is_active) as folder}
-      <div class="search-wrap">
+            <button class="sidebar-item" class:active={activeFolderId === folder.id} onclick={() => selectFolder(folder)}>
-        <svg class="search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg>
+              <span class="sidebar-item-name">{folder.name}</span>
-        <input
+              <span class="sidebar-item-count">{folder.item_count}</span>
-          type="text"
+              {#if showManage}
-          class="search-input"
+                <button class="sidebar-item-delete" onclick={(e) => { e.stopPropagation(); if (confirm(`Delete folder "${folder.name}"? Items will be moved.`)) deleteTaxonomy(folder.id); }}>
-          placeholder="Search your brain..."
+                  <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
-          bind:value={searchQuery}
+                </button>
-          oninput={handleSearchInput}
+              {/if}
-        />
+            </button>
-        {#if searchQuery}
+          {/each}
-          <button class="search-clear" onclick={() => { searchQuery = ''; loadItems(); }}>
+        {:else}
-            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+          {#each sidebarTags.filter(t => t.is_active) as tag}
-          </button>
+            <button class="sidebar-item" class:active={activeTagId === tag.id} onclick={() => selectTag(tag)}>
+              <span class="sidebar-item-name">{tag.name}</span>
+              <span class="sidebar-item-count">{tag.item_count}</span>
+              {#if showManage}
+                <button class="sidebar-item-delete" onclick={(e) => { e.stopPropagation(); if (confirm(`Delete tag "${tag.name}"?`)) deleteTaxonomy(tag.id); }}>
+                  <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+                </button>
+              {/if}
+            </button>
+          {/each}
         {/if}
-      </div>
-    </section>
 
-    <!-- ═══ Masonry card grid ═══ -->
+        <!-- Add / Manage -->
+        <div class="sidebar-actions">
+          {#if showManage}
+            <div class="sidebar-add">
+              <input class="sidebar-add-input" placeholder="New {sidebarView === 'folders' ? 'folder' : 'tag'}..." bind:value={newTaxName} onkeydown={(e) => { if (e.key === 'Enter') addTaxonomy(); }} />
+              <button class="sidebar-add-btn" onclick={addTaxonomy}>Add</button>
+            </div>
+          {/if}
+          <button class="sidebar-manage-toggle" onclick={() => showManage = !showManage}>
+            {showManage ? 'Done' : 'Manage'}
+          </button>
+        </div>
+      </aside>
+
+      <!-- Main content -->
+      <div class="brain-main">
+        <!-- Active filter indicator -->
+        {#if activeFolder || activeTag}
+          <div class="active-filter">
+            <span class="filter-label">Filtered by {activeFolder ? 'folder' : 'tag'}:</span>
+            <span class="filter-tag">{activeFolder || activeTag}</span>
+            <button class="filter-clear" onclick={() => { selectFolder(null); selectTag(null); }}>
+              <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+              Clear
+            </button>
+          </div>
+        {/if}
+
+        <!-- Search -->
+        <div class="search-section">
+          <div class="search-wrap">
+            <svg class="search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg>
+            <input type="text" class="search-input" placeholder="Search your brain..." bind:value={searchQuery} oninput={handleSearchInput} />
+            {#if searchQuery}
+              <button class="search-clear" onclick={() => { searchQuery = ''; loadItems(); }}>
+                <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+              </button>
+            {/if}
+          </div>
+        </div>
+
+        <!-- Masonry card grid -->
     {#if loading}
       <div class="masonry">
         {#each [1, 2, 3, 4, 5, 6] as _}
@@ -445,6 +524,9 @@
       </div>
     {/if}
 
+      </div><!-- .brain-main -->
+    </div><!-- .brain-layout -->
+
   </div>
 </div>
 
@@ -667,23 +749,44 @@
   }
   .capture-btn:hover { opacity: 0.9; }
 
-  /* ═══ Signal strip ═══ */
+  /* ═══ Layout: Sidebar + Main ═══ */
-  .signal-strip { display: grid; grid-template-columns: repeat(auto-fill, minmax(160px, 1fr)); gap: 12px; margin-bottom: 18px; }
+  .brain-layout { display: grid; grid-template-columns: 240px 1fr; gap: 16px; align-items: start; }
-  .signal-card {
+
-    border-radius: 28px; border: 1px solid rgba(35,26,17,0.08);
+  .brain-sidebar {
-    background: rgba(255,252,248,0.68); backdrop-filter: blur(14px);
+    position: sticky; top: 68px;
-    padding: 18px; text-align: left;
+    border-radius: 20px; border: 1px solid rgba(35,26,17,0.08);
-    transition: transform 160ms ease, background 160ms ease, border-color 160ms ease;
+    background: rgba(255,252,248,0.72); backdrop-filter: blur(14px);
+    padding: 14px; max-height: calc(100vh - 80px); overflow-y: auto;
   }
-  .signal-card:hover { transform: translateY(-2px); background: rgba(255,255,255,0.82); }
+  .sidebar-tabs { display: flex; gap: 2px; margin-bottom: 10px; background: rgba(35,26,17,0.04); border-radius: 10px; padding: 3px; }
-  .signal-card.active {
+  .sidebar-tab {
-    border-color: rgba(179,92,50,0.2);
+    flex: 1; padding: 6px 0; border-radius: 8px; font-size: 0.8rem; font-weight: 600;
-    background: linear-gradient(145deg, rgba(255,248,242,0.94), rgba(246,237,227,0.72));
+    color: #7d6f61; background: none; border: none; font-family: var(--font); transition: all 160ms;
   }
-  .signal-topline { display: flex; align-items: end; justify-content: space-between; gap: 16px; margin-bottom: 12px; }
+  .sidebar-tab.active { background: rgba(255,255,255,0.9); color: #1e1812; box-shadow: 0 1px 3px rgba(35,26,17,0.06); }
-  .signal-label { font-size: 11px; text-transform: uppercase; letter-spacing: 0.12em; color: #7d6f61; }
+
-  .signal-value { font-size: clamp(1.6rem, 3vw, 2.2rem); line-height: 0.95; letter-spacing: -0.05em; color: #1e1812; }
+  .sidebar-item {
-  .signal-note { color: #4f463d; line-height: 1.6; font-size: 0.85rem; }
+    display: flex; align-items: center; gap: 8px; width: 100%; padding: 8px 10px;
+    border-radius: 10px; border: none; background: none; font-family: var(--font);
+    font-size: 0.85rem; color: #3d342c; text-align: left; transition: all 160ms;
+  }
+  .sidebar-item:hover { background: rgba(255,255,255,0.6); }
+  .sidebar-item.active { background: linear-gradient(135deg, rgba(255,248,242,0.94), rgba(246,237,227,0.72)); color: #1e1812; font-weight: 600; }
+  .sidebar-item-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sidebar-item-count { flex-shrink: 0; font-size: 0.72rem; font-family: var(--mono); color: #8c7b69; background: rgba(35,26,17,0.04); padding: 1px 6px; border-radius: 6px; }
+  .sidebar-item-delete { flex-shrink: 0; width: 20px; height: 20px; border-radius: 6px; border: none; background: none; color: #8c7b69; display: flex; align-items: center; justify-content: center; }
+  .sidebar-item-delete:hover { background: rgba(220,38,38,0.1); color: #DC2626; }
+
+  .sidebar-actions { margin-top: 10px; padding-top: 10px; border-top: 1px solid rgba(35,26,17,0.06); display: flex; flex-direction: column; gap: 6px; }
+  .sidebar-add { display: flex; gap: 4px; }
+  .sidebar-add-input { flex: 1; padding: 6px 10px; border-radius: 8px; border: 1px solid rgba(35,26,17,0.1); background: rgba(255,255,255,0.7); font-size: 0.8rem; font-family: var(--font); color: #1e1812; outline: none; }
+  .sidebar-add-input:focus { border-color: rgba(179,92,50,0.4); }
+  .sidebar-add-input::placeholder { color: #8c7b69; }
+  .sidebar-add-btn { padding: 6px 10px; border-radius: 8px; border: none; background: #1e1812; color: white; font-size: 0.78rem; font-weight: 600; font-family: var(--font); }
+  .sidebar-manage-toggle { padding: 6px 0; border: none; background: none; font-size: 0.78rem; color: #8c7b69; font-family: var(--font); text-align: center; }
+  .sidebar-manage-toggle:hover { color: #1e1812; }
+
+  .brain-main { min-width: 0; }
 
   /* ═══ Active filter ═══ */
   .active-filter {
@@ -1113,11 +1216,13 @@
   /* ═══ Mobile ═══ */
   @media (max-width: 1100px) {
     .masonry { columns: 2; }
+    .brain-layout { grid-template-columns: 200px 1fr; }
   }
   @media (max-width: 768px) {
     .brain-command { display: grid; gap: 14px; }
     .command-actions { justify-items: start; }
-    .signal-strip { grid-template-columns: 1fr 1fr; }
+    .brain-layout { grid-template-columns: 1fr; }
+    .brain-sidebar { position: static; max-height: none; }
     .masonry { columns: 1; }
     .detail-sheet { width: 100%; padding: 20px; }
     .viewer-overlay { padding: 12px; }

services/brain/app/api/taxonomy.py

@@ -0,0 +1,334 @@
+"""Taxonomy API — folder and tag CRUD, sidebar data."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
+from sqlalchemy import select, func, update, delete
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.deps import get_user_id, get_db_session
+from app.models.taxonomy import Folder, Tag, ItemTag, slugify, ensure_user_taxonomy
+from app.models.item import Item
+
+router = APIRouter(prefix="/api/taxonomy", tags=["taxonomy"])
+
+
+# ── Schemas ──
+
+class FolderIn(BaseModel):
+    name: str
+
+class FolderOut(BaseModel):
+    id: str
+    name: str
+    slug: str
+    is_active: bool
+    sort_order: int
+    item_count: int = 0
+    model_config = {"from_attributes": True}
+
+class TagIn(BaseModel):
+    name: str
+
+class TagOut(BaseModel):
+    id: str
+    name: str
+    slug: str
+    is_active: bool
+    sort_order: int
+    item_count: int = 0
+    model_config = {"from_attributes": True}
+
+class SidebarOut(BaseModel):
+    folders: list[FolderOut]
+    tags: list[TagOut]
+    total_items: int
+
+class MergeTagIn(BaseModel):
+    source_tag_id: str
+    target_tag_id: str
+
+
+# ── Sidebar data ──
+
+@router.get("/sidebar", response_model=SidebarOut)
+async def get_sidebar(
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    await ensure_user_taxonomy(db, user_id)
+
+    # Folders with counts
+    folder_rows = (await db.execute(
+        select(Folder).where(Folder.user_id == user_id).order_by(Folder.sort_order, Folder.name)
+    )).scalars().all()
+
+    folder_counts = {}
+    for row in (await db.execute(
+        select(Item.folder_id, func.count()).where(
+            Item.user_id == user_id, Item.folder_id.isnot(None)
+        ).group_by(Item.folder_id)
+    )).all():
+        folder_counts[row[0]] = row[1]
+
+    folders = [FolderOut(
+        id=f.id, name=f.name, slug=f.slug, is_active=f.is_active,
+        sort_order=f.sort_order, item_count=folder_counts.get(f.id, 0)
+    ) for f in folder_rows]
+
+    # Tags with counts
+    tag_rows = (await db.execute(
+        select(Tag).where(Tag.user_id == user_id).order_by(Tag.sort_order, Tag.name)
+    )).scalars().all()
+
+    tag_counts = {}
+    for row in (await db.execute(
+        select(ItemTag.tag_id, func.count()).join(Item, Item.id == ItemTag.item_id).where(
+            Item.user_id == user_id
+        ).group_by(ItemTag.tag_id)
+    )).all():
+        tag_counts[row[0]] = row[1]
+
+    tags = [TagOut(
+        id=t.id, name=t.name, slug=t.slug, is_active=t.is_active,
+        sort_order=t.sort_order, item_count=tag_counts.get(t.id, 0)
+    ) for t in tag_rows]
+
+    # Total items
+    total = (await db.execute(
+        select(func.count()).where(Item.user_id == user_id)
+    )).scalar() or 0
+
+    return SidebarOut(folders=folders, tags=tags, total_items=total)
+
+
+# ── Folder CRUD ──
+
+@router.get("/folders", response_model=list[FolderOut])
+async def list_folders(
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    await ensure_user_taxonomy(db, user_id)
+    rows = (await db.execute(
+        select(Folder).where(Folder.user_id == user_id).order_by(Folder.sort_order, Folder.name)
+    )).scalars().all()
+    return [FolderOut(id=f.id, name=f.name, slug=f.slug, is_active=f.is_active, sort_order=f.sort_order) for f in rows]
+
+
+@router.post("/folders", response_model=FolderOut, status_code=201)
+async def create_folder(
+    body: FolderIn,
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    slug = slugify(body.name)
+    existing = (await db.execute(
+        select(Folder).where(Folder.user_id == user_id, Folder.slug == slug)
+    )).scalar_one_or_none()
+    if existing:
+        raise HTTPException(400, "Folder already exists")
+
+    max_order = (await db.execute(
+        select(func.max(Folder.sort_order)).where(Folder.user_id == user_id)
+    )).scalar() or 0
+
+    folder = Folder(id=str(uuid.uuid4()), user_id=user_id, name=body.name.strip(), slug=slug, sort_order=max_order + 1)
+    db.add(folder)
+    await db.commit()
+    return FolderOut(id=folder.id, name=folder.name, slug=folder.slug, is_active=folder.is_active, sort_order=folder.sort_order)
+
+
+@router.patch("/folders/{folder_id}", response_model=FolderOut)
+async def update_folder(
+    folder_id: str,
+    body: FolderIn,
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    folder = (await db.execute(
+        select(Folder).where(Folder.id == folder_id, Folder.user_id == user_id)
+    )).scalar_one_or_none()
+    if not folder:
+        raise HTTPException(404, "Folder not found")
+
+    folder.name = body.name.strip()
+    folder.slug = slugify(body.name)
+    folder.updated_at = datetime.utcnow()
+
+    # Update denormalized folder name on items
+    await db.execute(
+        update(Item).where(Item.folder_id == folder_id).values(folder=folder.name)
+    )
+    await db.commit()
+    return FolderOut(id=folder.id, name=folder.name, slug=folder.slug, is_active=folder.is_active, sort_order=folder.sort_order)
+
+
+@router.delete("/folders/{folder_id}")
+async def delete_folder(
+    folder_id: str,
+    fallback_folder_id: Optional[str] = Query(None),
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    folder = (await db.execute(
+        select(Folder).where(Folder.id == folder_id, Folder.user_id == user_id)
+    )).scalar_one_or_none()
+    if not folder:
+        raise HTTPException(404, "Folder not found")
+
+    # Move items to fallback folder or first available folder
+    if fallback_folder_id:
+        fallback = (await db.execute(select(Folder).where(Folder.id == fallback_folder_id))).scalar_one_or_none()
+    else:
+        fallback = (await db.execute(
+            select(Folder).where(Folder.user_id == user_id, Folder.id != folder_id).order_by(Folder.sort_order).limit(1)
+        )).scalar_one_or_none()
+
+    if fallback:
+        await db.execute(
+            update(Item).where(Item.folder_id == folder_id).values(folder_id=fallback.id, folder=fallback.name)
+        )
+
+    await db.execute(delete(Folder).where(Folder.id == folder_id))
+    await db.commit()
+    return {"status": "deleted", "items_moved_to": fallback.name if fallback else None}
+
+
+# ── Tag CRUD ──
+
+@router.get("/tags", response_model=list[TagOut])
+async def list_tags(
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    await ensure_user_taxonomy(db, user_id)
+    rows = (await db.execute(
+        select(Tag).where(Tag.user_id == user_id).order_by(Tag.sort_order, Tag.name)
+    )).scalars().all()
+    return [TagOut(id=t.id, name=t.name, slug=t.slug, is_active=t.is_active, sort_order=t.sort_order) for t in rows]
+
+
+@router.post("/tags", response_model=TagOut, status_code=201)
+async def create_tag(
+    body: TagIn,
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    slug = slugify(body.name)
+    existing = (await db.execute(
+        select(Tag).where(Tag.user_id == user_id, Tag.slug == slug)
+    )).scalar_one_or_none()
+    if existing:
+        raise HTTPException(400, "Tag already exists")
+
+    max_order = (await db.execute(
+        select(func.max(Tag.sort_order)).where(Tag.user_id == user_id)
+    )).scalar() or 0
+
+    tag = Tag(id=str(uuid.uuid4()), user_id=user_id, name=body.name.strip(), slug=slug, sort_order=max_order + 1)
+    db.add(tag)
+    await db.commit()
+    return TagOut(id=tag.id, name=tag.name, slug=tag.slug, is_active=tag.is_active, sort_order=tag.sort_order)
+
+
+@router.patch("/tags/{tag_id}", response_model=TagOut)
+async def update_tag(
+    tag_id: str,
+    body: TagIn,
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    tag = (await db.execute(
+        select(Tag).where(Tag.id == tag_id, Tag.user_id == user_id)
+    )).scalar_one_or_none()
+    if not tag:
+        raise HTTPException(404, "Tag not found")
+
+    old_name = tag.name
+    tag.name = body.name.strip()
+    tag.slug = slugify(body.name)
+    tag.updated_at = datetime.utcnow()
+
+    # Update denormalized tags array on items that had the old name
+    items_with_tag = (await db.execute(
+        select(Item).join(ItemTag, ItemTag.item_id == Item.id).where(ItemTag.tag_id == tag_id)
+    )).scalars().all()
+    for item in items_with_tag:
+        if item.tags and old_name in item.tags:
+            item.tags = [tag.name if t == old_name else t for t in item.tags]
+
+    await db.commit()
+    return TagOut(id=tag.id, name=tag.name, slug=tag.slug, is_active=tag.is_active, sort_order=tag.sort_order)
+
+
+@router.delete("/tags/{tag_id}")
+async def delete_tag(
+    tag_id: str,
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    tag = (await db.execute(
+        select(Tag).where(Tag.id == tag_id, Tag.user_id == user_id)
+    )).scalar_one_or_none()
+    if not tag:
+        raise HTTPException(404, "Tag not found")
+
+    # Remove tag from denormalized arrays
+    items_with_tag = (await db.execute(
+        select(Item).join(ItemTag, ItemTag.item_id == Item.id).where(ItemTag.tag_id == tag_id)
+    )).scalars().all()
+    for item in items_with_tag:
+        if item.tags and tag.name in item.tags:
+            item.tags = [t for t in item.tags if t != tag.name]
+
+    # Delete join table entries and tag
+    await db.execute(delete(ItemTag).where(ItemTag.tag_id == tag_id))
+    await db.execute(delete(Tag).where(Tag.id == tag_id))
+    await db.commit()
+    return {"status": "deleted"}
+
+
+@router.post("/tags/merge")
+async def merge_tags(
+    body: MergeTagIn,
+    user_id: str = Depends(get_user_id),
+    db: AsyncSession = Depends(get_db_session),
+):
+    """Merge source tag into target tag. All items with source get target instead."""
+    source = (await db.execute(select(Tag).where(Tag.id == body.source_tag_id, Tag.user_id == user_id))).scalar_one_or_none()
+    target = (await db.execute(select(Tag).where(Tag.id == body.target_tag_id, Tag.user_id == user_id))).scalar_one_or_none()
+    if not source or not target:
+        raise HTTPException(404, "Tag not found")
+
+    # Move item_tags from source to target (skip duplicates)
+    source_items = (await db.execute(
+        select(ItemTag.item_id).where(ItemTag.tag_id == source.id)
+    )).scalars().all()
+    target_items = set((await db.execute(
+        select(ItemTag.item_id).where(ItemTag.tag_id == target.id)
+    )).scalars().all())
+
+    for item_id in source_items:
+        if item_id not in target_items:
+            db.add(ItemTag(item_id=item_id, tag_id=target.id))
+
+    # Update denormalized tags
+    items = (await db.execute(
+        select(Item).join(ItemTag, ItemTag.item_id == Item.id).where(ItemTag.tag_id == source.id)
+    )).scalars().all()
+    for item in items:
+        if item.tags:
+            new_tags = [target.name if t == source.name else t for t in item.tags]
+            item.tags = list(dict.fromkeys(new_tags))  # dedupe
+
+    # Delete source
+    await db.execute(delete(ItemTag).where(ItemTag.tag_id == source.id))
+    await db.execute(delete(Tag).where(Tag.id == source.id))
+    await db.commit()
+    return {"status": "merged", "source": source.name, "target": target.name}

services/brain/app/main.py

@@ -6,6 +6,7 @@ from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 from app.api.routes import router
+from app.api.taxonomy import router as taxonomy_router
 from app.config import DEBUG
 
 logging.basicConfig(
@@ -23,6 +24,7 @@ app = FastAPI(
 
 # No CORS — internal service only, accessed via gateway
 app.include_router(router)
+app.include_router(taxonomy_router)
 
 
 @app.on_event("startup")
@@ -30,6 +32,7 @@ async def startup():
     from sqlalchemy import text as sa_text
     from app.database import engine, Base
     from app.models.item import Item, ItemAsset, AppLink  # noqa: import to register models
+    from app.models.taxonomy import Folder, Tag, ItemTag  # noqa: register taxonomy tables
 
     # Enable pgvector extension before creating tables
     async with engine.begin() as conn:

services/brain/app/models/item.py

@@ -28,8 +28,9 @@ class Item(Base):
     url = Column(Text, nullable=True)
     raw_content = Column(Text, nullable=True)       # original user input (note body, etc.)
     extracted_text = Column(Text, nullable=True)     # full extracted text from page/doc
-    folder = Column(String(64), nullable=True)
+    folder_id = Column(UUID(as_uuid=False), ForeignKey("folders.id", ondelete="SET NULL"), nullable=True)
-    tags = Column(ARRAY(String), nullable=True, default=list)
+    folder = Column(String(64), nullable=True)       # denormalized folder name for fast reads
+    tags = Column(ARRAY(String), nullable=True, default=list)  # denormalized tag names for fast reads
     summary = Column(Text, nullable=True)
     confidence = Column(Float, nullable=True)
     metadata_json = Column(JSONB, nullable=True, default=dict)

services/brain/app/models/taxonomy.py

@@ -0,0 +1,103 @@
+"""Database models for folders and tags — editable taxonomy."""
+
+import re
+import uuid
+from datetime import datetime
+
+from sqlalchemy import Column, String, Integer, Boolean, DateTime, ForeignKey, Index, UniqueConstraint
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from app.database import Base
+
+
+def new_id():
+    return str(uuid.uuid4())
+
+
+def slugify(text: str) -> str:
+    s = text.lower().strip()
+    s = re.sub(r'[^\w\s-]', '', s)
+    s = re.sub(r'[\s_]+', '-', s)
+    return s.strip('-')
+
+
+class Folder(Base):
+    __tablename__ = "folders"
+
+    id = Column(UUID(as_uuid=False), primary_key=True, default=new_id)
+    user_id = Column(String(64), nullable=False, index=True)
+    name = Column(String(128), nullable=False)
+    slug = Column(String(128), nullable=False)
+    is_active = Column(Boolean, default=True, nullable=False)
+    sort_order = Column(Integer, default=0, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint('user_id', 'slug', name='uq_folder_user_slug'),
+    )
+
+
+class Tag(Base):
+    __tablename__ = "tags"
+
+    id = Column(UUID(as_uuid=False), primary_key=True, default=new_id)
+    user_id = Column(String(64), nullable=False, index=True)
+    name = Column(String(128), nullable=False)
+    slug = Column(String(128), nullable=False)
+    is_active = Column(Boolean, default=True, nullable=False)
+    sort_order = Column(Integer, default=0, nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow, nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint('user_id', 'slug', name='uq_tag_user_slug'),
+    )
+
+
+class ItemTag(Base):
+    __tablename__ = "item_tags"
+
+    item_id = Column(UUID(as_uuid=False), ForeignKey("items.id", ondelete="CASCADE"), primary_key=True)
+    tag_id = Column(UUID(as_uuid=False), ForeignKey("tags.id", ondelete="CASCADE"), primary_key=True)
+    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
+
+
+# Default folders to seed for new users
+DEFAULT_FOLDERS = ["Home", "Family", "Work", "Travel", "Knowledge", "Faith", "Projects"]
+
+# Default tags to seed for new users
+DEFAULT_TAGS = [
+    "reference", "important", "legal", "financial", "insurance",
+    "research", "idea", "guide", "tutorial", "setup", "how-to",
+    "tools", "dev", "server", "selfhosted", "home-assistant",
+    "shopping", "compare", "buy", "product",
+    "family", "kids", "health", "travel", "faith",
+    "video", "read-later", "books",
+]
+
+
+async def ensure_user_taxonomy(db, user_id: str):
+    """Seed default folders and tags for a new user if they have none."""
+    from sqlalchemy import select, func
+
+    folder_count = (await db.execute(
+        select(func.count()).where(Folder.user_id == user_id)
+    )).scalar() or 0
+
+    if folder_count == 0:
+        for i, name in enumerate(DEFAULT_FOLDERS):
+            db.add(Folder(id=new_id(), user_id=user_id, name=name, slug=slugify(name), sort_order=i))
+        await db.flush()
+
+    tag_count = (await db.execute(
+        select(func.count()).where(Tag.user_id == user_id)
+    )).scalar() or 0
+
+    if tag_count == 0:
+        for i, name in enumerate(DEFAULT_TAGS):
+            db.add(Tag(id=new_id(), user_id=user_id, name=name, slug=slugify(name), sort_order=i))
+        await db.flush()
+
+    await db.commit()

services/brain/app/services/classify.py

@@ -5,15 +5,17 @@ import logging
 
 import httpx
 
-from app.config import OPENAI_API_KEY, OPENAI_MODEL, FOLDERS, TAGS
+from app.config import OPENAI_API_KEY, OPENAI_MODEL
 
 log = logging.getLogger(__name__)
 
-SYSTEM_PROMPT = f"""You are a classification engine for a personal "second brain" knowledge management system.
+
+def build_system_prompt(folders: list[str], tags: list[str]) -> str:
+    return f"""You are a classification engine for a personal "second brain" knowledge management system.
 
 Given an item (URL, note, document, or file), you must return structured JSON with:
-- folder: exactly 1 from this list: {json.dumps(FOLDERS)}
+- folder: exactly 1 from this list: {json.dumps(folders)}
-- tags: exactly 2 or 3 from this list: {json.dumps(TAGS)}
+- tags: exactly 2 or 3 from this list: {json.dumps(tags)}
 - title: a concise, normalized title (max 80 chars)
 - summary: a 1-2 sentence summary of the content (for links/documents only)
 - corrected_text: for NOTES ONLY — return the original note text with spelling/grammar fixed. Keep the original meaning, tone, and structure. Only fix typos and obvious errors. Return empty string for non-notes.
@@ -27,7 +29,9 @@ Rules:
 - For notes: the summary field should be a very short 5-10 word description, not a rewrite.
 - Always return valid JSON matching the schema exactly"""
 
-RESPONSE_SCHEMA = {
+
+def build_response_schema(folders: list[str], tags: list[str]) -> dict:
+    return {
     "type": "json_schema",
     "json_schema": {
         "name": "classification",
@@ -35,10 +39,10 @@ RESPONSE_SCHEMA = {
         "schema": {
             "type": "object",
             "properties": {
-                "folder": {"type": "string", "enum": FOLDERS},
+                "folder": {"type": "string", "enum": folders},
                 "tags": {
                     "type": "array",
-                    "items": {"type": "string", "enum": TAGS},
+                    "items": {"type": "string", "enum": tags},
                     "minItems": 2,
                     "maxItems": 3,
                 },
@@ -72,9 +76,15 @@ async def classify_item(
     url: str | None = None,
     title: str | None = None,
     text: str | None = None,
+    folders: list[str] | None = None,
+    tags: list[str] | None = None,
     retries: int = 2,
 ) -> dict:
     """Call OpenAI to classify an item. Returns dict with folder, tags, title, summary, confidence."""
+    from app.config import FOLDERS, TAGS
+    folders = folders or FOLDERS
+    tags = tags or TAGS
+
     if not OPENAI_API_KEY:
         log.warning("No OPENAI_API_KEY set, returning defaults")
         return {
@@ -86,6 +96,8 @@ async def classify_item(
         }
 
     user_msg = build_user_prompt(item_type, url, title, text)
+    system_prompt = build_system_prompt(folders, tags)
+    response_schema = build_response_schema(folders, tags)
 
     for attempt in range(retries + 1):
         try:
@@ -96,10 +108,10 @@ async def classify_item(
                     json={
                         "model": OPENAI_MODEL,
                         "messages": [
-                            {"role": "system", "content": SYSTEM_PROMPT},
+                            {"role": "system", "content": system_prompt},
                             {"role": "user", "content": user_msg},
                         ],
-                        "response_format": RESPONSE_SCHEMA,
+                        "response_format": response_schema,
                         "temperature": 0.2,
                     },
                 )
@@ -109,9 +121,9 @@ async def classify_item(
                 result = json.loads(content)
 
                 # Validate folder and tags are in allowed sets
-                if result["folder"] not in FOLDERS:
+                if result["folder"] not in folders:
-                    result["folder"] = "Knowledge"
+                    result["folder"] = folders[0] if folders else "Knowledge"
-                result["tags"] = [t for t in result["tags"] if t in TAGS][:3]
+                result["tags"] = [t for t in result["tags"] if t in tags][:3]
                 if len(result["tags"]) < 2:
                     result["tags"] = (result["tags"] + ["reference", "read-later"])[:3]
 

services/brain/app/worker/tasks.py

@@ -159,18 +159,53 @@ async def _process_item(item_id: str):
                     if result.get("page_count"):
                         item.metadata_json["page_count"] = result["page_count"]
 
-            # ── Step 2: AI classification ──
+            # ── Step 2: Fetch live taxonomy from DB ──
-            log.info(f"Classifying item {item.id}")
+            from app.models.taxonomy import Folder as FolderModel, Tag as TagModel, ItemTag, ensure_user_taxonomy
+            await ensure_user_taxonomy(db, item.user_id)
+
+            active_folders = (await db.execute(
+                select(FolderModel).where(FolderModel.user_id == item.user_id, FolderModel.is_active == True)
+                .order_by(FolderModel.sort_order)
+            )).scalars().all()
+            active_tags = (await db.execute(
+                select(TagModel).where(TagModel.user_id == item.user_id, TagModel.is_active == True)
+                .order_by(TagModel.sort_order)
+            )).scalars().all()
+
+            folder_names = [f.name for f in active_folders]
+            tag_names = [t.name for t in active_tags]
+            folder_map = {f.name: f for f in active_folders}
+            tag_map = {t.name: t for t in active_tags}
+
+            # ── Step 3: AI classification ──
+            log.info(f"Classifying item {item.id} with {len(folder_names)} folders, {len(tag_names)} tags")
             classification = await classify_item(
                 item_type=item.type,
                 url=item.url,
                 title=title,
                 text=extracted_text,
+                folders=folder_names,
+                tags=tag_names,
             )
 
             item.title = classification.get("title") or title or "Untitled"
-            item.folder = classification.get("folder", "Knowledge")
+
-            item.tags = classification.get("tags", ["reference", "read-later"])
+            # Set folder (relational + denormalized)
+            classified_folder = classification.get("folder", folder_names[0] if folder_names else "Knowledge")
+            item.folder = classified_folder
+            if classified_folder in folder_map:
+                item.folder_id = folder_map[classified_folder].id
+
+            # Set tags (relational + denormalized)
+            classified_tags = classification.get("tags", [])
+            item.tags = classified_tags
+
+            # Clear old item_tags and create new ones
+            from sqlalchemy import delete as sa_delete
+            await db.execute(sa_delete(ItemTag).where(ItemTag.item_id == item.id))
+            for tag_name in classified_tags:
+                if tag_name in tag_map:
+                    db.add(ItemTag(item_id=item.id, tag_id=tag_map[tag_name].id))
 
             # For notes: replace raw_content with spell-corrected version
             corrected = classification.get("corrected_text", "")