From 610fce8db3532cefc6b452346faf479a8a3776d1 Mon Sep 17 00:00:00 2001
From: francy51 <francesco12382@gmail.com>
Date: Tue, 3 Mar 2026 23:10:08 -0500
Subject: [PATCH] Add category and tags granularity to company sync flows

---
 app/analysis/page.tsx                         |  15 +++
 app/filings/page.tsx                          |  36 +++++-
 app/watchlist/page.tsx                        |  75 ++++++++++--
 drizzle/0004_watchlist_company_taxonomy.sql   |   3 +
 drizzle/meta/_journal.json                    |   7 ++
 lib/api.ts                                    |  15 ++-
 lib/server/api/app.ts                         | 107 +++++++++++++++---
 .../api/task-workflow-hybrid.e2e.test.ts      |  77 ++++++++++++-
 lib/server/db/schema.ts                       |   2 +
 lib/server/repos/watchlist.ts                 |  56 ++++++++-
 lib/server/task-processors.ts                 |  47 +++++++-
 lib/types.ts                                  |   4 +
 12 files changed, 415 insertions(+), 29 deletions(-)
 create mode 100644 drizzle/0004_watchlist_company_taxonomy.sql

diff --git a/app/analysis/page.tsx b/app/analysis/page.tsx
index 8e0e8db..3cf88a5 100644
--- a/app/analysis/page.tsx
+++ b/app/analysis/page.tsx
@@ -275,6 +275,21 @@ function AnalysisPageContent() {
           <p className="text-xl font-semibold text-[color:var(--terminal-bright)]">{analysis?.company.companyName ?? ticker}</p>
           <p className="mt-1 text-xs uppercase tracking-[0.16em] text-[color:var(--terminal-muted)]">{analysis?.company.ticker ?? ticker}</p>
           <p className="mt-2 text-sm text-[color:var(--terminal-muted)]">{analysis?.company.sector ?? 'Sector unavailable'}</p>
+          {analysis?.company.category ? (
+            <p className="mt-1 text-xs uppercase tracking-[0.16em] text-[color:var(--terminal-muted)]">{analysis.company.category}</p>
+          ) : null}
+          {analysis?.company.tags.length ? (
+            <div className="mt-2 flex flex-wrap gap-1">
+              {analysis.company.tags.map((tag) => (
+                <span
+                  key={tag}
+                  className="rounded border border-[color:var(--line-weak)] px-1.5 py-0.5 text-[10px] uppercase tracking-[0.12em] text-[color:var(--terminal-muted)]"
+                >
+                  {tag}
+                </span>
+              ))}
+            </div>
+          ) : null}
         </Panel>
 
         <Panel title="Live Price">
diff --git a/app/filings/page.tsx b/app/filings/page.tsx
index 6da6e94..084e729 100644
--- a/app/filings/page.tsx
+++ b/app/filings/page.tsx
@@ -47,6 +47,21 @@ function hasFinancialSnapshot(filing: Filing) {
   return filing.filing_type === '10-K' || filing.filing_type === '10-Q';
 }
 
+function parseTagsInput(input: string) {
+  const unique = new Set<string>();
+
+  for (const segment of input.split(',')) {
+    const tag = segment.trim();
+    if (!tag) {
+      continue;
+    }
+
+    unique.add(tag);
+  }
+
+  return [...unique];
+}
+
 function asScaledFinancialSnapshot(
   value: number | null | undefined,
   scale: NumberScaleUnit
@@ -111,6 +126,8 @@ function FilingsPageContent() {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [syncTickerInput, setSyncTickerInput] = useState('');
+  const [syncCategoryInput, setSyncCategoryInput] = useState('');
+  const [syncTagsInput, setSyncTagsInput] = useState('');
   const [filterTickerInput, setFilterTickerInput] = useState('');
   const [searchTicker, setSearchTicker] = useState('');
   const [financialValueScale, setFinancialValueScale] = useState<NumberScaleUnit>('millions');
@@ -156,7 +173,12 @@ function FilingsPageContent() {
     }
 
     try {
-      await queueFilingSync({ ticker: syncTickerInput.trim().toUpperCase(), limit: 20 });
+      await queueFilingSync({
+        ticker: syncTickerInput.trim().toUpperCase(),
+        limit: 20,
+        category: syncCategoryInput.trim() || undefined,
+        tags: parseTagsInput(syncTagsInput)
+      });
       void queryClient.invalidateQueries({ queryKey: queryKeys.recentTasks(20) });
       void queryClient.invalidateQueries({ queryKey: ['filings'] });
       await loadFilings(searchTicker || undefined);
@@ -227,6 +249,18 @@ function FilingsPageContent() {
               placeholder="Ticker (AAPL)"
               className="w-full sm:max-w-xs"
             />
+            <Input
+              value={syncCategoryInput}
+              onChange={(event) => setSyncCategoryInput(event.target.value)}
+              placeholder="Category (optional)"
+              className="w-full sm:max-w-xs"
+            />
+            <Input
+              value={syncTagsInput}
+              onChange={(event) => setSyncTagsInput(event.target.value)}
+              placeholder="Tags (comma-separated)"
+              className="w-full sm:max-w-xs"
+            />
             <Button type="submit" className="w-full sm:w-auto">
               <Download className="size-4" />
               Queue sync
diff --git a/app/watchlist/page.tsx b/app/watchlist/page.tsx
index 0739ba3..f19575c 100644
--- a/app/watchlist/page.tsx
+++ b/app/watchlist/page.tsx
@@ -19,8 +19,25 @@ type FormState = {
   ticker: string;
   companyName: string;
   sector: string;
+  category: string;
+  tags: string;
 };
 
+function parseTagsInput(input: string) {
+  const unique = new Set<string>();
+
+  for (const segment of input.split(',')) {
+    const tag = segment.trim();
+    if (!tag) {
+      continue;
+    }
+
+    unique.add(tag);
+  }
+
+  return [...unique];
+}
+
 export default function WatchlistPage() {
   const { isPending, isAuthenticated } = useAuthGuard();
   const queryClient = useQueryClient();
@@ -29,7 +46,13 @@ export default function WatchlistPage() {
   const [items, setItems] = useState<WatchlistItem[]>([]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
-  const [form, setForm] = useState<FormState>({ ticker: '', companyName: '', sector: '' });
+  const [form, setForm] = useState<FormState>({
+    ticker: '',
+    companyName: '',
+    sector: '',
+    category: '',
+    tags: ''
+  });
 
   const loadWatchlist = useCallback(async () => {
     const options = watchlistQueryOptions();
@@ -63,10 +86,18 @@ export default function WatchlistPage() {
       await upsertWatchlistItem({
         ticker: form.ticker.toUpperCase(),
         companyName: form.companyName,
-        sector: form.sector || undefined
+        sector: form.sector || undefined,
+        category: form.category || undefined,
+        tags: parseTagsInput(form.tags)
       });
 
-      setForm({ ticker: '', companyName: '', sector: '' });
+      setForm({
+        ticker: '',
+        companyName: '',
+        sector: '',
+        category: '',
+        tags: ''
+      });
       void queryClient.invalidateQueries({ queryKey: queryKeys.watchlist() });
       await loadWatchlist();
     } catch (err) {
@@ -74,13 +105,18 @@ export default function WatchlistPage() {
     }
   };
 
-  const queueSync = async (ticker: string) => {
+  const queueSync = async (item: WatchlistItem) => {
     try {
-      await queueFilingSync({ ticker, limit: 20 });
+      await queueFilingSync({
+        ticker: item.ticker,
+        limit: 20,
+        category: item.category ?? undefined,
+        tags: item.tags.length > 0 ? item.tags : undefined
+      });
       void queryClient.invalidateQueries({ queryKey: queryKeys.recentTasks(20) });
       void queryClient.invalidateQueries({ queryKey: ['filings'] });
     } catch (err) {
-      setError(err instanceof Error ? err.message : `Failed to queue sync for ${ticker}`);
+      setError(err instanceof Error ? err.message : `Failed to queue sync for ${item.ticker}`);
     }
   };
 
@@ -106,15 +142,30 @@ export default function WatchlistPage() {
                 <article key={item.id} className="rounded-xl border border-[color:var(--line-weak)] bg-[color:var(--panel-soft)] p-4">
                   <div className="flex items-start justify-between gap-3">
                     <div>
-                      <p className="text-xs uppercase tracking-[0.2em] text-[color:var(--terminal-muted)]">{item.sector ?? 'Unclassified'}</p>
+                      <p className="text-xs uppercase tracking-[0.2em] text-[color:var(--terminal-muted)]">
+                        {item.sector ?? 'Unclassified'}
+                        {item.category ? ` · ${item.category}` : ''}
+                      </p>
                       <h3 className="mt-1 text-xl font-semibold text-[color:var(--terminal-bright)]">{item.ticker}</h3>
                       <p className="mt-1 text-sm text-[color:var(--terminal-muted)]">{item.company_name}</p>
+                      {item.tags.length > 0 ? (
+                        <div className="mt-2 flex flex-wrap gap-1">
+                          {item.tags.map((tag) => (
+                            <span
+                              key={`${item.id}-${tag}`}
+                              className="rounded border border-[color:var(--line-weak)] bg-[color:var(--panel-soft)] px-1.5 py-0.5 text-[10px] uppercase tracking-[0.12em] text-[color:var(--terminal-muted)]"
+                            >
+                              {tag}
+                            </span>
+                          ))}
+                        </div>
+                      ) : null}
                     </div>
                     <Eye className="size-4 text-[color:var(--accent)]" />
                   </div>
 
                   <div className="mt-4 flex flex-wrap items-center gap-2">
-                    <Button variant="secondary" className="px-2 py-1 text-xs" onClick={() => void queueSync(item.ticker)}>
+                    <Button variant="secondary" className="px-2 py-1 text-xs" onClick={() => void queueSync(item)}>
                       Sync filings
                     </Button>
                     <Link
@@ -172,6 +223,14 @@ export default function WatchlistPage() {
               <label className="mb-1 block text-xs uppercase tracking-[0.2em] text-[color:var(--terminal-muted)]">Sector</label>
               <Input value={form.sector} onChange={(event) => setForm((prev) => ({ ...prev, sector: event.target.value }))} />
             </div>
+            <div>
+              <label className="mb-1 block text-xs uppercase tracking-[0.2em] text-[color:var(--terminal-muted)]">Category</label>
+              <Input value={form.category} onChange={(event) => setForm((prev) => ({ ...prev, category: event.target.value }))} placeholder="e.g. Core, Speculative, Watch only" />
+            </div>
+            <div>
+              <label className="mb-1 block text-xs uppercase tracking-[0.2em] text-[color:var(--terminal-muted)]">Tags</label>
+              <Input value={form.tags} onChange={(event) => setForm((prev) => ({ ...prev, tags: event.target.value }))} placeholder="Comma-separated tags" />
+            </div>
             <Button type="submit" className="w-full">
               <Plus className="size-4" />
               Save symbol
diff --git a/drizzle/0004_watchlist_company_taxonomy.sql b/drizzle/0004_watchlist_company_taxonomy.sql
new file mode 100644
index 0000000..1befcbe
--- /dev/null
+++ b/drizzle/0004_watchlist_company_taxonomy.sql
@@ -0,0 +1,3 @@
+ALTER TABLE `watchlist_item` ADD `category` text;
+--> statement-breakpoint
+ALTER TABLE `watchlist_item` ADD `tags` text;
diff --git a/drizzle/meta/_journal.json b/drizzle/meta/_journal.json
index 9c20f18..04c4830 100644
--- a/drizzle/meta/_journal.json
+++ b/drizzle/meta/_journal.json
@@ -29,6 +29,13 @@
       "when": 1772486100000,
       "tag": "0003_task_stage_event_timeline",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "6",
+      "when": 1772568000000,
+      "tag": "0004_watchlist_company_taxonomy",
+      "breakpoints": true
     }
   ]
 }
diff --git a/lib/api.ts b/lib/api.ts
index dfec448..c1ba561 100644
--- a/lib/api.ts
+++ b/lib/api.ts
@@ -110,7 +110,13 @@ export async function listWatchlist() {
   return await unwrapData<{ items: WatchlistItem[] }>(result, 'Unable to fetch watchlist');
 }
 
-export async function upsertWatchlistItem(input: { ticker: string; companyName: string; sector?: string }) {
+export async function upsertWatchlistItem(input: {
+  ticker: string;
+  companyName: string;
+  sector?: string;
+  category?: string;
+  tags?: string[];
+}) {
   const result = await client.api.watchlist.post(input);
   return await unwrapData<{ item: WatchlistItem }>(result, 'Unable to save watchlist item');
 }
@@ -231,7 +237,12 @@ export async function getCompanyAiReport(accessionNumber: string) {
   return await unwrapData<{ report: CompanyAiReportDetail }>(result, 'Unable to fetch AI summary');
 }
 
-export async function queueFilingSync(input: { ticker: string; limit?: number }) {
+export async function queueFilingSync(input: {
+  ticker: string;
+  limit?: number;
+  category?: string;
+  tags?: string[];
+}) {
   const result = await client.api.filings.sync.post(input);
   return await unwrapData<{ task: Task }>(result, 'Unable to queue filing sync');
 }
diff --git a/lib/server/api/app.ts b/lib/server/api/app.ts
index 900aa89..fe22f84 100644
--- a/lib/server/api/app.ts
+++ b/lib/server/api/app.ts
@@ -26,6 +26,7 @@ import {
 import { getLatestPortfolioInsight } from '@/lib/server/repos/insights';
 import {
   deleteWatchlistItemRecord,
+  getWatchlistItemByTicker,
   listWatchlistItems,
   upsertWatchlistItemRecord
 } from '@/lib/server/repos/watchlist';
@@ -86,6 +87,39 @@ function asBoolean(value: unknown, fallback = false) {
   return fallback;
 }
 
+function asOptionalString(value: unknown) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function asTags(value: unknown) {
+  const source = Array.isArray(value)
+    ? value
+    : typeof value === 'string'
+      ? value.split(',')
+      : [];
+
+  const unique = new Set<string>();
+  for (const entry of source) {
+    if (typeof entry !== 'string') {
+      continue;
+    }
+
+    const tag = entry.trim();
+    if (!tag) {
+      continue;
+    }
+
+    unique.add(tag);
+  }
+
+  return [...unique];
+}
+
 function asStatementMode(value: unknown): FinancialStatementMode {
   return FINANCIAL_STATEMENT_MODES.includes(value as FinancialStatementMode)
     ? value as FinancialStatementMode
@@ -115,15 +149,38 @@ function withFinancialMetricsPolicy(filing: Filing): Filing {
   };
 }
 
-async function queueAutoFilingSync(userId: string, ticker: string) {
+function buildSyncFilingsPayload(input: {
+  ticker: string;
+  limit: number;
+  category?: unknown;
+  tags?: unknown;
+}) {
+  const category = asOptionalString(input.category);
+  const tags = asTags(input.tags);
+
+  return {
+    ticker: input.ticker,
+    limit: input.limit,
+    ...(category ? { category } : {}),
+    ...(tags.length > 0 ? { tags } : {})
+  };
+}
+
+async function queueAutoFilingSync(
+  userId: string,
+  ticker: string,
+  metadata?: { category?: unknown; tags?: unknown }
+) {
   try {
     await enqueueTask({
       userId,
       taskType: 'sync_filings',
-      payload: {
+      payload: buildSyncFilingsPayload({
         ticker,
-        limit: AUTO_FILING_SYNC_LIMIT
-      },
+        limit: AUTO_FILING_SYNC_LIMIT,
+        category: metadata?.category,
+        tags: metadata?.tags
+      }),
       priority: 90,
       resourceKey: `sync_filings:${ticker}`
     });
@@ -228,7 +285,9 @@ export const app = new Elysia({ prefix: '/api' })
     const payload = asRecord(body);
     const ticker = typeof payload.ticker === 'string' ? payload.ticker.trim().toUpperCase() : '';
     const companyName = typeof payload.companyName === 'string' ? payload.companyName.trim() : '';
-    const sector = typeof payload.sector === 'string' ? payload.sector.trim() : '';
+    const sector = asOptionalString(payload.sector) ?? '';
+    const category = asOptionalString(payload.category) ?? '';
+    const tags = asTags(payload.tags);
 
     if (!ticker) {
       return jsonError('ticker is required');
@@ -243,11 +302,16 @@ export const app = new Elysia({ prefix: '/api' })
         userId: session.user.id,
         ticker,
         companyName,
-        sector
+        sector,
+        category,
+        tags
       });
 
       const autoFilingSyncQueued = created
-        ? await queueAutoFilingSync(session.user.id, ticker)
+        ? await queueAutoFilingSync(session.user.id, ticker, {
+          category: item.category,
+          tags: item.tags
+        })
         : false;
 
       return Response.json({ item, autoFilingSyncQueued });
@@ -258,7 +322,9 @@ export const app = new Elysia({ prefix: '/api' })
     body: t.Object({
       ticker: t.String({ minLength: 1 }),
       companyName: t.String({ minLength: 1 }),
-      sector: t.Optional(t.String())
+      sector: t.Optional(t.String()),
+      category: t.Optional(t.String()),
+      tags: t.Optional(t.Union([t.Array(t.String()), t.String()]))
     })
   })
   .delete('/watchlist/:id', async ({ params }) => {
@@ -524,6 +590,8 @@ export const app = new Elysia({ prefix: '/api' })
           ticker,
           companyName,
           sector: watchlistItem?.sector ?? null,
+          category: watchlistItem?.category ?? null,
+          tags: watchlistItem?.tags ?? [],
           cik: latestFiling?.cik ?? null
         },
         quote: liveQuote,
@@ -588,13 +656,16 @@ export const app = new Elysia({ prefix: '/api' })
 
     if (shouldQueueSync) {
       try {
+        const watchlistItem = await getWatchlistItemByTicker(session.user.id, ticker);
         await enqueueTask({
           userId: session.user.id,
           taskType: 'sync_filings',
-          payload: {
+          payload: buildSyncFilingsPayload({
             ticker,
-            limit: defaultFinancialSyncLimit(window)
-          },
+            limit: defaultFinancialSyncLimit(window),
+            category: watchlistItem?.category,
+            tags: watchlistItem?.tags
+          }),
           priority: 88,
           resourceKey: `sync_filings:${ticker}`
         });
@@ -707,6 +778,8 @@ export const app = new Elysia({ prefix: '/api' })
 
     const payload = asRecord(body);
     const ticker = typeof payload.ticker === 'string' ? payload.ticker.trim().toUpperCase() : '';
+    const category = asOptionalString(payload.category);
+    const tags = asTags(payload.tags);
 
     if (!ticker) {
       return jsonError('ticker is required');
@@ -717,10 +790,12 @@ export const app = new Elysia({ prefix: '/api' })
       const task = await enqueueTask({
         userId: session.user.id,
         taskType: 'sync_filings',
-        payload: {
+        payload: buildSyncFilingsPayload({
           ticker,
-          limit: Number.isFinite(limit) ? limit : 20
-        },
+          limit: Number.isFinite(limit) ? limit : 20,
+          category,
+          tags
+        }),
         priority: 90,
         resourceKey: `sync_filings:${ticker}`
       });
@@ -732,7 +807,9 @@ export const app = new Elysia({ prefix: '/api' })
   }, {
     body: t.Object({
       ticker: t.String({ minLength: 1 }),
-      limit: t.Optional(t.Numeric())
+      limit: t.Optional(t.Numeric()),
+      category: t.Optional(t.String()),
+      tags: t.Optional(t.Union([t.Array(t.String()), t.String()]))
     })
   })
   .post('/filings/:accessionNumber/analyze', async ({ params }) => {
diff --git a/lib/server/api/task-workflow-hybrid.e2e.test.ts b/lib/server/api/task-workflow-hybrid.e2e.test.ts
index bc8501c..e1ebd10 100644
--- a/lib/server/api/task-workflow-hybrid.e2e.test.ts
+++ b/lib/server/api/task-workflow-hybrid.e2e.test.ts
@@ -85,7 +85,8 @@ function applySqlMigrations(client: { exec: (query: string) => void }) {
     '0000_cold_silver_centurion.sql',
     '0001_glossy_statement_snapshots.sql',
     '0002_workflow_task_projection_metadata.sql',
-    '0003_task_stage_event_timeline.sql'
+    '0003_task_stage_event_timeline.sql',
+    '0004_watchlist_company_taxonomy.sql'
   ];
 
   for (const file of migrationFiles) {
@@ -215,6 +216,80 @@ if (process.env.RUN_TASK_WORKFLOW_E2E === '1') {
     expect(tasks.every((task) => typeof task.workflow_run_id === 'string' && task.workflow_run_id.length > 0)).toBe(true);
   });
 
+  it('persists watchlist category and tags and forwards them to auto sync task payload', async () => {
+    const created = await jsonRequest('POST', '/api/watchlist', {
+      ticker: 'shop',
+      companyName: 'Shopify Inc.',
+      sector: 'Technology',
+      category: 'core',
+      tags: ['growth', 'ecommerce', 'growth', '  ']
+    });
+
+    expect(created.response.status).toBe(200);
+    const createdBody = created.json as {
+      item: {
+        ticker: string;
+        category: string | null;
+        tags: string[];
+      };
+      autoFilingSyncQueued: boolean;
+    };
+
+    expect(createdBody.item.ticker).toBe('SHOP');
+    expect(createdBody.item.category).toBe('core');
+    expect(createdBody.item.tags).toEqual(['growth', 'ecommerce']);
+    expect(createdBody.autoFilingSyncQueued).toBe(true);
+
+    const tasksResponse = await jsonRequest('GET', '/api/tasks?limit=5');
+    expect(tasksResponse.response.status).toBe(200);
+
+    const task = (tasksResponse.json as {
+      tasks: Array<{
+        task_type: string;
+        payload: {
+          ticker?: string;
+          category?: string;
+          tags?: string[];
+          limit?: number;
+        };
+      }>;
+    }).tasks.find((entry) => entry.task_type === 'sync_filings');
+
+    expect(task).toBeTruthy();
+    expect(task?.payload.ticker).toBe('SHOP');
+    expect(task?.payload.limit).toBe(20);
+    expect(task?.payload.category).toBe('core');
+    expect(task?.payload.tags).toEqual(['growth', 'ecommerce']);
+  });
+
+  it('accepts category and comma-separated tags on manual filings sync payload', async () => {
+    const sync = await jsonRequest('POST', '/api/filings/sync', {
+      ticker: 'nvda',
+      limit: 15,
+      category: 'watch',
+      tags: 'semis, ai, semis'
+    });
+
+    expect(sync.response.status).toBe(200);
+    const task = (sync.json as {
+      task: {
+        task_type: string;
+        payload: {
+          ticker: string;
+          limit: number;
+          category?: string;
+          tags?: string[];
+        };
+      };
+    }).task;
+
+    expect(task.task_type).toBe('sync_filings');
+    expect(task.payload.ticker).toBe('NVDA');
+    expect(task.payload.limit).toBe(15);
+    expect(task.payload.category).toBe('watch');
+    expect(task.payload.tags).toEqual(['semis', 'ai']);
+  });
+
   it('updates notification read and silenced state via patch endpoint', async () => {
     const created = await jsonRequest('POST', '/api/filings/0000000000-26-000010/analyze');
     const taskId = (created.json as { task: { id: string } }).task.id;
diff --git a/lib/server/db/schema.ts b/lib/server/db/schema.ts
index eb06db6..39804c7 100644
--- a/lib/server/db/schema.ts
+++ b/lib/server/db/schema.ts
@@ -204,6 +204,8 @@ export const watchlistItem = sqliteTable('watchlist_item', {
   ticker: text('ticker').notNull(),
   company_name: text('company_name').notNull(),
   sector: text('sector'),
+  category: text('category'),
+  tags: text('tags', { mode: 'json' }).$type<string[]>(),
   created_at: text('created_at').notNull()
 }, (table) => ({
   watchlistUserTickerUnique: uniqueIndex('watchlist_user_ticker_uidx').on(table.user_id, table.ticker),
diff --git a/lib/server/repos/watchlist.ts b/lib/server/repos/watchlist.ts
index 9a47156..1cd7f76 100644
--- a/lib/server/repos/watchlist.ts
+++ b/lib/server/repos/watchlist.ts
@@ -5,6 +5,33 @@ import { watchlistItem } from '@/lib/server/db/schema';
 
 type WatchlistRow = typeof watchlistItem.$inferSelect;
 
+function normalizeTags(tags?: string[]) {
+  if (!Array.isArray(tags)) {
+    return null;
+  }
+
+  const unique = new Set<string>();
+
+  for (const entry of tags) {
+    if (typeof entry !== 'string') {
+      continue;
+    }
+
+    const tag = entry.trim();
+    if (!tag) {
+      continue;
+    }
+
+    unique.add(tag);
+  }
+
+  if (unique.size === 0) {
+    return null;
+  }
+
+  return [...unique];
+}
+
 function toWatchlistItem(row: WatchlistRow): WatchlistItem {
   return {
     id: row.id,
@@ -12,6 +39,10 @@ function toWatchlistItem(row: WatchlistRow): WatchlistItem {
     ticker: row.ticker,
     company_name: row.company_name,
     sector: row.sector,
+    category: row.category,
+    tags: Array.isArray(row.tags)
+      ? row.tags.filter((entry): entry is string => typeof entry === 'string')
+      : [],
     created_at: row.created_at
   };
 }
@@ -26,14 +57,33 @@ export async function listWatchlistItems(userId: string) {
   return rows.map(toWatchlistItem);
 }
 
+export async function getWatchlistItemByTicker(userId: string, ticker: string) {
+  const normalizedTicker = ticker.trim().toUpperCase();
+  if (!normalizedTicker) {
+    return null;
+  }
+
+  const [row] = await db
+    .select()
+    .from(watchlistItem)
+    .where(and(eq(watchlistItem.user_id, userId), eq(watchlistItem.ticker, normalizedTicker)))
+    .limit(1);
+
+  return row ? toWatchlistItem(row) : null;
+}
+
 export async function upsertWatchlistItemRecord(input: {
   userId: string;
   ticker: string;
   companyName: string;
   sector?: string;
+  category?: string;
+  tags?: string[];
 }) {
   const normalizedTicker = input.ticker.trim().toUpperCase();
   const normalizedSector = input.sector?.trim() ? input.sector.trim() : null;
+  const normalizedCategory = input.category?.trim() ? input.category.trim() : null;
+  const normalizedTags = normalizeTags(input.tags);
   const now = new Date().toISOString();
 
   const [inserted] = await db
@@ -43,6 +93,8 @@ export async function upsertWatchlistItemRecord(input: {
       ticker: normalizedTicker,
       company_name: input.companyName,
       sector: normalizedSector,
+      category: normalizedCategory,
+      tags: normalizedTags,
       created_at: now
     })
     .onConflictDoNothing({
@@ -61,7 +113,9 @@ export async function upsertWatchlistItemRecord(input: {
     .update(watchlistItem)
     .set({
       company_name: input.companyName,
-      sector: normalizedSector
+      sector: normalizedSector,
+      category: normalizedCategory,
+      tags: normalizedTags
     })
     .where(and(eq(watchlistItem.user_id, input.userId), eq(watchlistItem.ticker, normalizedTicker)))
     .returning();
diff --git a/lib/server/task-processors.ts b/lib/server/task-processors.ts
index b410474..8ed0295 100644
--- a/lib/server/task-processors.ts
+++ b/lib/server/task-processors.ts
@@ -155,6 +155,37 @@ function parseLimit(raw: unknown, fallback: number, min: number, max: number) {
   return Math.min(Math.max(intValue, min), max);
 }
 
+function parseOptionalText(raw: unknown) {
+  if (typeof raw !== 'string') {
+    return null;
+  }
+
+  const normalized = raw.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+function parseTags(raw: unknown) {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+
+  const unique = new Set<string>();
+  for (const entry of raw) {
+    if (typeof entry !== 'string') {
+      continue;
+    }
+
+    const tag = entry.trim();
+    if (!tag) {
+      continue;
+    }
+
+    unique.add(tag);
+  }
+
+  return [...unique];
+}
+
 function sanitizeExtractionText(value: unknown, maxLength: number) {
   if (typeof value !== 'string') {
     return null;
@@ -519,8 +550,20 @@ function filingLinks(filing: {
 async function processSyncFilings(task: Task) {
   const ticker = parseTicker(task.payload.ticker);
   const limit = parseLimit(task.payload.limit, 20, 1, 50);
+  const category = parseOptionalText(task.payload.category);
+  const tags = parseTags(task.payload.tags);
+  const scopeLabel = [
+    category,
+    tags.length > 0 ? `tags: ${tags.join(', ')}` : null
+  ]
+    .filter((entry): entry is string => Boolean(entry))
+    .join(' | ');
 
-  await setProjectionStage(task, 'sync.fetch_filings', `Fetching up to ${limit} filings for ${ticker}`);
+  await setProjectionStage(
+    task,
+    'sync.fetch_filings',
+    `Fetching up to ${limit} filings for ${ticker}${scopeLabel ? ` (${scopeLabel})` : ''}`
+  );
   const filings = await fetchRecentFilings(ticker, limit);
   const metricsByAccession = new Map<string, Filing['metrics']>();
   const filingsByCik = new Map<string, typeof filings>();
@@ -631,6 +674,8 @@ async function processSyncFilings(task: Task) {
 
   return {
     ticker,
+    category,
+    tags,
     fetched: filings.length,
     inserted: saveResult.inserted,
     updated: saveResult.updated,
diff --git a/lib/types.ts b/lib/types.ts
index 81397d1..2ae64b2 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -11,6 +11,8 @@ export type WatchlistItem = {
   ticker: string;
   company_name: string;
   sector: string | null;
+  category: string | null;
+  tags: string[];
   created_at: string;
 };
 
@@ -262,6 +264,8 @@ export type CompanyAnalysis = {
     ticker: string;
     companyName: string;
     sector: string | null;
+    category: string | null;
+    tags: string[];
     cik: string | null;
   };
   quote: number;