From 7840c59fb9f2dc5ee62a85bf23b2a0e9237a0652 Mon Sep 17 00:00:00 2001
From: Dries Peeters <dries.peeters96@gmail.com>
Date: Fri, 15 May 2026 08:55:37 +0200
Subject: [PATCH] feat: add AI-powered time entry suggestions in timer and
 manual entry forms

Introduce GET /api/ai/suggest with deterministic AISuggestionService results
and optional LLM enrichment (?rich=true), plus reusable suggestion chips,
notes ghost autocomplete, and a manual-entry Autofill popover. All UI hides
when AI is disabled; LLM failures degrade to deterministic suggestions only.
---
 README.md                                    |   8 +
 app/routes/api.py                            | 155 ++++++++++++
 app/static/js/ai_autocomplete.js             | 230 ++++++++++++++++++
 app/templates/base.html                      |   9 +
 app/templates/components/ai_suggestions.html | 233 ++++++++++++++++++
 app/templates/main/dashboard.html            |  54 +++++
 app/templates/timer/manual_entry.html        | 238 ++++++++++++++++++-
 docs/api/API_VERSIONING.md                   |  11 +
 8 files changed, 934 insertions(+), 4 deletions(-)
 create mode 100644 app/static/js/ai_autocomplete.js
 create mode 100644 app/templates/components/ai_suggestions.html

diff --git a/README.md b/README.md
index 734813e6..57ebd6e3 100644
--- a/README.md
+++ b/README.md
@@ -722,6 +722,14 @@ The AI helper is exposed as:
 - Session web UI JSON: `POST /api/ai/chat` (same-origin, login required)
 - REST API v1: `POST /api/v1/ai/chat` (API token required, scopes `read:ai`/`write:ai`)
 
+**Time entry suggestions** (when `AI_ENABLED=true`):
+
+- `GET /api/ai/suggest` — deterministic suggestions from recent patterns and active tasks; optional `?q=` filters by notes/project name; `?rich=true` merges LLM suggestions when configured. AI failures return deterministic results only.
+- **Start Timer** modal: horizontal suggestion chips above the project field (refresh for LLM-enhanced suggestions).
+- **Log Time** form: “✦ Autofill” popover and ghost-text autocomplete on the notes field (`app/static/js/ai_autocomplete.js`).
+
+All suggestion UI is hidden when AI is disabled (`ai_enabled` in template context).
+
 ### Bundled Ollama service (Docker Compose, opt-in)
 
 The root `docker-compose.yml` defines a CPU-only **`ollama`** service and a one-shot **`ollama-init`** sidecar that pulls `AI_MODEL` (default `llama3.1`, ~4.7 GB) into the `ollama_data` volume. These services use the Compose **`ai`** profile so they **do not start by default**.
diff --git a/app/routes/api.py b/app/routes/api.py
index 0f44d365..9126d0a4 100644
--- a/app/routes/api.py
+++ b/app/routes/api.py
@@ -1,5 +1,6 @@
 import json
 import os
+import re
 import uuid
 from datetime import datetime, time, timedelta
 
@@ -24,6 +25,7 @@ from app.models import (
     User,
 )
 from app.models.time_entry import local_now
+from app.services.ai_suggestion_service import AISuggestionService
 from app.services.global_search_service import run_global_search
 from app.services.llm_service import AIServiceError, LLMService
 from app.services.time_tracking_service import TimeTrackingService
@@ -100,6 +102,159 @@ def ai_confirm_action():
         return _ai_error_response(exc)
 
 
+def _ai_confidence_label(value):
+    """Map a numeric confidence (0..1) to a coarse label used by the suggestion UI."""
+    try:
+        score = float(value)
+    except (TypeError, ValueError):
+        return "low"
+    if score >= 0.7:
+        return "high"
+    if score >= 0.4:
+        return "medium"
+    return "low"
+
+
+def _ai_safe_int(value):
+    try:
+        return int(value) if value not in (None, "") else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _ai_parse_suggestion_array(content):
+    """Best-effort extraction of a JSON array from an LLM reply that may include prose."""
+    if not isinstance(content, str) or not content.strip():
+        return []
+    fenced = re.search(r"```(?:json)?\s*(\[.*?\])\s*```", content, re.DOTALL)
+    candidate = fenced.group(1) if fenced else None
+    if candidate is None:
+        match = re.search(r"\[.*\]", content, re.DOTALL)
+        candidate = match.group(0) if match else None
+    if candidate is None:
+        return []
+    try:
+        data = json.loads(candidate)
+    except (ValueError, TypeError):
+        return []
+    if not isinstance(data, list):
+        return []
+    return [item for item in data if isinstance(item, dict)]
+
+
+@api_bp.route("/api/ai/suggest")
+@login_required
+@deprecated_session_api("/api/v1/ai/suggest")
+def ai_suggest():
+    """Return AI-powered time entry suggestions (deterministic, optionally LLM-enhanced)."""
+    q = (request.args.get("q") or "").strip()
+    rich = (request.args.get("rich") or "").strip().lower() in {"1", "true", "yes", "on"}
+
+    suggestions = []
+
+    try:
+        deterministic = AISuggestionService().get_time_entry_suggestions(current_user.id, limit=5)
+    except Exception as exc:  # noqa: BLE001 - never let suggestion errors 500 the request
+        current_app.logger.warning("AI deterministic suggestions failed: %s", exc)
+        deterministic = []
+
+    pairs = {(s.get("project_id"), s.get("task_id")) for s in deterministic if s.get("project_id")}
+    last_entry_by_pair = {}
+    for project_id, task_id in pairs:
+        query = TimeEntry.query.filter(
+            TimeEntry.user_id == current_user.id,
+            TimeEntry.project_id == project_id,
+            TimeEntry.end_time.isnot(None),
+        )
+        if task_id is None:
+            query = query.filter(TimeEntry.task_id.is_(None))
+        else:
+            query = query.filter(TimeEntry.task_id == task_id)
+        entry = query.order_by(TimeEntry.start_time.desc()).first()
+        if entry is not None:
+            last_entry_by_pair[(project_id, task_id)] = entry
+
+    for item in deterministic:
+        pid = item.get("project_id")
+        tid = item.get("task_id")
+        last = last_entry_by_pair.get((pid, tid))
+        suggestions.append(
+            {
+                "project_id": pid,
+                "project_name": item.get("project_name"),
+                "task_id": tid,
+                "task_name": item.get("task_name"),
+                "notes": (last.notes if last and last.notes else "") or "",
+                "tags": (last.tags if last and last.tags else "") or "",
+                "billable": bool(last.billable) if last is not None else True,
+                "confidence": _ai_confidence_label(item.get("confidence")),
+                "source": "deterministic",
+            }
+        )
+
+    if rich:
+        try:
+            llm = LLMService()
+            if llm.is_enabled():
+                prompt = (
+                    "Based on the user's recent time entries and assigned tasks, suggest the top 3 most likely "
+                    "next time entries. For each, return project_id, task_id (if any), notes, tags, billable. "
+                    "Return ONLY a JSON array, no prose."
+                )
+                result = llm.chat(current_user, prompt)
+                ai_items = _ai_parse_suggestion_array(result.get("reply") or "")
+                for item in ai_items:
+                    pid = _ai_safe_int(item.get("project_id"))
+                    if pid is None or not user_can_access_project(current_user, pid):
+                        continue
+                    project = Project.query.get(pid)
+                    if project is None:
+                        continue
+                    tid = _ai_safe_int(item.get("task_id"))
+                    task = Task.query.get(tid) if tid else None
+                    if task is not None and task.project_id != pid:
+                        task = None
+                        tid = None
+                    suggestions.append(
+                        {
+                            "project_id": pid,
+                            "project_name": project.name,
+                            "task_id": tid,
+                            "task_name": task.name if task else None,
+                            "notes": (str(item.get("notes") or ""))[:1000],
+                            "tags": (str(item.get("tags") or ""))[:500],
+                            "billable": bool(item.get("billable", True)),
+                            "confidence": "medium",
+                            "source": "ai",
+                        }
+                    )
+        except AIServiceError as exc:
+            current_app.logger.info("AI rich suggestions unavailable: %s", exc.message)
+        except Exception as exc:  # noqa: BLE001 - never fail the request because of AI errors
+            current_app.logger.warning("AI rich suggestions failed: %s", exc)
+
+    seen = set()
+    unique = []
+    for item in suggestions:
+        key = (item.get("project_id"), item.get("task_id"))
+        if key in seen:
+            continue
+        seen.add(key)
+        unique.append(item)
+
+    if q:
+        ql = q.lower()
+
+        def _matches(item):
+            project_name = (item.get("project_name") or "").lower()
+            notes = (item.get("notes") or "").lower()
+            return ql in project_name or ql in notes
+
+        unique = [item for item in unique if _matches(item)]
+
+    return jsonify({"ok": True, "suggestions": unique[:5]})
+
+
 def _effective_user_for_version_api():
     """Session user, or API token user (Bearer / X-API-Key). Used for version check routes."""
     if getattr(current_user, "is_authenticated", False):
diff --git a/app/static/js/ai_autocomplete.js b/app/static/js/ai_autocomplete.js
new file mode 100644
index 00000000..e7818416
--- /dev/null
+++ b/app/static/js/ai_autocomplete.js
@@ -0,0 +1,230 @@
+/*
+ * AI ghost-text autocomplete for time-entry notes fields.
+ *
+ * Binds to any <input> or <textarea> with `data-ai-autocomplete="notes"`. While the user
+ * types, this debounced helper queries /api/ai/suggest?q=<value> and shows the rest of the
+ * best-matching suggestion as a soft gray "ghost" overlay aligned with the field's caret.
+ * Tab/ArrowRight accept the ghost; Escape (or any other change) dismisses it.
+ *
+ * No build step or framework required — exposes a single global `initAIAutocomplete()` that
+ * scans the document (or an optional root) for matching elements and binds them once.
+ */
+(function (global) {
+    'use strict';
+
+    var ENDPOINT = '/api/ai/suggest';
+    var DEBOUNCE_MS = 400;
+    var MIN_LENGTH = 3;
+    var GHOST_COLOR = 'rgba(107, 114, 128, 0.65)'; // gray-500 @ 65%
+
+    function buildOverlay(input) {
+        var parent = input.parentNode;
+        if (!parent) return null;
+
+        var wrap = document.createElement('span');
+        wrap.className = 'ai-autocomplete-wrap';
+        var inline = input.tagName === 'TEXTAREA' ? 'block' : 'inline-block';
+        wrap.style.cssText = 'position:relative;display:' + inline + ';width:100%;';
+
+        var overlay = document.createElement('div');
+        overlay.className = 'ai-autocomplete-ghost';
+        overlay.setAttribute('aria-hidden', 'true');
+        overlay.style.cssText = [
+            'position:absolute',
+            'top:0', 'left:0', 'right:0', 'bottom:0',
+            'pointer-events:none',
+            'overflow:hidden',
+            'white-space:pre-wrap',
+            'word-wrap:break-word',
+            'color:transparent',
+            'background:transparent',
+            'z-index:0',
+            'margin:0'
+        ].join(';');
+
+        parent.insertBefore(wrap, input);
+        wrap.appendChild(input);
+        wrap.appendChild(overlay);
+
+        if (!input.style.backgroundColor) {
+            input.style.backgroundColor = 'transparent';
+        }
+        input.style.position = 'relative';
+        input.style.zIndex = '1';
+
+        return overlay;
+    }
+
+    function syncOverlayStyles(input, overlay) {
+        var cs = window.getComputedStyle(input);
+        var props = [
+            'fontFamily', 'fontSize', 'fontWeight', 'fontStyle', 'fontVariant',
+            'lineHeight', 'letterSpacing', 'wordSpacing', 'textIndent',
+            'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft',
+            'boxSizing', 'textAlign', 'textTransform'
+        ];
+        for (var i = 0; i < props.length; i++) {
+            overlay.style[props[i]] = cs[props[i]];
+        }
+        overlay.style.borderTopWidth = cs.borderTopWidth;
+        overlay.style.borderRightWidth = cs.borderRightWidth;
+        overlay.style.borderBottomWidth = cs.borderBottomWidth;
+        overlay.style.borderLeftWidth = cs.borderLeftWidth;
+        overlay.style.borderColor = 'transparent';
+        overlay.style.borderStyle = 'solid';
+    }
+
+    function setGhost(input, overlay, suffix) {
+        if (!overlay) return;
+        overlay.textContent = '';
+        if (!suffix) {
+            input.removeAttribute('data-ai-ghost');
+            return;
+        }
+        syncOverlayStyles(input, overlay);
+        overlay.appendChild(document.createTextNode(input.value || ''));
+        var ghost = document.createElement('span');
+        ghost.style.color = GHOST_COLOR;
+        ghost.textContent = suffix;
+        overlay.appendChild(ghost);
+        try {
+            overlay.scrollTop = input.scrollTop;
+            overlay.scrollLeft = input.scrollLeft;
+        } catch (_) {}
+        input.setAttribute('data-ai-ghost', suffix);
+    }
+
+    function clearGhost(input, overlay) {
+        setGhost(input, overlay, '');
+    }
+
+    function acceptGhost(input, overlay) {
+        var suffix = input.getAttribute('data-ai-ghost');
+        if (!suffix) return false;
+        var current = input.value || '';
+        input.value = current + suffix;
+        clearGhost(input, overlay);
+        try {
+            var end = input.value.length;
+            input.setSelectionRange(end, end);
+        } catch (_) {}
+        try { input.dispatchEvent(new Event('input', { bubbles: true })); } catch (_) {}
+        try { input.dispatchEvent(new Event('change', { bubbles: true })); } catch (_) {}
+        return true;
+    }
+
+    function findGhostSuffix(value, suggestions) {
+        if (!value || !Array.isArray(suggestions) || !suggestions.length) return '';
+        var lower = value.toLowerCase();
+        for (var i = 0; i < suggestions.length; i++) {
+            var s = suggestions[i];
+            var notes = (s && s.notes) ? String(s.notes) : '';
+            if (!notes) continue;
+            if (notes.length <= value.length) continue;
+            if (notes.toLowerCase().indexOf(lower) === 0) {
+                return notes.slice(value.length);
+            }
+        }
+        return '';
+    }
+
+    var inflightController = null;
+    function fetchSuggestions(query) {
+        if (inflightController) {
+            try { inflightController.abort(); } catch (_) {}
+            inflightController = null;
+        }
+        var controller = (typeof AbortController !== 'undefined') ? new AbortController() : null;
+        inflightController = controller;
+        var url = ENDPOINT + '?q=' + encodeURIComponent(query);
+        return fetch(url, {
+            credentials: 'same-origin',
+            headers: { 'Accept': 'application/json' },
+            cache: 'no-store',
+            signal: controller ? controller.signal : undefined
+        }).then(function (resp) {
+            if (!resp.ok) return [];
+            return resp.json();
+        }).then(function (data) {
+            if (!data || !Array.isArray(data.suggestions)) return [];
+            return data.suggestions;
+        }).catch(function () {
+            return [];
+        }).then(function (result) {
+            if (inflightController === controller) inflightController = null;
+            return result;
+        });
+    }
+
+    function bindInput(input) {
+        if (input.__aiAutocompleteBound) return;
+        input.__aiAutocompleteBound = true;
+        var overlay = buildOverlay(input);
+        if (!overlay) return;
+
+        var debounceTimer = null;
+
+        function onInput() {
+            clearGhost(input, overlay);
+            if (debounceTimer) { clearTimeout(debounceTimer); debounceTimer = null; }
+            var value = input.value || '';
+            if (value.length < MIN_LENGTH) return;
+            debounceTimer = setTimeout(function () {
+                debounceTimer = null;
+                var current = input.value || '';
+                if (current.length < MIN_LENGTH) return;
+                fetchSuggestions(current).then(function (suggestions) {
+                    if ((input.value || '') !== current) return;
+                    var suffix = findGhostSuffix(current, suggestions);
+                    if (suffix) setGhost(input, overlay, suffix);
+                });
+            }, DEBOUNCE_MS);
+        }
+
+        function onKeyDown(e) {
+            var hasGhost = !!input.getAttribute('data-ai-ghost');
+            if (!hasGhost) return;
+            if (e.key === 'Tab' || e.key === 'ArrowRight') {
+                if (e.key === 'ArrowRight') {
+                    var len = (input.value || '').length;
+                    var start = input.selectionStart;
+                    var end = input.selectionEnd;
+                    if (start !== len || end !== len) return;
+                }
+                e.preventDefault();
+                acceptGhost(input, overlay);
+            } else if (e.key === 'Escape') {
+                e.stopPropagation();
+                clearGhost(input, overlay);
+            }
+        }
+
+        function onScroll() {
+            try {
+                overlay.scrollTop = input.scrollTop;
+                overlay.scrollLeft = input.scrollLeft;
+            } catch (_) {}
+        }
+
+        input.addEventListener('input', onInput);
+        input.addEventListener('keydown', onKeyDown);
+        input.addEventListener('blur', function () { clearGhost(input, overlay); });
+        input.addEventListener('scroll', onScroll);
+    }
+
+    function initAIAutocomplete(root) {
+        var scope = root && root.querySelectorAll ? root : document;
+        var nodes = scope.querySelectorAll(
+            'input[data-ai-autocomplete="notes"], textarea[data-ai-autocomplete="notes"]'
+        );
+        for (var i = 0; i < nodes.length; i++) bindInput(nodes[i]);
+    }
+
+    global.initAIAutocomplete = initAIAutocomplete;
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', function () { initAIAutocomplete(); });
+    } else {
+        initAIAutocomplete();
+    }
+})(window);
diff --git a/app/templates/base.html b/app/templates/base.html
index a5e6d341..50411ee6 100644
--- a/app/templates/base.html
+++ b/app/templates/base.html
@@ -541,6 +541,12 @@
                             <span class="ml-3 sidebar-label">{{ _('Dashboard') }}</span>
                         </a>
                     </li>
+                    <li class="mt-1">
+                        <a href="{{ url_for('main.productivity_dashboard') }}" class="sidebar-nav-item flex items-center p-2 rounded-lg border-l-4 {% if ep == 'main.productivity_dashboard' %}border-primary bg-primary/5 dark:bg-primary/10 text-primary font-semibold{% else %}border-transparent text-text-light dark:text-text-dark hover:bg-background-light dark:hover:bg-background-dark{% endif %}" title="{{ _('My productivity') }}">
+                            <i class="fas fa-chart-line w-6 text-center"></i>
+                            <span class="ml-3 sidebar-label">{{ _('My productivity') }}</span>
+                        </a>
+                    </li>
                     <li class="mt-1">
                         <a href="{{ url_for('timer.manual_entry') }}" class="sidebar-nav-item flex items-center p-2 rounded-lg border-l-4 {% if ep.startswith('timer.') and ep != 'timer.time_entries_overview' %}border-primary bg-primary/5 dark:bg-primary/10 text-primary font-semibold{% else %}border-transparent text-text-light dark:text-text-dark hover:bg-background-light dark:hover:bg-background-dark{% endif %}" title="{{ _('Timer') }}">
                             <i class="fas fa-stopwatch w-6 text-center"></i>
@@ -2564,6 +2570,9 @@ function trackBannerImpression(source) {
             navigator.serviceWorker.register('{{ url_for("main.service_worker") }}', { updateViaCache: 'none' }).catch(function () {});
         }
     </script>
+    {% if ai_enabled %}
+    <script src="{{ url_for('static', filename='js/ai_autocomplete.js') }}?v={{ app_version }}" defer></script>
+    {% endif %}
 </body>
 </html>
 
diff --git a/app/templates/components/ai_suggestions.html b/app/templates/components/ai_suggestions.html
new file mode 100644
index 00000000..74af237e
--- /dev/null
+++ b/app/templates/components/ai_suggestions.html
@@ -0,0 +1,233 @@
+{# AI-powered time entry suggestion chips. Listens for 'timer-modal-opened' to (re)fetch.
+   Emits 'ai-suggestion-selected' (CustomEvent) when a chip is clicked. Hides itself when AI is
+   disabled, the fetch fails, or there are no suggestions. #}
+{% if ai_enabled %}
+<div id="ai-suggestions-panel"
+     class="hidden mb-4 rounded-xl border border-border-light dark:border-border-dark bg-card-light dark:bg-card-dark p-3"
+     data-endpoint="{{ url_for('api.ai_suggest') }}"
+     data-cache-ttl="60"
+     data-empty-text="{{ _('No suggestions yet — track some time first')|e }}"
+     data-loading-text="{{ _('Loading suggestions…')|e }}"
+     aria-live="polite">
+    <div class="flex items-center justify-between mb-2">
+        <div class="flex items-center gap-2 text-sm font-medium text-text-light dark:text-text-dark">
+            <span aria-hidden="true" class="text-primary">✦</span>
+            <span>{{ _('Suggested for you') }}</span>
+        </div>
+        <button type="button"
+                data-ai-suggestions-refresh
+                title="{{ _('Refresh suggestions') }}"
+                aria-label="{{ _('Refresh suggestions') }}"
+                class="inline-flex items-center justify-center w-7 h-7 rounded-md text-text-muted-light dark:text-text-muted-dark hover:text-primary hover:bg-background-light dark:hover:bg-background-dark transition">
+            <i class="fas fa-arrows-rotate text-xs" data-ai-suggestions-refresh-icon></i>
+        </button>
+    </div>
+
+    <div data-ai-suggestions-loading class="hidden flex gap-2 overflow-x-auto pb-1">
+        <div class="animate-pulse h-9 w-40 rounded-full bg-gray-200 dark:bg-gray-700 shrink-0"></div>
+        <div class="animate-pulse h-9 w-48 rounded-full bg-gray-200 dark:bg-gray-700 shrink-0"></div>
+        <div class="animate-pulse h-9 w-36 rounded-full bg-gray-200 dark:bg-gray-700 shrink-0"></div>
+    </div>
+
+    <p data-ai-suggestions-empty class="hidden text-xs text-text-muted-light dark:text-text-muted-dark py-1">
+        {{ _('No suggestions yet — track some time first') }}
+    </p>
+
+    <div data-ai-suggestions-list class="hidden flex gap-2 overflow-x-auto pb-1 -mx-1 px-1"></div>
+</div>
+
+<script>
+(function() {
+    const panel = document.getElementById('ai-suggestions-panel');
+    if (!panel || panel.__aiSuggestionsBound) return;
+    panel.__aiSuggestionsBound = true;
+
+    const endpoint = panel.dataset.endpoint || '/api/ai/suggest';
+    const cacheTtlSeconds = parseInt(panel.dataset.cacheTtl || '60', 10);
+    const cacheKey = 'ai_suggestions_cache';
+    const refreshBtn = panel.querySelector('[data-ai-suggestions-refresh]');
+    const refreshIcon = panel.querySelector('[data-ai-suggestions-refresh-icon]');
+    const loadingEl = panel.querySelector('[data-ai-suggestions-loading]');
+    const listEl = panel.querySelector('[data-ai-suggestions-list]');
+    const emptyEl = panel.querySelector('[data-ai-suggestions-empty]');
+
+    function setBusy(isBusy) {
+        if (loadingEl) loadingEl.classList.toggle('hidden', !isBusy);
+        if (loadingEl) loadingEl.classList.toggle('flex', isBusy);
+        if (isBusy) {
+            if (listEl) listEl.classList.add('hidden');
+            if (emptyEl) emptyEl.classList.add('hidden');
+        }
+        if (refreshBtn) refreshBtn.disabled = !!isBusy;
+        if (refreshIcon) refreshIcon.classList.toggle('fa-spin', !!isBusy);
+    }
+
+    function truncate(value, max) {
+        const s = (value == null ? '' : String(value));
+        if (s.length <= max) return s;
+        return s.slice(0, Math.max(0, max - 1)) + '…';
+    }
+
+    function readCache() {
+        try {
+            const raw = sessionStorage.getItem(cacheKey);
+            if (!raw) return null;
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object') return null;
+            const ageMs = Date.now() - (parsed.fetchedAt || 0);
+            if (ageMs > cacheTtlSeconds * 1000) return null;
+            if (!Array.isArray(parsed.suggestions)) return null;
+            return parsed.suggestions;
+        } catch (_) {
+            return null;
+        }
+    }
+
+    function writeCache(suggestions) {
+        try {
+            sessionStorage.setItem(cacheKey, JSON.stringify({
+                fetchedAt: Date.now(),
+                suggestions: suggestions
+            }));
+        } catch (_) {}
+    }
+
+    function clearCache() {
+        try { sessionStorage.removeItem(cacheKey); } catch (_) {}
+    }
+
+    function confidenceClass(level) {
+        switch ((level || '').toLowerCase()) {
+            case 'high': return 'bg-emerald-500';
+            case 'medium': return 'bg-amber-500';
+            default: return 'bg-gray-400';
+        }
+    }
+
+    function buildChip(suggestion) {
+        const btn = document.createElement('button');
+        btn.type = 'button';
+        btn.className = [
+            'group inline-flex items-center gap-2 shrink-0',
+            'px-3 py-2 rounded-full',
+            'border border-border-light dark:border-border-dark',
+            'bg-background-light dark:bg-background-dark',
+            'hover:border-primary/60 hover:bg-primary/5 dark:hover:bg-primary/10',
+            'text-sm text-text-light dark:text-text-dark',
+            'transition focus:outline-none focus:ring-2 focus:ring-primary/40'
+        ].join(' ');
+        btn.title = (suggestion.project_name || '') +
+            (suggestion.task_name ? ' · ' + suggestion.task_name : '');
+
+        const dot = document.createElement('span');
+        dot.className = 'w-2 h-2 rounded-full ' + confidenceClass(suggestion.confidence);
+        dot.setAttribute('aria-hidden', 'true');
+        btn.appendChild(dot);
+
+        const project = document.createElement('span');
+        project.className = 'font-semibold';
+        project.textContent = truncate(suggestion.project_name || '—', 20);
+        btn.appendChild(project);
+
+        if (suggestion.task_name) {
+            const task = document.createElement('span');
+            task.className = 'text-text-muted-light dark:text-text-muted-dark';
+            task.textContent = '· ' + truncate(suggestion.task_name, 18);
+            btn.appendChild(task);
+        }
+
+        if ((suggestion.source || '').toLowerCase() === 'ai') {
+            const sparkle = document.createElement('span');
+            sparkle.className = 'text-primary text-xs';
+            sparkle.setAttribute('aria-hidden', 'true');
+            sparkle.textContent = '✦';
+            btn.appendChild(sparkle);
+        }
+
+        btn.addEventListener('click', function(e) {
+            e.preventDefault();
+            panel.dispatchEvent(new CustomEvent('ai-suggestion-selected', {
+                bubbles: true,
+                detail: suggestion
+            }));
+            document.dispatchEvent(new CustomEvent('ai-suggestion-selected', {
+                detail: suggestion
+            }));
+        });
+
+        return btn;
+    }
+
+    function render(suggestions) {
+        if (!Array.isArray(suggestions) || suggestions.length === 0) {
+            panel.classList.add('hidden');
+            if (listEl) {
+                listEl.innerHTML = '';
+                listEl.classList.add('hidden');
+                listEl.classList.remove('flex');
+            }
+            return;
+        }
+        panel.classList.remove('hidden');
+        if (loadingEl) {
+            loadingEl.classList.add('hidden');
+            loadingEl.classList.remove('flex');
+        }
+        if (emptyEl) emptyEl.classList.add('hidden');
+        if (listEl) {
+            listEl.innerHTML = '';
+            suggestions.forEach(function(s) { listEl.appendChild(buildChip(s)); });
+            listEl.classList.remove('hidden');
+            listEl.classList.add('flex');
+        }
+    }
+
+    async function fetchSuggestions(options) {
+        const useCache = !(options && options.force);
+        const rich = !!(options && options.rich);
+        if (useCache && !rich) {
+            const cached = readCache();
+            if (cached) { render(cached); return; }
+        }
+        setBusy(true);
+        try {
+            const url = endpoint + (rich ? (endpoint.indexOf('?') >= 0 ? '&rich=true' : '?rich=true') : '');
+            const resp = await fetch(url, {
+                credentials: 'same-origin',
+                headers: { 'Accept': 'application/json' },
+                cache: 'no-store'
+            });
+            if (!resp.ok) throw new Error('HTTP ' + resp.status);
+            const data = await resp.json();
+            const suggestions = (data && Array.isArray(data.suggestions)) ? data.suggestions : [];
+            if (!rich) writeCache(suggestions);
+            render(suggestions);
+        } catch (err) {
+            if (typeof console !== 'undefined' && console.warn) {
+                console.warn('[AI Suggestions] fetch failed:', err);
+            }
+            panel.classList.add('hidden');
+        } finally {
+            setBusy(false);
+        }
+    }
+
+    if (refreshBtn) {
+        refreshBtn.addEventListener('click', function() {
+            clearCache();
+            fetchSuggestions({ force: true, rich: true });
+        });
+    }
+
+    document.addEventListener('timer-modal-opened', function() {
+        fetchSuggestions({});
+    });
+
+    if (document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', function() { fetchSuggestions({}); });
+    } else {
+        fetchSuggestions({});
+    }
+})();
+</script>
+{% endif %}
diff --git a/app/templates/main/dashboard.html b/app/templates/main/dashboard.html
index ceba30f9..aae52bf1 100644
--- a/app/templates/main/dashboard.html
+++ b/app/templates/main/dashboard.html
@@ -709,6 +709,7 @@
             </div>
             <form method="POST" action="{{ url_for('timer.start_timer') }}" id="startTimerForm" class="p-4">
                 <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
+                {% include 'components/ai_suggestions.html' %}
                 <div class="space-y-4">
                     {% if templates %}
                     <div class="pb-3 border-b border-border-light dark:border-border-dark">
@@ -883,6 +884,7 @@
                         loadTasksForProject(projectSelect.value);
                     }
                 } catch (_) {}
+                try { document.dispatchEvent(new CustomEvent('timer-modal-opened')); } catch (_) {}
             }
         }
         document.querySelectorAll('.js-open-start-timer').forEach(function(openBtn) {
@@ -1645,6 +1647,58 @@
 });
 </script>
 
+{% if ai_enabled %}
+<script>
+// Wire AI suggestion chips inside the Start Timer modal: clicking a chip pre-fills the form.
+document.addEventListener('DOMContentLoaded', function() {
+    const modal = document.getElementById('startTimerModal');
+    if (!modal) return;
+
+    function applyAISuggestion(s) {
+        if (!s) return;
+        const projectSelect = document.getElementById('startTimerProject');
+        const taskSelect = document.getElementById('startTimerTask');
+        const clientSelect = document.getElementById('startTimerClient');
+        const notesInput = document.getElementById('startTimerNotes');
+        const tagsInput = document.getElementById('startTimerTags');
+
+        if (projectSelect && s.project_id) {
+            projectSelect.value = String(s.project_id);
+            if (clientSelect) clientSelect.value = '';
+            try { projectSelect.dispatchEvent(new Event('change', { bubbles: true })); } catch (_) {}
+        }
+
+        if (s.task_id && taskSelect) {
+            const target = String(s.task_id);
+            let attempts = 15;
+            (function trySetTask() {
+                const found = Array.from(taskSelect.options).some(function(o) { return o.value === target; });
+                if (found) {
+                    taskSelect.value = target;
+                    return;
+                }
+                if (attempts-- > 0) setTimeout(trySetTask, 100);
+            })();
+        }
+
+        if (s.notes != null) {
+            if (notesInput) notesInput.value = s.notes || '';
+            if (window.dashboardNotesEditor && typeof window.dashboardNotesEditor.setMarkdown === 'function') {
+                try { window.dashboardNotesEditor.setMarkdown(s.notes || ''); } catch (_) {}
+            }
+        }
+
+        if (tagsInput && s.tags != null) tagsInput.value = s.tags;
+    }
+
+    document.addEventListener('ai-suggestion-selected', function(e) {
+        if (!modal || modal.classList.contains('hidden')) return;
+        applyAISuggestion(e && e.detail);
+    });
+});
+</script>
+{% endif %}
+
 <!-- Toast UI Editor -->
 <script src="https://uicdn.toast.com/editor/latest/toastui-editor-all.min.js"></script>
 {% endblock %}
diff --git a/app/templates/timer/manual_entry.html b/app/templates/timer/manual_entry.html
index 2b6a0cb8..02cd89f3 100644
--- a/app/templates/timer/manual_entry.html
+++ b/app/templates/timer/manual_entry.html
@@ -53,9 +53,35 @@
         <div class="space-y-8">
             {# Section: Project & task #}
             <section class="pb-6 border-b border-border-light dark:border-border-dark">
-                <h2 class="form-section-title">
-                    <i class="fas fa-folder text-primary"></i>{{ _('Project & task') }}
-                </h2>
+                <div class="flex items-center justify-between gap-3 flex-wrap">
+                    <h2 class="form-section-title">
+                        <i class="fas fa-folder text-primary"></i>{{ _('Project & task') }}
+                    </h2>
+                    {% if ai_enabled %}
+                    <div id="aiAutofillContainer" class="relative hidden mb-2">
+                        <button type="button" id="aiAutofillBtn"
+                                class="inline-flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium rounded-lg border border-primary/40 text-primary bg-primary/5 hover:bg-primary/10 dark:hover:bg-primary/15 transition focus:outline-none focus:ring-2 focus:ring-primary/40"
+                                aria-haspopup="menu"
+                                aria-expanded="false"
+                                aria-controls="aiAutofillPopover">
+                            <span aria-hidden="true">✦</span>{{ _('Autofill') }}
+                        </button>
+                        <div id="aiAutofillPopover"
+                             class="hidden absolute z-30 right-0 mt-2 w-80 rounded-xl border border-border-light dark:border-border-dark bg-card-light dark:bg-card-dark shadow-lg p-2"
+                             role="menu"
+                             aria-hidden="true">
+                            <div data-ai-autofill-loading class="hidden flex-col gap-2 px-1 py-2">
+                                <div class="h-12 rounded-lg bg-gray-100 dark:bg-gray-700 animate-pulse"></div>
+                                <div class="h-12 rounded-lg bg-gray-100 dark:bg-gray-700 animate-pulse"></div>
+                            </div>
+                            <p data-ai-autofill-empty class="hidden px-3 py-3 text-xs text-text-muted-light dark:text-text-muted-dark">
+                                {{ _('No suggestions available') }}
+                            </p>
+                            <div data-ai-autofill-list class="space-y-1"></div>
+                        </div>
+                    </div>
+                    {% endif %}
+                </div>
                 <div class="space-y-6">
                     <div class="grid grid-cols-1 md:grid-cols-2 gap-6">
                         <div>
@@ -139,7 +165,7 @@
                     <div class="md:col-span-2">
                         <label for="notes" class="block text-sm font-medium text-text-light dark:text-text-dark mb-2">{% if getattr(settings, 'time_entry_require_description', false) %}{{ _('Notes') }} *{% else %}{{ _('Notes') }}{% endif %}</label>
                         <div class="markdown-editor-wrapper">
-                            <textarea name="notes" id="notes" class="hidden">{{ prefill_notes or '' }}</textarea>
+                            <textarea name="notes" id="notes" class="hidden" data-ai-autocomplete="notes">{{ prefill_notes or '' }}</textarea>
                             <div id="notes_editor"></div>
                         </div>
                     </div>
@@ -1105,4 +1131,208 @@ document.addEventListener('DOMContentLoaded', function() {
     document.head.appendChild(scriptEl);
 });
 </script>
+
+{% if ai_enabled %}
+<script>
+(function() {
+    const container = document.getElementById('aiAutofillContainer');
+    const button = document.getElementById('aiAutofillBtn');
+    const popover = document.getElementById('aiAutofillPopover');
+    if (!container || !button || !popover) return;
+
+    const listEl = popover.querySelector('[data-ai-autofill-list]');
+    const emptyEl = popover.querySelector('[data-ai-autofill-empty]');
+    const loadingEl = popover.querySelector('[data-ai-autofill-loading]');
+    const projectSelect = document.getElementById('project_id');
+    const taskSelect = document.getElementById('task_id');
+    const notesInput = document.getElementById('notes');
+    const tagsInput = document.getElementById('tags');
+    const billableInput = document.getElementById('billable');
+
+    let cachedSuggestions = null;
+    let everFetched = false;
+
+    function setLoading(busy) {
+        if (loadingEl) {
+            loadingEl.classList.toggle('hidden', !busy);
+            loadingEl.classList.toggle('flex', busy);
+        }
+        if (busy) {
+            if (emptyEl) emptyEl.classList.add('hidden');
+            if (listEl) listEl.innerHTML = '';
+        }
+    }
+
+    function openPopover() {
+        popover.classList.remove('hidden');
+        popover.setAttribute('aria-hidden', 'false');
+        button.setAttribute('aria-expanded', 'true');
+    }
+
+    function closePopover() {
+        popover.classList.add('hidden');
+        popover.setAttribute('aria-hidden', 'true');
+        button.setAttribute('aria-expanded', 'false');
+    }
+
+    function isOpen() {
+        return !popover.classList.contains('hidden');
+    }
+
+    function truncate(value, max) {
+        const s = (value == null ? '' : String(value));
+        if (s.length <= max) return s;
+        return s.slice(0, Math.max(0, max - 1)) + '…';
+    }
+
+    function setNotesValue(value) {
+        if (notesInput) notesInput.value = value || '';
+        if (window.mdEditor && typeof window.mdEditor.setMarkdown === 'function') {
+            try { window.mdEditor.setMarkdown(value || ''); } catch (_) {}
+        }
+    }
+
+    function trySetTaskWhenAvailable(taskId, attemptsRemaining) {
+        if (!taskSelect || !taskId) return;
+        const target = String(taskId);
+        const found = Array.from(taskSelect.options).some(function(o) { return o.value === target; });
+        if (found) {
+            taskSelect.value = target;
+            try { taskSelect.dispatchEvent(new Event('change', { bubbles: true })); } catch (_) {}
+            return;
+        }
+        if (attemptsRemaining > 0) {
+            setTimeout(function() { trySetTaskWhenAvailable(taskId, attemptsRemaining - 1); }, 100);
+        }
+    }
+
+    function applySuggestion(s) {
+        if (!s) return;
+        if (projectSelect && s.project_id) {
+            projectSelect.value = String(s.project_id);
+            try { projectSelect.dispatchEvent(new Event('change', { bubbles: true })); } catch (_) {}
+            if (s.task_id) {
+                taskSelect && taskSelect.setAttribute('data-selected-task-id', String(s.task_id));
+                trySetTaskWhenAvailable(s.task_id, 15);
+            }
+        }
+        if (s.notes) setNotesValue(s.notes);
+        if (tagsInput && s.tags != null) tagsInput.value = s.tags;
+        if (billableInput && typeof s.billable === 'boolean') billableInput.checked = !!s.billable;
+        closePopover();
+    }
+
+    function buildRow(s) {
+        const row = document.createElement('button');
+        row.type = 'button';
+        row.className = [
+            'w-full text-left px-3 py-2 rounded-lg',
+            'hover:bg-background-light dark:hover:bg-background-dark',
+            'focus:outline-none focus:bg-background-light dark:focus:bg-background-dark',
+            'transition'
+        ].join(' ');
+        row.setAttribute('role', 'menuitem');
+
+        const title = document.createElement('div');
+        title.className = 'flex items-center gap-2 text-sm font-medium text-text-light dark:text-text-dark';
+        const projectSpan = document.createElement('span');
+        projectSpan.textContent = truncate(s.project_name || '—', 28);
+        title.appendChild(projectSpan);
+        if (s.task_name) {
+            const sep = document.createElement('span');
+            sep.className = 'text-text-muted-light dark:text-text-muted-dark';
+            sep.textContent = '· ' + truncate(s.task_name, 22);
+            title.appendChild(sep);
+        }
+        row.appendChild(title);
+
+        if (s.notes) {
+            const notesPreview = document.createElement('div');
+            notesPreview.className = 'mt-1 text-xs text-text-muted-light dark:text-text-muted-dark line-clamp-2';
+            notesPreview.textContent = truncate(s.notes, 120);
+            row.appendChild(notesPreview);
+        }
+
+        row.addEventListener('click', function(e) {
+            e.preventDefault();
+            applySuggestion(s);
+        });
+        return row;
+    }
+
+    function renderSuggestions(suggestions) {
+        if (!listEl) return;
+        listEl.innerHTML = '';
+        if (!Array.isArray(suggestions) || suggestions.length === 0) {
+            if (emptyEl) emptyEl.classList.remove('hidden');
+            return;
+        }
+        if (emptyEl) emptyEl.classList.add('hidden');
+        suggestions.slice(0, 3).forEach(function(s) {
+            listEl.appendChild(buildRow(s));
+        });
+    }
+
+    async function loadSuggestions() {
+        setLoading(true);
+        try {
+            const resp = await fetch('{{ url_for("api.ai_suggest") }}', {
+                credentials: 'same-origin',
+                headers: { 'Accept': 'application/json' },
+                cache: 'no-store'
+            });
+            if (!resp.ok) throw new Error('HTTP ' + resp.status);
+            const data = await resp.json();
+            cachedSuggestions = (data && Array.isArray(data.suggestions)) ? data.suggestions : [];
+        } catch (_) {
+            cachedSuggestions = [];
+        } finally {
+            everFetched = true;
+            setLoading(false);
+            // hide the entire button if we never got any suggestions
+            if (!cachedSuggestions || cachedSuggestions.length === 0) {
+                container.classList.add('hidden');
+            } else {
+                container.classList.remove('hidden');
+            }
+            renderSuggestions(cachedSuggestions || []);
+        }
+    }
+
+    button.addEventListener('click', async function(e) {
+        e.preventDefault();
+        if (isOpen()) { closePopover(); return; }
+        if (!everFetched) {
+            openPopover();
+            await loadSuggestions();
+            if (!cachedSuggestions || cachedSuggestions.length === 0) {
+                closePopover();
+                return;
+            }
+        } else {
+            renderSuggestions(cachedSuggestions || []);
+            openPopover();
+        }
+    });
+
+    document.addEventListener('click', function(e) {
+        if (!isOpen()) return;
+        if (container.contains(e.target)) return;
+        closePopover();
+    });
+
+    document.addEventListener('keydown', function(e) {
+        if (e.key === 'Escape' && isOpen()) {
+            closePopover();
+            try { button.focus(); } catch (_) {}
+        }
+    });
+
+    // Probe once on load: hide the button entirely if there are no suggestions.
+    loadSuggestions().then(function() {
+        // popover stays closed; container visibility is set inside loadSuggestions
+    });
+})();
+</script>
+{% endif %}
 {% endblock %}
diff --git a/docs/api/API_VERSIONING.md b/docs/api/API_VERSIONING.md
index 55f8dc42..da4fa1ff 100644
--- a/docs/api/API_VERSIONING.md
+++ b/docs/api/API_VERSIONING.md
@@ -31,6 +31,17 @@ These **`/api/*`** routes have v1 successors. They remain for the web UI but may
 - `GET /api/projects`, `GET /api/projects/<id>/tasks`, `GET /api/tasks` → `/api/v1/projects`, `/api/v1/tasks`
 - `GET /api/activities` → `GET /api/v1/activities` (v1 is a simpler list; legacy adds filters/pagination)
 
+### Session AI routes (web UI; partial v1 migration)
+
+| Session route | Notes | v1 successor (planned) |
+|---------------|--------|-------------------------|
+| `GET /api/ai/context-preview` | Compact context for AI helper | `GET /api/v1/ai/context-preview` |
+| `POST /api/ai/chat` | AI helper chat | `POST /api/v1/ai/chat` |
+| `POST /api/ai/actions/confirm` | Confirm proposed AI actions | `POST /api/v1/ai/actions/confirm` |
+| `GET /api/ai/suggest` | Time entry suggestions (`?q=`, `?rich=true`) | `GET /api/v1/ai/suggest` (deprecation header points here) |
+
+`GET /api/ai/suggest` always returns deterministic suggestions from `AISuggestionService`; optional `rich=true` adds LLM suggestions when the helper is enabled. Failures in the LLM path do not fail the request.
+
 ### Internal / UI-only (no v1 equivalent yet)
 
 Examples: `GET /api/notifications`, dashboard stats (`/api/dashboard/*`, `/api/stats*`, `/api/reports/week-comparison`), editor uploads, smart notifications dismiss, many calendar helpers. Treat as **internal** to the web app unless documented otherwise.