docs: document pipeline readiness gate for task classification

concepts/task-classification.mdx

@@ -78,6 +78,34 @@ Task classification runs entirely on your machine using a persistent MLX inferen
   </Step>
 </Steps>
 
+## Pipeline readiness: when classification actually runs
+
+Classification doesn't just need to be *configured* — both halves of the pipeline have to be *working* before any session is classified. Each polling cycle, Meridian probes:
+
+- **The MLX classifier** — `/health` must respond and `/info` must report the model as loaded (a short, positive readiness probe, not the 120-second cold-start wait).
+- **A PM tracker with synced tickets** — at least one row must exist in the `pm_tasks` table. Rows only land there after a provider authenticates and fetches successfully, so bad credentials keep the pipeline paused.
+
+If either side is down, the classifier **pauses without advancing its cursor**. The session waiting at the head of the queue, and any that accumulate behind it, are held — not skipped. The moment both halves come alive, the backlog drains and every queued session is classified retroactively on the next cycle. The worklog drafter sits behind the same gate (after the PM sync step, so a newly-connected tracker self-opens the gate without a daemon restart).
+
+<Note>
+  **First-run behavior.** Because the MLX classifier sets both `category` *and* `task_key` in the same call, pausing classification also pauses session **categorization**. On a fresh install — before any PM tracker is connected and synced — sessions appear as **uncategorized** in the activity timeline, the Home view, and any focus or category breakdown. This is most visible immediately after `npm install` and `meridian start`.
+
+  Nothing is lost. As soon as you connect Jira, GitHub, or Linear and the first sync populates `pm_tasks` (and the MLX server reports ready), every held session is categorized and linked retroactively on the next polling cycle.
+</Note>
+
+You can confirm both halves yourself:
+
+```bash
+# Is the MLX classifier loaded and ready?
+curl -s http://127.0.0.1:7823/health
+curl -s http://127.0.0.1:7823/info  # look for a non-null "loaded_at"
+
+# Has a PM tracker synced any tickets?
+sqlite3 ~/.meridian/meridian.db 'SELECT COUNT(*) FROM pm_tasks;'
+```
+
+If both return positive results, the next cycle will classify any held sessions. The daemon log records each pause with a `task linking paused` line and resumes silently once the gate opens.
+
 ## Disabling classification
 
 If you don't need ticket linking — or if you're running on a machine without Apple Silicon — you can disable classification entirely:

guides/dashboard.mdx

@@ -47,6 +47,10 @@ Navigate to `/sessions` to see every completed session for the current day, orde
 
 Navigate to `/apps` to see all-time usage statistics aggregated by application: total time, session count, average session length, and the last time each app was seen. A focus donut chart at the top highlights your top apps by cumulative time.
 
+<Note>
+  **Why are my sessions showing as uncategorized?** On a fresh install — or any time the MLX classifier is down or no PM tracker has synced yet — Meridian pauses classification, which also pauses category assignment (both come from the same on-device LLM call). Sessions still record normally and appear in the timeline; they just show without a category until both halves of the pipeline are ready. They categorize retroactively on the next polling cycle once the gate opens. See [Pipeline readiness](/concepts/task-classification#pipeline-readiness-when-classification-actually-runs) for the full mechanics.
+</Note>
+
 ## Activity categories
 
 Meridian classifies each session into one of ten fixed categories. Each category has a distinct color used consistently across the timeline, the category breakdown chart, and every session card:

quickstart.mdx

@@ -94,6 +94,10 @@ This guide walks you through getting Meridian running on your machine for the fi
     ```
 
     The dashboard shows a real-time timeline of your app sessions, coloured by activity category, with a daily breakdown chart and session detail views. New sessions appear every 60 seconds as the daemon processes the latest screenpipe frames.
+
+    <Note>
+      **First sessions may show as uncategorized.** Until you connect a PM tracker (Jira, GitHub, or Linear) and it syncs its first batch of tickets — *and* the MLX classifier reports the model as loaded — Meridian pauses classification. Because the same LLM call assigns both the ticket link and the activity category, sessions appear without a category in the timeline and Home view during that window. Nothing is lost: held sessions categorize retroactively on the next polling cycle once both halves are ready. See [Pipeline readiness](/concepts/task-classification#pipeline-readiness-when-classification-actually-runs) for details.
+    </Note>
   </Step>
 </Steps>