seo-intel 1.5.33 → 1.5.38

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 1.5.38 (2026-05-23)
+
+### Fix — LM Studio model count was always 0 (wrong endpoint + wrong parser)
+The wizard showed `localhost:1234 LM Studio · 0 model(s) active` even when LM Studio had models loaded. Two bugs stacked:
+
+1. We were hitting `/api/v1/models` (LM Studio's native endpoint), not `/v1/models` (the OpenAI-compatible one).
+2. Even on the native endpoint, the response shape is `{ models: [{ key, loaded_instances }] }` — we were parsing it as `{ data: [{ id }] }` (OpenAI shape), so even when the call succeeded, the filter zeroed everything out.
+
+Fix in `setup/checks.js`:
+- Try `/v1/models` first (standard OpenAI-compat, listed under LM Studio's "OpenAI-compatible" Developer tab).
+- Fall back to `/api/v1/models` if the OpenAI route is disabled in LM Studio settings.
+- Parse both shapes: `data.data` (OpenAI) and `data.models` (LM Studio native). Identifier extracted via first-of `id | key | model | name`.
+
+Verified against the user's live LM Studio (3 models surfaced correctly — Gemma 4 E2B, an uncensored variant, and an embedding model). Smoke 10/10.
+
+## 1.5.37 (2026-05-23)
+
+### Notify — native macOS / Linux notifications for pending problems
+The "subtle nudge" delivery channel agreed in the v1.5.34 brainstorm. Users don't have to remember to open the dashboard; the OS reminds them when there's work to do.
+
+- **New CLI:** `seo-intel notify [project]` — scans configured projects (or one if specified), fires a native notification per project with critical/warn/info problem counts. Cron-friendly: no interactive output, never blocks, never throws. Pass `--open` to also open the dashboard URL after notifying.
+- **macOS:** uses built-in `osascript` (Notification Center). Glass sound fires when any project has critical issues; quiet otherwise. No third-party deps (no `terminal-notifier` etc).
+- **Linux:** uses `notify-send` (libnotify, ships with GNOME/KDE/XFCE). Falls through to console if not installed.
+- **Windows/unknown:** console-prints the notification so cron logs still capture it.
+- **New library:** `lib/notify.js` exports `notify({ title, message, subtitle?, sound? })` + `openUrl(url)`. Reusable from any future module (e.g. a Site Watch hook firing notifications on regressions).
+
+**Suggested cron entry** (macOS): `0 9 * * * cd /path/to/seo-intel && node cli.js notify` — fires at 9am every day for every project with pending issues.
+
+**Verified live:** 4 notifications fired correctly during testing (carbium 190 warn · 51 info; dgents 11 warn · 1 info; risunouto 26 warn · 11 info; ukkometa 55 warn · 20 info). All four landed in macOS Notification Center.
+
+## 1.5.36 (2026-05-23)
+
+### Setup — LM Studio detection works for LAN hosts (fixes "unreachable" false negative)
+The wizard's host-ping logic was gated on port number — only checked LM Studio if port was exactly 1234, only checked Ollama if anything else. That broke for any non-default setup. **Now probes both engines in parallel for every host** regardless of port.
+
+- **`/api/setup/ping-ollama`** runs `checkOllamaRemote` and `checkLmStudio` in parallel via `Promise.all`. Whichever responds wins. Order: Ollama preferred when both respond (preserves existing behaviour for ambiguous setups).
+- Success message now identifies the engine: *"Connected to LM Studio — 5 model(s) found"* vs *"Connected to Ollama — 3 model(s) found"*.
+- Unreachable error returns a structured `hint` with three common causes (bind to 127.0.0.1 only, firewall, wrong port) — much more useful than the old "check IP, port, and that Ollama is running" message.
+- Wizard surfaces the `hint` directly via HTML-escaped error text. No more misleading "Ollama is running on that machine" when the user is running LM Studio.
+
+The "EXTRACTION HOSTS" section copy already mentioned both engines correctly — only the per-ping result message and the backend gating needed fixing. Existing localhost auto-detection (the green `localhost:1234 active` row in the screenshot) was unaffected.
+
+## 1.5.35 (2026-05-22)
+
+### MCP — `mark_problem_status` closes the Problems loop
+Agents can now confirm fixes and dismiss problems they've handled. Without this tool, subjective problems (positioning, content gaps) would keep re-appearing in `list_problems` even after the agent had addressed them.
+
+- **`mark_problem_status(problem_id, project, status, snooze_days?, agent_name?, note?)`** — **free tier**. Status: `fixed` | `wont_fix` | `snoozed`. Snoozed requires `snooze_days` (1-365). Re-marking the same problem_id updates the existing record.
+- **`list_problems` gains `include_marked: boolean`** — by default marked problems are hidden; set true to audit what's been suppressed (each row gains a `status: 'active' | 'fixed' | 'wont_fix' | 'snoozed'` field).
+- **`problem_counts` in `list_projects` honor marks** — when an agent marks 12 of 26 orphans as fixed, the nag immediately drops to 14. The "warm fuzzy" of clearing things.
+
+Schema: idempotent `CREATE TABLE IF NOT EXISTS problem_status` migration in `getDb()`. Stores `problem_id` (matches `list_problems` output), project, status, marked_at, marked_by (e.g. `agent:claude-opus-4-7`), note, expires_at (for snoozes). Indexed by `(project, status)`.
+
+Verified end-to-end: mark a real orphan → count drops 26→25 → re-list with `include_marked` reveals it with `status: 'fixed'`. Smoke 10/10. MCP surface: 15 tools.
+
+## 1.5.34 (2026-05-22)
+
+### MCP — Problems as the entry surface ("what should I fix?")
+The single biggest UX shift in the agent flow. Two new touchpoints turn `list_projects` into a passive nag layer and `list_problems` into the canonical "fix-able findings" tool.
+
+- **`list_problems(project, severity?, category?, limit?, max_fix_difficulty?)`** — severity-sorted, agent-fixable problem list. Every item returns `{id, severity, category, tier, title, description, affected_urls, evidence, fix_template, verification, first_seen, last_seen, fix_difficulty}`. The `fix_template` is the design point — it gives a coding agent a concrete next step (file/URL, what to change, how to verify).
+  - **Free categories**: `tech` (HTTP 4xx/5xx), `indexability` (robots header conflicts), `links` (orphan pages), `schema` (missing structured data on substantive pages).
+  - **Paid categories**: `citability` (low AEO scores from `citability_scores`), `content` / `keyword` / `positioning` (mapped from Intelligence Ledger).
+  - Sorting: severity (critical → warn → info), then fix_difficulty (1=trivial → 5=deep work), then last_seen DESC.
+- **`list_projects` now nags.** Every project response includes `problem_counts`, `stale_days`, and a `nag` string that flags critical/warn counts and stale crawls. Solo users see paid-tier counts; free users see free-tier counts only (no teasing). Example output: `risunouto: 26 warn · crawl 42d stale. Call list_problems('risunouto') to see them.`
+- **New library: `lib/problems.js`** — `getProblems(db, project, opts)` + `getProblemCounts(db, project, opts)` are the unifying primitive. Six collectors today (4 free + 2 paid); future patches add more (decay targets, friction points, mark_problem_status, schema-vs-competitor diffs).
+
+The agent loop this unlocks: `list_projects` → see the nag → `list_problems(project, severity='critical')` → fix the highest-leverage one → `run_crawl(project)` → re-call `list_problems` to verify it cleared. Closed loop, no dashboard required.
+
+**MCP surface: 14 tools.** Next patches: `mark_problem_status` (v1.5.35) + native notification daemon (v1.5.36) + dashboard Problems tab as landing (v1.5.37).
+
 ## 1.5.33 (2026-05-19)
 
 ### Dashboard — visual brief foundation (intel-blue tokens + component utilities)

package/cli.js

@@ -1456,6 +1456,61 @@ program
     }
   });
 
+// ── NOTIFY (native OS notification for pending problems) ───────────────────
+// Designed to run on cron/launchd. Subtle nudge to push the user back into
+// the dashboard. macOS via osascript, Linux via notify-send, no deps.
+program
+  .command('notify [project]')
+  .description('Fire native macOS/Linux notification for projects with pending problems. Cron-friendly. Pass a project to limit; omit to scan all configured projects.')
+  .option('--open', 'Also open the dashboard URL when a notification fires')
+  .option('--all', 'Notify even when no problems exist (useful for testing)')
+  .option('--port <port>', 'Dashboard port for --open (default 3000)', '3000')
+  .action(async (project, opts) => {
+    const { notify, openUrl } = await import('./lib/notify.js');
+    const { getProblemCounts } = await import('./lib/problems.js');
+    const db = getDb();
+
+    // Resolve project list: explicit arg → single project; otherwise all configs with data
+    const configDir = join(__dirname, 'config');
+    const { readFileSync, readdirSync, existsSync } = await import('node:fs');
+    let projects = [];
+    if (project) {
+      try { loadConfig(project); projects = [{ project }]; }
+      catch (e) { console.error(chalk.red(e.message)); process.exit(1); }
+    } else if (existsSync(configDir)) {
+      projects = readdirSync(configDir)
+        .filter(f => f.endsWith('.json') && f !== 'example.json' && !f.startsWith('setup'))
+        .map(f => {
+          try { const c = JSON.parse(readFileSync(join(configDir, f), 'utf8')); return { project: c.project || f.replace('.json', '') }; }
+          catch { return null; }
+        })
+        .filter(Boolean);
+    }
+
+    let fired = 0;
+    const pro = isPro();
+    for (const { project: p } of projects) {
+      let counts;
+      try { counts = getProblemCounts(db, p, { includePaid: pro }); }
+      catch { continue; }
+      const score = counts.critical * 10 + counts.warn; // weighted: 1 critical = 10 warns
+      if (score === 0 && !opts.all) continue;
+      const title = `SEO Intel — ${p}`;
+      const message = counts.critical > 0
+        ? `${counts.critical} CRITICAL · ${counts.warn} warn pending`
+        : `${counts.warn} warn · ${counts.info} info pending`;
+      notify({ title, message, subtitle: 'Click the dashboard to fix', sound: counts.critical > 0 ? 'Glass' : false });
+      fired++;
+      console.log(chalk.dim(`  📣 ${p}: ${message}`));
+    }
+    if (opts.open && fired > 0) {
+      const url = `http://localhost:${opts.port}/`;
+      openUrl(url);
+      console.log(chalk.dim(`  → opened ${url}`));
+    }
+    if (fired === 0) console.log(chalk.dim('  ✓ No projects need attention.'));
+  });
+
 // ── STATUS ─────────────────────────────────────────────────────────────────
 program
   .command('status')

package/db/db.js

@@ -31,6 +31,20 @@ export function getDb(dbPath = './seo-intel.db') {
   try { _db.exec('ALTER TABLE extractions ADD COLUMN intent_scores TEXT'); } catch { /* already exists */ }
   try { _db.exec("ALTER TABLE insights ADD COLUMN source TEXT DEFAULT 'cli'"); } catch { /* already exists */ }
 
+  // Problem status tracking (v1.5.35) — agents/users mark items as fixed/wont_fix/snoozed
+  _db.exec(`
+    CREATE TABLE IF NOT EXISTS problem_status (
+      problem_id  TEXT PRIMARY KEY,                      -- matches lib/problems.js makeId() output
+      project     TEXT NOT NULL,
+      status      TEXT NOT NULL,                         -- fixed | wont_fix | snoozed
+      marked_at   INTEGER NOT NULL,
+      marked_by   TEXT,                                  -- 'agent:<name>' | 'cli' | 'dashboard'
+      note        TEXT,
+      expires_at  INTEGER                                -- for snoozed; NULL for fixed/wont_fix
+    );
+    CREATE INDEX IF NOT EXISTS idx_problem_status_project ON problem_status(project, status);
+  `);
+
   // Backfill first_seen_at from crawled_at for existing rows
   _db.exec('UPDATE pages SET first_seen_at = crawled_at WHERE first_seen_at IS NULL');
 

package/lib/notify.js

@@ -0,0 +1,74 @@
+/**
+ * lib/notify.js — Fire native OS notifications (macOS / Linux).
+ *
+ * Subtle nudge channel for the "user forgets to check SEO" problem.
+ * Click action: opens the dashboard URL (configurable). No third-party
+ * deps — uses built-in `osascript` on macOS and `notify-send` (libnotify)
+ * on Linux. Falls through to console on Windows / unknown platforms.
+ *
+ * Designed to be safe in cron contexts: never throws, never blocks the
+ * process, fire-and-forget via detached subprocess.
+ */
+
+import { spawn } from 'child_process';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.title       Headline shown bold in the notification
+ * @param {string} opts.message     Body text
+ * @param {string} [opts.subtitle]  macOS only — small subtitle below title
+ * @param {string} [opts.sound]     macOS sound name (e.g. 'Glass', 'Tink'). Set false to silence.
+ * @returns {boolean}  true if a native notification was fired; false on fallback
+ */
+export function notify({ title, message, subtitle, sound = false }) {
+  if (!title || !message) return false;
+  const platform = process.platform;
+  try {
+    if (platform === 'darwin') return notifyMacOS({ title, message, subtitle, sound });
+    if (platform === 'linux')  return notifyLinux({ title, message });
+  } catch { /* fall through */ }
+  // Windows / unknown — print to console so cron jobs still leave a trace
+  console.log(`[seo-intel notify] ${title}: ${message}`);
+  return false;
+}
+
+function notifyMacOS({ title, message, subtitle, sound }) {
+  // osascript can fire a notification but cannot wire click→URL natively.
+  // For click-to-open we'd need terminal-notifier (third-party). Keeping
+  // zero-dep here; the CLI's `--open` flag opens the dashboard alongside.
+  const safe = (s) => String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const parts = [`display notification "${safe(message)}" with title "${safe(title)}"`];
+  if (subtitle) parts.push(`subtitle "${safe(subtitle)}"`);
+  if (sound) parts.push(`sound name "${safe(sound)}"`);
+  const script = parts.join(' ');
+  spawn('osascript', ['-e', script], { detached: true, stdio: 'ignore' }).unref();
+  return true;
+}
+
+function notifyLinux({ title, message }) {
+  // notify-send is shipped with libnotify on most Linux distros (GNOME, KDE,
+  // XFCE). On minimal/headless installs it may be missing — we fail
+  // silently and console-print in that case.
+  const child = spawn('notify-send', [
+    '--app-name=SEO Intel',
+    '--icon=dialog-information',
+    title,
+    message,
+  ], { detached: true, stdio: 'ignore' });
+  child.on('error', () => console.log(`[seo-intel notify] ${title}: ${message}`));
+  child.unref();
+  return true;
+}
+
+/**
+ * Open a URL in the user's default browser. Cross-platform, fire-and-forget.
+ * @param {string} url
+ */
+export function openUrl(url) {
+  try {
+    const platform = process.platform;
+    if (platform === 'darwin') spawn('open', [url], { detached: true, stdio: 'ignore' }).unref();
+    else if (platform === 'linux') spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
+    else if (platform === 'win32') spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
+  } catch { /* best-effort */ }
+}

package/lib/problems.js

@@ -0,0 +1,382 @@
+/**
+ * lib/problems.js — Unified Problems list.
+ *
+ * Aggregates problem-shaped findings from every source in the DB (technical
+ * audit, citability scores, orphan analysis, schema gaps, intelligence
+ * ledger) into a single severity-sorted list with everything an AI coding
+ * agent needs to fix it: affected_urls, fix_template, verification.
+ *
+ * This is the canonical "what should I work on?" surface — backs both the
+ * MCP `list_problems` tool and the upcoming dashboard Problems tab.
+ *
+ * Each problem returns:
+ *   {
+ *     id, severity, category, tier, title, description, affected_urls,
+ *     evidence, fix_template, verification, first_seen, last_seen,
+ *     fix_difficulty
+ *   }
+ */
+
+import crypto from 'node:crypto';
+
+export const PROBLEM_CATEGORIES = ['tech', 'indexability', 'links', 'schema', 'citability', 'content', 'keyword', 'positioning'];
+export const FREE_CATEGORIES = ['tech', 'indexability', 'links', 'schema'];
+export const PAID_CATEGORIES = ['citability', 'content', 'keyword', 'positioning'];
+export const PROBLEM_STATUSES = ['fixed', 'wont_fix', 'snoozed'];
+
+const SEVERITY_RANK = { critical: 0, warn: 1, info: 2 };
+
+/**
+ * Persist a problem-status mark. Same problem_id → upserts.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {{ problemId: string, project: string, status: string, markedBy?: string, note?: string, snoozeDays?: number }} args
+ * @returns {{ ok: boolean, error?: string, status?: string, expires_at?: number }}
+ */
+export function markProblemStatus(db, { problemId, project, status, markedBy, note, snoozeDays }) {
+  if (!PROBLEM_STATUSES.includes(status)) {
+    return { ok: false, error: `Unknown status "${status}". Allowed: ${PROBLEM_STATUSES.join(', ')}` };
+  }
+  if (!problemId || !project) return { ok: false, error: 'problemId and project are required' };
+  if (status === 'snoozed' && (!snoozeDays || snoozeDays <= 0)) {
+    return { ok: false, error: 'snoozeDays (positive integer) is required when status=snoozed' };
+  }
+  const now = Date.now();
+  const expiresAt = status === 'snoozed' ? now + snoozeDays * 86_400_000 : null;
+  db.prepare(`
+    INSERT INTO problem_status (problem_id, project, status, marked_at, marked_by, note, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(problem_id) DO UPDATE SET
+      status = excluded.status,
+      marked_at = excluded.marked_at,
+      marked_by = excluded.marked_by,
+      note = excluded.note,
+      expires_at = excluded.expires_at
+  `).run(problemId, project, status, now, markedBy || null, note || null, expiresAt);
+  return { ok: true, status, marked_at: now, expires_at: expiresAt };
+}
+
+/**
+ * Read all active status marks for a project. "Active" = not expired.
+ * Used internally by getProblems to filter; also exposed via MCP for inspection.
+ *
+ * @returns {Map<string, { status, marked_at, marked_by, note, expires_at }>}
+ */
+export function getActiveStatusMap(db, project) {
+  const now = Date.now();
+  const rows = db.prepare(`
+    SELECT problem_id, status, marked_at, marked_by, note, expires_at
+    FROM problem_status
+    WHERE project = ? AND (expires_at IS NULL OR expires_at > ?)
+  `).all(project, now);
+  return new Map(rows.map(r => [r.problem_id, r]));
+}
+
+function shortHash(str) {
+  return crypto.createHash('sha1').update(str).digest('hex').slice(0, 10);
+}
+
+function makeId(category, kind, key) {
+  return `${category}::${kind}::${shortHash(key)}`;
+}
+
+// ── Collectors (each returns Problem[]) ─────────────────────────────────────
+
+// 1. HTTP errors on target/owned pages — broken pages, critical
+function collectHttpErrors(db, project) {
+  const rows = db.prepare(`
+    SELECT p.url, p.status_code, p.crawled_at, p.first_seen_at, d.domain, d.role
+    FROM pages p JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ? AND d.role IN ('target', 'owned')
+      AND p.status_code >= 400 AND p.status_code < 600
+    ORDER BY p.status_code, p.url
+  `).all(project);
+  return rows.map(r => ({
+    id: makeId('tech', `http-${r.status_code}`, r.url),
+    severity: 'critical',
+    category: 'tech',
+    tier: 'free',
+    title: `${r.status_code} on ${shortPath(r.url)}`,
+    description: `Page returns HTTP ${r.status_code}. Search engines and AI crawlers will drop this URL.`,
+    affected_urls: [r.url],
+    evidence: { status_code: r.status_code, domain: r.domain, role: r.role },
+    fix_template: r.status_code === 404
+      ? `Either restore the page at \`${r.url}\` or add a 301 redirect to its replacement. Check internal links pointing here via \`get_pages\` and update them.`
+      : `Investigate why \`${r.url}\` returns ${r.status_code}. Server error, auth wall, or rate-limit. Restore 200 status or redirect.`,
+    verification: `Re-crawl with \`run_crawl(${project})\`, then re-run \`list_problems\` — this entry should disappear.`,
+    first_seen: r.first_seen_at || r.crawled_at,
+    last_seen: r.crawled_at,
+    fix_difficulty: r.status_code === 404 ? 2 : 4,
+  }));
+}
+
+// 2. Indexability — pages marked noindex via x_robots_tag header but indexable=1 in meta (conflict)
+//    OR pages explicitly noindex that have backlinks (wasted authority)
+function collectIndexabilityIssues(db, project) {
+  const xRobotsNoindex = db.prepare(`
+    SELECT p.url, p.x_robots_tag, p.is_indexable, p.crawled_at, p.first_seen_at, d.domain
+    FROM pages p JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ? AND d.role IN ('target', 'owned')
+      AND p.x_robots_tag IS NOT NULL
+      AND lower(p.x_robots_tag) LIKE '%noindex%'
+      AND p.is_indexable = 1
+  `).all(project);
+
+  const out = [];
+  for (const r of xRobotsNoindex) {
+    out.push({
+      id: makeId('indexability', 'robots-conflict', r.url),
+      severity: 'warn',
+      category: 'indexability',
+      tier: 'free',
+      title: `Robots header conflict on ${shortPath(r.url)}`,
+      description: `X-Robots-Tag header says noindex but the meta robots tag allows indexing. Search engines will follow the header — page won't be indexed.`,
+      affected_urls: [r.url],
+      evidence: { x_robots_tag: r.x_robots_tag, is_indexable_meta: !!r.is_indexable },
+      fix_template: `Decide which is canonical. Either remove \`X-Robots-Tag: noindex\` from the server response, or set \`<meta name="robots" content="noindex">\` so both agree. Check Cloudflare/nginx config if the header is unexpected.`,
+      verification: `Re-crawl and confirm \`x_robots_tag\` no longer contains noindex via \`get_pages\`.`,
+      first_seen: r.first_seen_at || r.crawled_at,
+      last_seen: r.crawled_at,
+      fix_difficulty: 3,
+    });
+  }
+  return out;
+}
+
+// 3. Orphan pages — target/owned pages on the site with no incoming internal links
+function collectOrphans(db, project) {
+  const rows = db.prepare(`
+    SELECT p.url, p.crawled_at, p.first_seen_at, p.click_depth, d.domain
+    FROM pages p JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ? AND d.role IN ('target', 'owned')
+      AND p.status_code = 200
+      AND p.click_depth > 0
+      AND p.url NOT IN (
+        SELECT DISTINCT l.target_url FROM links l
+        JOIN pages sp ON sp.id = l.source_id
+        JOIN domains sd ON sd.id = sp.domain_id
+        WHERE sd.project = ? AND l.is_internal = 1
+      )
+    ORDER BY p.click_depth, p.url
+    LIMIT 200
+  `).all(project, project);
+  return rows.map(r => ({
+    id: makeId('links', 'orphan', r.url),
+    severity: 'warn',
+    category: 'links',
+    tier: 'free',
+    title: `Orphan: ${shortPath(r.url)}`,
+    description: `No internal links point to this page. Search engines can only find it via sitemap; AI agents won't surface it.`,
+    affected_urls: [r.url],
+    evidence: { click_depth: r.click_depth, domain: r.domain },
+    fix_template: `Find 2–3 thematically related pages and add internal links to \`${r.url}\` from them. Use anchor text matching the page's primary keyword. Call \`get_pages(${project})\` to find candidates by topic, or \`list_keywords(${project})\` to find pages targeting overlapping keywords.`,
+    verification: `Re-crawl, then re-run \`list_problems\` — the orphan entry should be gone once any incoming link exists.`,
+    first_seen: r.first_seen_at || r.crawled_at,
+    last_seen: r.crawled_at,
+    fix_difficulty: 2,
+  }));
+}
+
+// 4. Schema coverage gaps — target pages missing schema where competitors have it
+function collectSchemaGaps(db, project) {
+  // Per-page: target pages with no page_schemas entries
+  const rows = db.prepare(`
+    SELECT p.url, p.title, p.word_count, p.crawled_at, p.first_seen_at, d.domain
+    FROM pages p JOIN domains d ON d.id = p.domain_id
+    WHERE d.project = ? AND d.role IN ('target', 'owned')
+      AND p.status_code = 200 AND p.word_count >= 300
+      AND p.id NOT IN (SELECT DISTINCT page_id FROM page_schemas)
+    ORDER BY p.word_count DESC
+    LIMIT 50
+  `).all(project);
+  return rows.map(r => ({
+    id: makeId('schema', 'missing', r.url),
+    severity: 'info',
+    category: 'schema',
+    tier: 'free',
+    title: `No schema on ${shortPath(r.url)}`,
+    description: `Substantive page (${r.word_count} words) ships zero structured-data markup. AI engines and rich-results lose out.`,
+    affected_urls: [r.url],
+    evidence: { word_count: r.word_count, title: r.title },
+    fix_template: `Add JSON-LD schema appropriate to the page type. Article / BlogPosting / Product / FAQPage / Organization are the common ones. Use \`get_headings(${project}, '${r.url}')\` to inspect the page structure first. Keep it short — 5–10 fields is enough.`,
+    verification: `Re-crawl, then \`get_intel(${project}, for=raw)\` should show schema count increment.`,
+    first_seen: r.first_seen_at || r.crawled_at,
+    last_seen: r.crawled_at,
+    fix_difficulty: 2,
+  }));
+}
+
+// 5. PAID — low-citability pages (AEO score < 40 in citability_scores table)
+function collectCitabilityGaps(db, project) {
+  let rows = [];
+  try {
+    rows = db.prepare(`
+      SELECT cs.url, cs.score, cs.tier, cs.entity_authority, cs.structured_claims,
+             cs.answer_density, cs.qa_proximity, cs.freshness, cs.schema_coverage,
+             cs.scored_at, p.title, p.word_count, d.role
+      FROM citability_scores cs
+      JOIN pages p ON p.id = cs.page_id
+      JOIN domains d ON d.id = p.domain_id
+      WHERE d.project = ? AND d.role IN ('target', 'owned') AND cs.score < 60
+      ORDER BY cs.score ASC
+      LIMIT 100
+    `).all(project);
+  } catch { /* citability_scores may not exist if AEO never run */ }
+  return rows.map(r => ({
+    id: makeId('citability', 'low-score', r.url),
+    severity: r.score < 30 ? 'critical' : r.score < 45 ? 'warn' : 'info',
+    category: 'citability',
+    tier: 'paid',
+    title: `Citability ${r.score}/100 on ${shortPath(r.url)}`,
+    description: `Page scores poorly for AI citability. Weak: ${weakestSignals(r)}.`,
+    affected_urls: [r.url],
+    evidence: {
+      score: r.score, tier: r.tier,
+      signals: {
+        entity_authority: r.entity_authority,
+        structured_claims: r.structured_claims,
+        answer_density: r.answer_density,
+        qa_proximity: r.qa_proximity,
+        freshness: r.freshness,
+        schema_coverage: r.schema_coverage,
+      },
+      word_count: r.word_count,
+    },
+    fix_template: citabilityFix(r),
+    verification: `Re-crawl, run \`run_citability_audit(${project})\`, then \`list_problems\` — score should rise.`,
+    first_seen: r.scored_at,
+    last_seen: r.scored_at,
+    fix_difficulty: 3,
+  }));
+}
+
+// 6. PAID — Intelligence Ledger insights mapped to problems
+function collectInsightProblems(db, project) {
+  let rows = [];
+  try {
+    rows = db.prepare(`
+      SELECT id, type, fingerprint, first_seen, last_seen, data, source
+      FROM insights
+      WHERE project = ? AND status = 'active'
+        AND type IN ('content_gap', 'keyword_gap', 'technical_gap', 'positioning')
+      ORDER BY last_seen DESC
+      LIMIT 100
+    `).all(project);
+  } catch { return []; }
+  return rows.map(r => {
+    const data = safeParse(r.data);
+    const typeMeta = INSIGHT_TYPE_MAP[r.type] || { category: 'content', severity: 'info' };
+    const titleHint = data?.keyword || data?.topic || data?.gap || data?.phrase || `Insight ${r.id}`;
+    return {
+      id: makeId(typeMeta.category, r.type, r.fingerprint),
+      severity: typeMeta.severity,
+      category: typeMeta.category,
+      tier: 'paid',
+      title: `${typeMeta.label}: ${titleHint}`,
+      description: data?.why || data?.description || `Active insight in the Intelligence Ledger (type=${r.type}).`,
+      affected_urls: data?.url ? [data.url] : (data?.pages || []),
+      evidence: { insight_id: r.id, source: r.source, ...data },
+      fix_template: data?.suggestion || data?.fix || `Address this ${r.type} via blog draft, page update, or content fix. Use \`draft_blog_prompt(${project}, topic='${titleHint}')\` for an AEO-aware draft prompt.`,
+      verification: `After the fix, call \`mark_problem_status('${makeId(typeMeta.category, r.type, r.fingerprint)}', 'fixed')\` (coming in v1.5.35) or wait for the next analyze run to clear it.`,
+      first_seen: r.first_seen,
+      last_seen: r.last_seen,
+      fix_difficulty: typeMeta.difficulty,
+    };
+  });
+}
+
+const INSIGHT_TYPE_MAP = {
+  content_gap:   { category: 'content',  severity: 'warn',  label: 'Content gap',   difficulty: 4 },
+  keyword_gap:   { category: 'keyword',  severity: 'warn',  label: 'Keyword gap',   difficulty: 3 },
+  technical_gap: { category: 'tech',     severity: 'warn',  label: 'Technical gap', difficulty: 3 },
+  positioning:   { category: 'positioning', severity: 'info', label: 'Positioning', difficulty: 5 },
+};
+
+// ── Aggregator ─────────────────────────────────────────────────────────────
+
+/**
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} project
+ * @param {{ severity?: string, category?: string, limit?: number, includePaid?: boolean, maxFixDifficulty?: number, includeMarked?: boolean }} opts
+ * @returns {object[]}
+ */
+export function getProblems(db, project, opts = {}) {
+  const all = [
+    ...collectHttpErrors(db, project),
+    ...collectIndexabilityIssues(db, project),
+    ...collectOrphans(db, project),
+    ...collectSchemaGaps(db, project),
+  ];
+  if (opts.includePaid) {
+    all.push(...collectCitabilityGaps(db, project));
+    all.push(...collectInsightProblems(db, project));
+  }
+  // Filter out problems marked fixed/wont_fix/snoozed (unless caller asks to see them).
+  const statusMap = getActiveStatusMap(db, project);
+  let filtered = all.flatMap(p => {
+    const mark = statusMap.get(p.id);
+    if (mark && !opts.includeMarked) return [];   // hide by default
+    return [{ ...p, status: mark ? mark.status : 'active', status_mark: mark || null }];
+  });
+  if (opts.severity) filtered = filtered.filter(p => p.severity === opts.severity);
+  if (opts.category) filtered = filtered.filter(p => p.category === opts.category);
+  if (opts.maxFixDifficulty) filtered = filtered.filter(p => p.fix_difficulty <= opts.maxFixDifficulty);
+  filtered.sort((a, b) =>
+    SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
+    a.fix_difficulty - b.fix_difficulty ||
+    b.last_seen - a.last_seen
+  );
+  if (opts.limit) filtered = filtered.slice(0, opts.limit);
+  return filtered;
+}
+
+/**
+ * Counts only — used by list_projects nag to surface "5 critical pending".
+ * Free tier sees free-only counts so we don't tease paid data.
+ */
+export function getProblemCounts(db, project, { includePaid = false } = {}) {
+  const problems = getProblems(db, project, { includePaid });
+  const counts = { critical: 0, warn: 0, info: 0, total: problems.length, by_category: {} };
+  for (const p of problems) {
+    counts[p.severity]++;
+    counts.by_category[p.category] = (counts.by_category[p.category] || 0) + 1;
+  }
+  return counts;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function shortPath(url) {
+  try {
+    const u = new URL(url);
+    const p = (u.pathname + u.search + u.hash).slice(0, 60);
+    return `${u.hostname}${p}`;
+  } catch { return url.slice(0, 60); }
+}
+
+function safeParse(s) { try { return JSON.parse(s); } catch { return null; } }
+
+function weakestSignals(r) {
+  const signals = [
+    ['entity authority', r.entity_authority],
+    ['structured claims', r.structured_claims],
+    ['answer density', r.answer_density],
+    ['Q&A proximity', r.qa_proximity],
+    ['freshness', r.freshness],
+    ['schema coverage', r.schema_coverage],
+  ];
+  return signals.sort((a, b) => a[1] - b[1]).slice(0, 2).map(s => s[0]).join(' + ');
+}
+
+function citabilityFix(r) {
+  const fixes = [];
+  if (r.entity_authority < 4)   fixes.push('cite 2–3 named experts/authoritative sources');
+  if (r.structured_claims < 4)  fixes.push('add concrete numbers, dates, or measurable claims (e.g. "47ms latency")');
+  if (r.answer_density < 4)     fixes.push('shorten paragraphs; one answer per heading');
+  if (r.qa_proximity < 4)       fixes.push('add an FAQ section with `FAQPage` schema');
+  if (r.freshness < 4)          fixes.push('update the publish date and add a brief "last updated" note');
+  if (r.schema_coverage < 4)    fixes.push('add JSON-LD schema appropriate to the page type');
+  return fixes.length
+    ? `To raise score: ${fixes.join('; ')}.`
+    : `Page just under threshold — minor improvements suffice. Use \`prescore_draft\` on a revised version to confirm before publishing.`;
+}

package/mcp/server.js

@@ -29,6 +29,7 @@ import { getDb, insertAgentInsight, AGENT_INSIGHT_TYPES, getActiveInsights, getC
 import { getIntel, INTEL_SLICES, FREE_SLICES } from '../lib/intel.js';
 import { isPro } from '../lib/license.js';
 import { readProgress } from '../lib/progress.js';
+import { getProblems, getProblemCounts, markProblemStatus, getActiveStatusMap, PROBLEM_CATEGORIES, PROBLEM_STATUSES } from '../lib/problems.js';
 
 import { runAeoAnalysis, persistAeoScores, upsertCitabilityInsights } from '../analyses/aeo/index.js';
 import { prescore } from '../analyses/blog-draft/prescorer.js';
@@ -69,19 +70,50 @@ function listConfigProjects() {
 }
 
 // ── Tool: list_projects (free) ────────────────────────────────────────────
+// Designed as the natural entry point. Returns per-project pending problem
+// counts so that every interaction with the agent surfaces stale audits —
+// the "freemium nag" pattern. Solo users see paid-tier problem counts too.
 server.registerTool(
   'list_projects',
   {
-    description: 'List all SEO Intel projects configured on this machine, each with its target domain and crawled page count. Use this first to discover which projects are available before calling get_intel. Free tier — no license required.',
+    description: 'List all SEO Intel projects on this machine with crawled-page counts AND pending problem counts. Use this as the entry point for every SEO conversation — the response includes a `nag` field per project flagging stale crawls or unresolved critical issues. After noticing the nag, the next natural tool is list_problems(project). Free tier — no license required (Solo users see paid-tier problem counts in addition to free ones).',
   },
   async () => {
     const db = getDb();
     const configs = listConfigProjects();
+    const includePaid = isPro();
+    const now = Date.now();
     const out = configs.map(c => {
       const row = db.prepare(
-        'SELECT COUNT(*) AS n FROM pages p JOIN domains d ON d.id=p.domain_id WHERE d.project=?'
+        'SELECT COUNT(*) AS n, MAX(d.last_crawled) AS last_crawled FROM pages p JOIN domains d ON d.id=p.domain_id WHERE d.project=?'
       ).get(c.project);
-      return { ...c, pages: row?.n || 0 };
+      const pages = row?.n || 0;
+      const lastCrawl = row?.last_crawled || null;
+      const staleDays = lastCrawl ? Math.floor((now - lastCrawl) / 86_400_000) : null;
+      let counts = null;
+      let nag = null;
+      if (pages > 0) {
+        try {
+          counts = getProblemCounts(db, c.project, { includePaid });
+          const reasons = [];
+          if (counts.critical > 0) reasons.push(`${counts.critical} CRITICAL`);
+          if (counts.warn > 0) reasons.push(`${counts.warn} warn`);
+          if (staleDays !== null && staleDays >= 7) reasons.push(`crawl ${staleDays}d stale`);
+          if (reasons.length) {
+            nag = `${reasons.join(' · ')}. Call list_problems('${c.project}') to see them${counts.critical > 0 ? ', then fix the criticals first' : ''}.`;
+          }
+        } catch { /* problems collector failed (e.g. fresh DB) — silent */ }
+      }
+      return {
+        project: c.project,
+        target: c.target,
+        pages,
+        last_crawled: lastCrawl ? new Date(lastCrawl).toISOString() : null,
+        stale_days: staleDays,
+        problem_counts: counts,
+        nag,
+        problems_tier: includePaid ? 'paid' : 'free',
+      };
     });
     return {
       content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
@@ -675,11 +707,134 @@ server.registerTool(
   }
 );
 
+// ── Tool: list_problems (the "what should I fix?" entry tool) ─────────────
+// This is the canonical Problems surface. Returns severity-sorted, agent-
+// fixable findings with affected_urls, fix_template, verification. Free
+// categories: tech, indexability, links, schema. Paid adds: citability,
+// content, keyword, positioning.
+server.registerTool(
+  'list_problems',
+  {
+    description: [
+      "List concrete, fixable SEO problems for a project — severity-sorted, with everything an AI coding agent needs to remediate (affected_urls, fix_template, verification). This is the primary 'what should I work on?' tool: call list_projects first to see the nag/counts, then call list_problems here.",
+      "",
+      "Free tier categories: tech (HTTP errors), indexability (robots conflicts), links (orphan pages), schema (missing structured data).",
+      "Paid tier adds: citability (low AEO scores), content/keyword/positioning gaps from the Intelligence Ledger.",
+      "",
+      "Each problem returns {id, severity, category, tier, title, description, affected_urls, evidence, fix_template, verification, first_seen, last_seen, fix_difficulty}. fix_difficulty: 1=trivial → 5=deep work.",
+      "",
+      "Typical agent loop: list_projects → list_problems(project, severity='critical') → fix highest-leverage one → run_crawl(project) → list_problems again to verify it cleared.",
+    ].join("\n"),
+    inputSchema: {
+      project: z.string(),
+      severity: z.enum(['critical', 'warn', 'info']).optional().describe('Filter to one severity'),
+      category: z.enum(PROBLEM_CATEGORIES).optional().describe('Filter to one category'),
+      limit: z.number().int().positive().max(500).optional().describe('Max problems to return (default 50)'),
+      max_fix_difficulty: z.number().int().min(1).max(5).optional().describe('Cap on fix_difficulty — useful for picking quick wins (set to 2 for "easy" only)'),
+      include_marked: z.boolean().optional().describe('Include problems already marked fixed/wont_fix/snoozed (default false — they are hidden). Useful for auditing what has been suppressed.'),
+    },
+  },
+  async ({ project, severity, category, limit = 50, max_fix_difficulty, include_marked }) => {
+    if (!loadProjectConfig(project)) {
+      return { content: [{ type: 'text', text: `Project "${project}" not found. Use list_projects to discover.` }], isError: true };
+    }
+    try {
+      const db = getDb();
+      const includePaid = isPro();
+      const problems = getProblems(db, project, {
+        severity, category, limit,
+        maxFixDifficulty: max_fix_difficulty,
+        includePaid,
+        includeMarked: !!include_marked,
+      });
+      const counts = getProblemCounts(db, project, { includePaid });
+      const out = {
+        project,
+        tier: includePaid ? 'paid' : 'free',
+        counts,
+        returned: problems.length,
+        filters: { severity: severity || 'any', category: category || 'any', max_fix_difficulty: max_fix_difficulty || null },
+        upsell: includePaid ? null : 'Solo unlocks citability, content_gap, keyword_gap, positioning categories. Currently showing free-tier categories only (tech, indexability, links, schema). Upgrade at https://ukkometa.fi/en/seo-intel/',
+        problems,
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+        structuredContent: out,
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Tool: mark_problem_status (free — closes the loop) ────────────────────
+server.registerTool(
+  'mark_problem_status',
+  {
+    description: [
+      "Mark a problem (from list_problems) as fixed, wont_fix, or snoozed. Subsequent list_problems calls will hide it unless the underlying source data re-surfaces it. Free tier — agents need this to confirm 'I fixed it' on subjective problems (positioning, content_gap) whose source data won't auto-clear on re-crawl.",
+      "",
+      "Statuses:",
+      "  fixed     — done. Hide permanently. (If the same problem_id resurfaces from a future crawl, the mark is ignored and it shows again — i.e. the mark is per-instance not per-fingerprint.)",
+      "  wont_fix  — accepted/ignored. Hide permanently.",
+      "  snoozed   — hide for N days (require `snooze_days`). After that the problem re-appears in list_problems.",
+      "",
+      "Re-marking the same problem_id with a different status updates the existing record. To un-hide, re-mark with status='fixed' and snooze_days=0, then re-mark with 'snoozed' / snooze_days=0 — actually simpler: call list_problems(include_marked=true) to see hidden ones and mark them again.",
+    ].join("\n"),
+    inputSchema: {
+      problem_id: z.string().describe('The `id` field from a list_problems result, e.g. "links::orphan::abc1234567"'),
+      project: z.string().describe('Must match the project the problem belongs to'),
+      status: z.enum(PROBLEM_STATUSES).describe('fixed | wont_fix | snoozed'),
+      snooze_days: z.number().int().positive().max(365).optional().describe('Required when status=snoozed. Max 365.'),
+      agent_name: z.string().optional().describe('Provenance — stored as marked_by'),
+      note: z.string().optional().describe('Optional context, e.g. "added internal link from homepage"'),
+    },
+  },
+  async ({ problem_id, project, status, snooze_days, agent_name, note }) => {
+    if (!loadProjectConfig(project)) {
+      return { content: [{ type: 'text', text: `Project "${project}" not found. Use list_projects to discover.` }], isError: true };
+    }
+    try {
+      const db = getDb();
+      const result = markProblemStatus(db, {
+        problemId: problem_id,
+        project,
+        status,
+        markedBy: agent_name ? `agent:${agent_name}` : 'agent',
+        note,
+        snoozeDays: snooze_days,
+      });
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `seo-intel mark error: ${result.error}` }], isError: true };
+      }
+      const payload = {
+        ok: true,
+        problem_id,
+        project,
+        status,
+        marked_at: new Date(result.marked_at).toISOString(),
+        expires_at: result.expires_at ? new Date(result.expires_at).toISOString() : null,
+        hint: status === 'fixed'
+          ? 'Marked fixed. Hidden from list_problems. Re-call list_problems to confirm.'
+          : status === 'wont_fix'
+          ? 'Marked wont_fix. Permanently hidden. To un-hide: call this tool again with a different status.'
+          : `Snoozed until ${new Date(result.expires_at).toISOString()}. Will re-appear in list_problems after that.`,
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   // stderr is fine; the host typically surfaces this in its MCP logs panel.
-  console.error(`[seo-intel-mcp] v${VERSION} ready on stdio. 13 tools — free: list_projects, get_intel(raw), get_pages, list_keywords, get_headings, run_crawl, get_crawl_status, ingest_insight, export_intel (free-tier subset); paid: get_intel(audit/blog/competitor), run_citability_audit, get_competitor_positioning, prescore_draft, draft_blog_prompt, export_intel (paid tables).`);
+  console.error(`[seo-intel-mcp] v${VERSION} ready on stdio. 15 tools — free: list_projects (with nag), list_problems, mark_problem_status, get_intel(raw), get_pages, list_keywords, get_headings, run_crawl, get_crawl_status, ingest_insight, export_intel (free-tier subset); paid: get_intel(audit/blog/competitor), run_citability_audit, get_competitor_positioning, prescore_draft, draft_blog_prompt, export_intel (paid tables), and list_problems unlocks paid categories.`);
 }
 
 main().catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-intel",
-  "version": "1.5.33",
+  "version": "1.5.38",
   "description": "Local Ahrefs-style SEO competitor intelligence. Crawl → SQLite → cloud analysis.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/setup/checks.js

@@ -80,15 +80,29 @@ export async function checkOllamaRemote(host) {
 export async function checkLmStudio(customUrl) {
   const host = customUrl || process.env.LMSTUDIO_URL || 'http://localhost:1234';
 
+  // LM Studio exposes TWO model endpoints with DIFFERENT response shapes:
+  //   /v1/models        OpenAI-compatible → { data: [{ id }] }
+  //   /api/v1/models    LM Studio native  → { models: [{ key, loaded_instances }] }
+  // Try OpenAI-compat first (standard, smaller payload, listed under "OpenAI-
+  // compatible" tab in LM Studio Developer panel). Fall back to the native
+  // endpoint if the OpenAI one isn't enabled. Parse both shapes.
   try {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 3000);
-    const res = await fetch(`${host}/api/v1/models`, { signal: controller.signal });
+    let res = await fetch(`${host}/v1/models`, { signal: controller.signal });
+    if (!res.ok) {
+      // OpenAI-compat path off — try LM Studio native
+      res = await fetch(`${host}/api/v1/models`, { signal: controller.signal });
+    }
     clearTimeout(timeout);
 
     if (!res.ok) return { reachable: false, models: [], host };
-    const data = await res.json().catch(() => ({ data: [] }));
-    const models = (data.data || []).map(m => m.id || m.model).filter(Boolean);
+    const data = await res.json().catch(() => ({}));
+    // Support both shapes: OpenAI `data[]` and LM Studio native `models[]`.
+    const list = Array.isArray(data.data) ? data.data
+               : Array.isArray(data.models) ? data.models
+               : [];
+    const models = list.map(m => m.id || m.key || m.model || m.name).filter(Boolean);
     return { reachable: true, models, host };
   } catch {
     return { reachable: false, models: [], host };

package/setup/web-routes.js

@@ -314,25 +314,27 @@ async function handlePingOllama(req, res) {
 
     const { checkOllamaRemote, checkLmStudio } = await import('./checks.js');
 
-    // Try Ollama first, then LM Studio if port suggests it or Ollama fails
-    const port = new URL(host).port;
-    if (port === '1234') {
-      // Port 1234 = LM Studio default
-      const lmResult = await checkLmStudio(host);
+    // Probe BOTH engines in parallel. Whichever responds, that's the engine.
+    // Don't gate on port — users can run Ollama on 1234 or LM Studio on 11434
+    // (and many do, e.g. when avoiding port conflicts on shared dev boxes).
+    const [ollamaResult, lmResult] = await Promise.all([
+      checkOllamaRemote(host).catch(() => ({ reachable: false, models: [], host })),
+      checkLmStudio(host).catch(() => ({ reachable: false, models: [], host })),
+    ]);
+
+    if (ollamaResult.reachable) {
+      jsonResponse(res, { ...ollamaResult, mode: 'ollama' });
+    } else if (lmResult.reachable) {
       jsonResponse(res, { ...lmResult, host, mode: 'lmstudio' });
     } else {
-      const result = await checkOllamaRemote(host);
-      if (result.reachable) {
-        jsonResponse(res, result);
-      } else {
-        // Ollama unreachable — try LM Studio as fallback
-        const lmResult = await checkLmStudio(host);
-        if (lmResult.reachable) {
-          jsonResponse(res, { ...lmResult, host, mode: 'lmstudio' });
-        } else {
-          jsonResponse(res, result); // return original Ollama failure
-        }
-      }
+      // Neither engine responded — return a useful error.
+      const port = (() => { try { return new URL(host).port; } catch { return ''; } })();
+      jsonResponse(res, {
+        reachable: false,
+        host,
+        probed: { ollama: `${host}/api/tags`, lmstudio: `${host}/api/v1/models` },
+        hint: `Neither Ollama (port ${port || '11434'} expected) nor LM Studio (port ${port || '1234'} expected) responded at ${host}. Common causes: (1) the engine is bound to 127.0.0.1 only — re-bind to 0.0.0.0 to allow LAN access, (2) firewall blocking inbound port ${port || 'N'}, (3) wrong port. Verify from the LM Studio Developer tab / 'ollama serve' output.`,
+      });
     }
   } catch (err) {
     jsonResponse(res, { error: err.message }, 500);

package/setup/wizard.html

@@ -2274,7 +2274,9 @@ input::placeholder {
     let host = input.value.trim();
     if (!host) return;
 
-    // Auto-add protocol and port
+    // Auto-add protocol. Don't auto-add a default port — LM Studio uses 1234,
+    // Ollama uses 11434. If the user pasted without a port, default to Ollama's
+    // 11434 but the probe will also try LM Studio at 1234 if Ollama fails.
     if (!host.startsWith('http')) host = 'http://' + host;
     if (!host.includes(':', host.indexOf('//') + 2)) host += ':11434';
 
@@ -2285,8 +2287,9 @@ input::placeholder {
     try {
       const res = await API.get(`/api/setup/ping-ollama?host=${encodeURIComponent(host)}`);
       if (res.reachable) {
-        result.innerHTML = `<span style="color:var(--color-success);"><i class="fa-solid fa-check"></i> Connected — ${res.models.length} model(s) found</span>`;
-        // Append to comma-separated OLLAMA_HOSTS in .env
+        const engine = res.mode === 'lmstudio' ? 'LM Studio' : 'Ollama';
+        result.innerHTML = `<span style="color:var(--color-success);"><i class="fa-solid fa-check"></i> Connected to ${engine} — ${res.models.length} model(s) found</span>`;
+        // Append to comma-separated OLLAMA_HOSTS in .env (legacy name covers both engines)
         const currentHosts = (state.systemStatus?.env?.raw?.OLLAMA_HOSTS || '').split(',').map(h => h.trim()).filter(Boolean);
         if (!currentHosts.includes(host)) currentHosts.push(host);
         await API.post('/api/setup/save-env', { key: 'OLLAMA_HOSTS', value: currentHosts.join(',') });
@@ -2298,7 +2301,9 @@ input::placeholder {
         // Reload models with new host
         loadModels();
       } else {
-        result.innerHTML = `<span style="color:var(--color-danger);"><i class="fa-solid fa-xmark"></i> Unreachable — check IP, port, and that Ollama is running on that machine</span>`;
+        // Better diagnostic — backend now returns a `hint` with common-cause guidance
+        const hint = res.hint || `Check IP, port, and that Ollama (port 11434) or LM Studio (port 1234) is running on that machine and bound to a network interface (not just 127.0.0.1).`;
+        result.innerHTML = `<span style="color:var(--color-danger);"><i class="fa-solid fa-xmark"></i> Unreachable — ${escapeHtml(hint)}</span>`;
       }
     } catch (err) {
       result.innerHTML = `<span style="color:var(--color-danger);"><i class="fa-solid fa-xmark"></i> ${err.message}</span>`;
@@ -2307,6 +2312,11 @@ input::placeholder {
     btn.innerHTML = '<i class="fa-solid fa-satellite-dish"></i> Ping';
   };
 
+  // Light HTML escape so backend-supplied hint strings can't break out
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+  }
+
   window.removeOllamaHost = async function(host) {
     // Remove single host from comma-separated OLLAMA_HOSTS
     const currentHosts = (state.systemStatus?.env?.raw?.OLLAMA_HOSTS || '').split(',').map(h => h.trim()).filter(Boolean);