formlab-mcp 0.6.35 → 0.6.37

package/README.md

@@ -37,7 +37,7 @@ Ask Claude (or another MCP client) things like:
 | `list_lots` | Inventory lots across ingredients (each a received batch with its own remaining balance, supplier, expiry, **unit cost**, **status** — `active` / `hold` / `quarantine` / `rejected`; held lots are blocked from consumption, with a `holdReason` — and the **approved source** it was received from: `source.supplier` + `source.manufacturer`, where recalls hinge on the manufacturer). Each lot also reports its **Certificate of Analysis** (`coa`: linked, or matched by lot number) and `coaMissing` for an in-stock lot without one. Filters: `ingredient_id`, `expiring_within_days`, `status` (e.g. `hold` to find lots held for a recall), `missing_coa` |
 | `list_suppliers` | Supplier / manufacturer records with roll-ups — ingredients approved, lots received / on hand (+ value at paid cost), qualified / trial / disqualified source counts, last receipt; lots count by supplier **and** by manufacturer |
 | `get_supplier` | One supplier in full: record, every ingredient it's an approved source for, every lot from it, and the **recall trace** (batches that consumed those lots → products, shipments, samples, sub-batches; lots on hold flagged) |
-| `list_documents` | The document register (same as the app's Documents page): ingredient SDS / PDS / CoA / other with lot, version, source and expiry; test and notebook attachments; per-record uploads and links (formulas, batches, samples, suppliers, equipment…). File **metadata** only, never the text inside a file. Filters: `type`, `record`, `linked`, `query`, `lot`, `format`, `expiry`, `expiring_within_days`, `without_expiry`, `uploaded_within_days`. A `summary` block carries the page's tile counts: expired, expiring in 30 days, SDS/CoA without expiry, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, added last 7 days |
+| `list_documents` | The document register (same as the app's Documents page): ingredient SDS / PDS / CoA / other with lot, version, source and expiry; test and notebook attachments; per-record uploads and links (formulas, batches, samples, suppliers, equipment…). File **metadata** only, never the text inside a file, with who added each file (`addedBy`) and when. Filters: `type`, `record`, `linked`, `query`, `lot`, `format`, `expiry`, `expiring_within_days`, `without_expiry`, `uploaded_within_days`, `added_by`. A `summary` block carries the page's tile counts: expired, expiring in 30 days, SDS/CoA without expiry, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, added last 7 days |
 | `list_inventory` | Portfolio stock rollup — one row per ingredient with on-hand qty, summed lot balance, nearest expiry, and a low-stock flag (on-hand ≤ `reorderThreshold`, or zero). Filters: `low_stock_only`, `expiring_within_days`, `family` |
 | `list_batches` | Filtered list of production / lab-prep events |
 | `get_batch` | Full record + actual composition, measured/derived **actual volume** (mass ÷ density, never a sum of per-ingredient volumes) and **actual mass** (yield, else summed as-prepared inputs — mL rows through that ingredient's density — else measured volume × density), **estimatedVolume** (mass ÷ the formula's finished density when no actual exists, flagged `estimate: true`), **plannedMass** for volume-target batches (target × finished density) and **formulaFinishedDensity**, the **process** method + any **process-factor values** (DOE inputs), samples + blend lineage, and — as a finished-goods lot — its storage **`location`** + finished-goods **`stockLedger`** (shipments out + adjustments; `shippedQty` total) |
@@ -52,7 +52,7 @@ Ask Claude (or another MCP client) things like:
 | `get_batch_pivot` | Production analytics — aggregate batches by `group_by` (formula / status / month / prepared_by / project) × `metric` (count, avg_yield_pct, total_produced_kg, avg_cost_per_batch, total_samples, total_tests), with share + total for additive metrics. Optional `batch_uids` scope + `status` filter |
 | `get_project_pivot` | Portfolio analytics — aggregate projects by `group_by` (status / phase / priority / business_unit / site / customer / lead, or `cf:<custom field>`) × `metric` (count, total_formulas / batches / samples, total_cost, avg_formulas / batches / cost_per_batch), rolling child activity + cost up by any project attribute. Optional `project_uids` scope |
 | `get_stability` | Grounded stability / shelf-life analysis for a formulation, sample or batch × parameter (auto-detected): time-series, drift (per-month slope + R²), an I-chart (mean ±3σ + out-of-control points), spec status, and an ICH-Q1E-flavored projected shelf life (point + 95%-CI crossing), all on **one point per test date per run condition** (replicates averaged, never separate time points), split by storage condition |
-| `get_design_space` | COMPOSITION design space for one project: which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested **interior gap** as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised **2-component PCA** of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
+| `get_design_space` | COMPOSITION design space for one project, several (`projects`) or any formula list (`formulas`, across projects — like the app's Scope → DOE Matrix): which ingredients vary and over what observed wt-% ranges (ranked), an occupied-region summary ("where you've been"), the biggest untested **interior gap** as ready-to-seed DOE ranges (a combination you could have made but skipped), and an optional standardised **2-component PCA** of all varying ingredients — loadings, variance-explained, scree, and a full-dimensional gap. Optional `axes` (choose the 2–3 axes), `by_role` (map ingredients summed by primary Function, e.g. Pigment / Solvent / Film Former — no gap, roles aren't DOE factors) and `property` (highest / lowest formula plus the ingredients whose level tracks it, Spearman ρ). Reports formulas that aren't on the map and the spread on it. Matches the in-app Design Space Viewer exactly. Answers *"where haven't I explored?"* / *"what should I formulate next?"* |
 | `list_doe_designs` | Saved DOE designs — the *recipe* behind each batch of runs: design type, factors + ranges, constraints, run count, D-efficiency. Filters: `project`, `design_type`, `constrained_only`, `name_contains` |
 | `get_doe_design` | One design in full: constraints in plain language, the model it was optimised for, generation settings (run budget, replicates, centre points, seed) and the complete run matrix with the formulation each run became |
 | `find_by_smarts` | SMARTS-pattern substructure search across every ingredient with a SMILES; peptides that only store a sequence are searched with the structure derived from it, as the app draws them (`smilesDerived: true`). Requires `@rdkit/rdkit` (optional dependency — install with `npm install @rdkit/rdkit` in `mcp/` if you get a "not installed" error). Examples: `c1ccccc1` (any aromatic 6-ring), `[OX2H1]` (any hydroxyl), `C(=O)O` (carboxylic acid), `[F,Cl,Br,I]` (any halogen). |
@@ -66,8 +66,8 @@ Ask Claude (or another MCP client) things like:
 | `get_test_panel` | One Test Panel: ordered parameters with resolved method UIDs + specs, plus `usage` (reports created from it) and `performanceByParameter` |
 | `list_projects` | Filtered list of projects (the buckets formulations are filed under) + per-project formulation count. Filters: `status`, `name_contains` |
 | `get_project` | Full project record + the formulations filed under it |
-| `list_notebook_entries` | ELN feed — dated authored notes attached to records. Filters: `entity_type`, `entity_id`, `author`, `text_contains`, `since`, `until` |
-| `get_notebook_entry` | One notebook entry — full body, author, attachment metadata, resolved linked record |
+| `list_notebook_entries` | ELN feed — dated authored notes attached to records. Append-only: a withdrawn note is kept with `retracted` = {at, by, reason}. Filters: `entity_type`, `entity_id`, `author`, `text_contains`, `since`, `until`, `retracted` |
+| `get_notebook_entry` | One notebook entry — full body, author, attachment metadata, resolved linked record, and `retracted` when withdrawn |
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "formlab-mcp",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "mcpName": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only Model Context Protocol server for FormLab \u2014 lets Claude (and other MCP clients) read and analyze your FormLab data, from a local export file OR your live cloud workspace.",
   "type": "module",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.juliu1980/formlab-mcp",
   "description": "Read-only MCP for FormLab — let Claude query your formulation lab. Free reads a local export; Pro connects to your live cloud workspace with a dedicated read-only token.",
-  "version": "0.6.35",
+  "version": "0.6.37",
   "websiteUrl": "https://formvix.com/mcp",
   "repository": {
     "url": "https://github.com/juliu1980/FormLab",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "formlab-mcp",
-      "version": "0.6.35",
+      "version": "0.6.37",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/tools/designspace.js

@@ -292,14 +292,87 @@ function _eligibleProjects(db) {
   return out;
 }
 
+// ---- scope, roles, property insights (ports of the app's build 26p–26s) -----
+
+// Resolve a list of formula ids / UIDs / names (exact name first, then substring).
+function _resolveFormulas(list, db) {
+  const norm = (s) => String(s || '').toLowerCase();
+  const out = [], missing = [];
+  (list || []).forEach(q => {
+    const f = resolveById('formulations', q)
+      || (db.formulations || []).find(x => x && norm(x.name) === norm(q))
+      || (db.formulations || []).find(x => x && norm(x.name).includes(norm(q)));
+    if (f && !f._trashed) { if (!out.includes(f)) out.push(f); } else missing.push(q);
+  });
+  return { forms: out, missing };
+}
+function _resolveProject(q, db) {
+  const norm = (s) => String(s || '').toLowerCase();
+  return resolveById('projects', q)
+    || (db.projects || []).find(p => norm(p.name) === norm(q))
+    || (db.projects || []).find(p => norm(p.name).includes(norm(q)));
+}
+// Primary Function role per ingredient ("Pigment|Opacifier" → "Pigment").
+function _roleMap(db) {
+  const m = new Map();
+  (db.ingredients || []).forEach(i => { const r = i && i.function ? String(i.function).split('|')[0].trim() : ''; if (r) m.set(i.id, r); });
+  return m;
+}
+// Per-formula role totals (wt% summed by role), as a map shaped like the
+// ingredient maps so the same geometry helpers work on it (keys 'role:<name>').
+function _roleMaps(forms, mapsByForm, db) {
+  const rm = _roleMap(db), out = new Map();
+  forms.forEach(f => {
+    const m = mapsByForm.get(f.id) || new Map(), t = new Map();
+    m.forEach((v, id) => { const r = rm.get(id); if (r && Number.isFinite(v)) t.set('role:' + r, (t.get('role:' + r) || 0) + v); });
+    out.set(f.id, t);
+  });
+  return out;
+}
+// Roles that vary, ranked by ABSOLUTE spread (the app's _asmDsRoleCands) — the
+// big building blocks first, not a small role that swings a lot relatively.
+function _roleCandidates(forms, roleMaps) {
+  const by = new Map();
+  forms.forEach(f => (roleMaps.get(f.id) || new Map()).forEach((v, id) => { if (!by.has(id)) by.set(id, []); by.get(id).push(v); }));
+  const out = [];
+  by.forEach((a, id) => {
+    if (a.length < 2) return;
+    const min = Math.min(...a), max = Math.max(...a), spread = max - min;
+    if (spread <= 0.01) return;
+    const mean = a.reduce((x, y) => x + y, 0) / a.length;
+    out.push({ id, name: id.slice(5), role: true, obs: { min, max, mean, n: a.length }, spread, rel: mean > 0 ? spread / mean : 0, score: spread });
+  });
+  return out.sort((a, b) => b.score - a.score);
+}
+// A formula's value for a measured parameter: the mean of every numeric
+// reading of it across the formula's samples (the app's _asmFormulaValueForCol).
+function _paramValue(f, param, db) {
+  const sids = new Set((db.samples || []).filter(s => s.formulationId === f.id).map(s => s.id));
+  const vals = [];
+  (db.testResults || []).forEach(t => { if (!sids.has(t.sampleId)) return; (t.measurements || []).forEach(m => { if (m.parameter === param) { const v = parseFloat(m.value); if (!isNaN(v)) vals.push(v); } }); });
+  return vals.length ? vals.reduce((a, b) => a + b, 0) / vals.length : null;
+}
+function _spearman(xs, ys) {
+  const rank = (a) => { const idx = a.map((v, i) => [v, i]).sort((p, q) => p[0] - q[0]); const r = new Array(a.length); let i = 0; while (i < idx.length) { let j = i; while (j + 1 < idx.length && idx[j + 1][0] === idx[i][0]) j++; const avg = (i + j) / 2 + 1; for (let k = i; k <= j; k++) r[idx[k][1]] = avg; i = j + 1; } return r; };
+  const rx = rank(xs), ry = rank(ys), n = xs.length;
+  const mx = rx.reduce((a, b) => a + b, 0) / n, my = ry.reduce((a, b) => a + b, 0) / n;
+  let sxx = 0, syy = 0, sxy = 0; for (let i = 0; i < n; i++) { const dx = rx[i] - mx, dy = ry[i] - my; sxx += dx * dx; syy += dy * dy; sxy += dx * dy; }
+  return (sxx && syy) ? sxy / Math.sqrt(sxx * syy) : null;
+}
+
 const get_design_space = {
   definition: {
     name: 'get_design_space',
-    description: 'Map a project\'s COMPOSITION design space (the descriptive mirror of the DOE designer, and the composition-space counterpart to get_coverage_matrix\'s TEST coverage). For one project it returns: the ingredients that actually VARY across its formulas + their observed wt-% ranges (ranked by proportional swing); an occupied-region summary ("where you\'ve been"); the biggest untested INTERIOR gap — a combination you could have made but skipped, kept inside the occupied cloud — expressed as ready-to-seed DOE ingredient ranges (low/high %); and, when the project has ≥3 varying ingredients, a standardised 2-component PCA of ALL of them: per-axis ingredient loadings, variance-explained, a scree list, and a full-dimensional gap. Numbers match FormLab\'s in-app Design Space Viewer exactly. Use it to answer "where haven\'t I explored?" / "what should I formulate next?" and to hand a chemist an experiment target. Read-only.',
+    description: 'Map a project\'s COMPOSITION design space (the descriptive mirror of the DOE designer, and the composition-space counterpart to get_coverage_matrix\'s TEST coverage). For one project it returns: the ingredients that actually VARY across its formulas + their observed wt-% ranges (ranked by proportional swing); an occupied-region summary ("where you\'ve been"); the biggest untested INTERIOR gap — a combination you could have made but skipped, kept inside the occupied cloud — expressed as ready-to-seed DOE ingredient ranges (low/high %); and, when the project has ≥3 varying ingredients, a standardised 2-component PCA of ALL of them: per-axis ingredient loadings, variance-explained, a scree list, and a full-dimensional gap. Numbers match FormLab\'s in-app Design Space Viewer exactly. Scope can be one project, several (projects), or any formula list (formulas); axes can be chosen (axes) or mapped by ingredient role (by_role); property adds best/worst formula and the ingredient that tracks it. Use it to answer "where haven\'t I explored?" / "what should I formulate next?" and to hand a chemist an experiment target. Read-only.',
     inputSchema: {
       type: 'object',
       properties: {
-        project: { type: 'string', description: 'Project id, UID, or name (case-insensitive; substring allowed). Omit to auto-pick the most-populated eligible project (≥3 formulas).' },
+        project: { type: 'string', description: 'Project id, UID, or name (case-insensitive; substring allowed). Omit (and omit projects/formulas) to auto-pick the most-populated eligible project (≥3 formulas).' },
+        projects: { type: 'array', items: { type: 'string' }, description: 'Map several projects together (ids, UIDs or names) — the app\'s cross-project scope. Ingredients most of the formulas share are ranked first.' },
+        formulas: { type: 'array', items: { type: 'string' }, description: 'Map exactly these formulas (ids, UIDs or names), from any projects — like the app\'s "Scope → DOE Matrix". Overrides project/projects.' },
+        axes: { type: 'array', items: { type: 'string' }, description: 'Choose the 2 or 3 axes yourself (ingredient names/ids, or role names with by_role) instead of the most-varying ones. Each must vary in the scope.' },
+        by_role: { type: 'boolean', description: 'Map ROLES instead of single ingredients: each formula\'s ingredients summed by their primary Function (e.g. Pigment / Solvent / Film Former), ranked by absolute spread. No gap is reported (roles are not DOE factors).' },
+        property: { type: 'string', description: 'A measured parameter name (e.g. "Gloss @60°"). Adds insights over the formulas on the map: highest and lowest formula, and the varying ingredient whose level tracks it most (Spearman ρ; a correlation, not a cause).' },
         include_pca: { type: 'boolean', description: 'Include the "map everything" PCA of all varying ingredients (loadings + variance + full-dimensional gap). Default true. Needs ≥3 varying ingredients and ≥3 formulas.' },
         loadings_per_component: { type: 'number', description: 'How many top ingredient loadings to list per principal component. Default 5, max 20.' },
       },
@@ -309,34 +382,54 @@ const get_design_space = {
     const { db } = getStore();
     const norm = (s) => String(s || '').toLowerCase();
 
-    // Resolve the project (explicit pick, else the most-populated eligible one).
-    let proj = null;
-    if (args.project) {
-      proj = resolveById('projects', args.project)
-        || (db.projects || []).find(p => norm(p.name) === norm(args.project))
-        || (db.projects || []).find(p => norm(p.name).includes(norm(args.project)));
-      if (!proj) return { error: `No project matched "${args.project}".` };
+    // Resolve the scope: explicit formulas > several projects > one project >
+    // the most-populated eligible project.
+    let proj = null, forms, scope;
+    const notes = [];
+    if (Array.isArray(args.formulas) && args.formulas.length) {
+      const r = _resolveFormulas(args.formulas, db);
+      if (r.missing.length) notes.push(`No formula matched: ${r.missing.join(', ')}.`);
+      forms = r.forms;
+      scope = { kind: 'formulas' };
+    } else if (Array.isArray(args.projects) && args.projects.length) {
+      const ps = [];
+      for (const q of args.projects) { const p = _resolveProject(q, db); if (!p) return { error: `No project matched "${q}".` }; if (!ps.includes(p)) ps.push(p); }
+      const ids = new Set(ps.map(p => p.id));
+      forms = (db.formulations || []).filter(f => f && !f._trashed && ids.has(f.projectId));
+      scope = { kind: 'projects' };
+      if (ps.length === 1) proj = ps[0];
     } else {
-      const elig = _eligibleProjects(db);
-      if (!elig.length) return { error: 'No project has ≥3 formulas to map. Assign at least 3 formulas to a project first.' };
-      proj = (db.projects || []).find(p => p.id === elig[0].id);
+      if (args.project) {
+        proj = _resolveProject(args.project, db);
+        if (!proj) return { error: `No project matched "${args.project}".` };
+      } else {
+        const elig = _eligibleProjects(db);
+        if (!elig.length) return { error: 'No project has ≥3 formulas to map. Assign at least 3 formulas to a project first.' };
+        proj = (db.projects || []).find(p => p.id === elig[0].id);
+      }
+      forms = (db.formulations || []).filter(f => f && !f._trashed && f.projectId === proj.id);
+      scope = { kind: 'project' };
     }
-    const pid = proj.id;
-    const forms = (db.formulations || []).filter(f => f && !f._trashed && f.projectId === pid);
+    const projIds = [...new Set(forms.map(f => f.projectId || ''))];
+    scope.formulaCount = forms.length;
+    scope.projects = projIds.map(id => (((db.projects || []).find(p => p.id === id) || {}).name) || (id ? id : '(no project)'));
 
     // Precompute ingredient maps once (reused by ranking, gap, PCA, observed range).
     const mapsByForm = new Map(forms.map(f => [f.id, _ingredientPctMap(f)]));
 
-    const out = {
-      project: { id: pid, uid: proj.uid || null, name: proj.name || pid, formulaCount: forms.length },
-      notes: [],
-    };
+    const out = { scope, notes };
+    if (proj) out.project = { id: proj.id, uid: proj.uid || null, name: proj.name || proj.id, formulaCount: forms.length };
     if (forms.length < 3) {
-      out.notes.push('This project has fewer than 3 formulas — a design space is only coherent with at least 3 points. Results below are provisional.');
+      out.notes.push('The scope has fewer than 3 formulas — a design space is only coherent with at least 3 points. Results below are provisional.');
     }
 
-    // Varying ingredients + observed ranges (ranked).
-    const cand = _factorCandidates(forms, mapsByForm, db);
+    // Varying ingredients + observed ranges (ranked). A scope spanning projects
+    // ranks ingredients at least half its formulas SHARE first (the app's rule).
+    let cand = _factorCandidates(forms, mapsByForm, db);
+    if (projIds.length > 1) {
+      const half = forms.length / 2;
+      cand = cand.filter(c => c.obs.n >= half).concat(cand.filter(c => c.obs.n < half));
+    }
     out.varyingIngredientCount = cand.length;
     out.varyingIngredients = cand.map(c => ({
       ingredient: c.name,
@@ -354,31 +447,73 @@ const get_design_space = {
       return out;
     }
 
-    // Axes: top-3 ternary (relative proportions) or top-2 scatter (absolute %).
-    const mode = cand.length >= 3 ? 'ternary' : 'scatter';
-    const comps = cand.slice(0, mode === 'ternary' ? 3 : 2);
+    // Axes: by role (pseudo-components) or ingredients; auto (most varying) or
+    // chosen. Values for the geometry come from `vmaps` (ingredient or role maps).
+    const byRole = !!args.by_role;
+    let vmaps = mapsByForm, axCand = cand;
+    if (byRole) {
+      vmaps = _roleMaps(forms, mapsByForm, db);
+      axCand = _roleCandidates(forms, vmaps);
+      out.roles = axCand.map(c => ({ role: c.name, observedRange: { min: +c.obs.min.toFixed(4), max: +c.obs.max.toFixed(4), unit: '%' }, usedInFormulas: c.obs.n }));
+      if (axCand.length < 2) { out.notes.push('Fewer than 2 ingredient roles vary (set ingredient Functions to use by_role).'); out.axes = null; return out; }
+    }
+    let comps = null, chosen = false;
+    if (Array.isArray(args.axes) && args.axes.length) {
+      const find = (q) => axCand.find(c => norm(c.id) === norm(q) || norm(c.name) === norm(q)) || axCand.find(c => norm(c.name).includes(norm(q)));
+      const picked = [];
+      args.axes.forEach(q => { const c = find(q); if (c && !picked.includes(c)) picked.push(c); });
+      if ((picked.length === 3 || picked.length === 2) && picked.length === args.axes.length) { comps = picked; chosen = true; }
+      else out.notes.push(`Could not use axes [${args.axes.join(', ')}] — each must be a distinct ${byRole ? 'role' : 'ingredient'} that varies in this scope (2 or 3). Using the most-varying instead.`);
+    }
+    if (!comps) comps = axCand.slice(0, axCand.length >= 3 ? 3 : 2);
+    const mode = comps.length === 3 ? 'ternary' : 'scatter';
+    const kind = byRole ? 'roles (ingredients summed by primary Function)' : 'ingredients';
     out.axes = {
       mode,
-      basis: mode === 'ternary'
-        ? 'Top 3 most-varying ingredients, as relative proportions (a ternary).'
-        : 'Top 2 most-varying ingredients, as absolute wt-%.',
-      ingredients: comps.map(c => c.name),
+      basis: `${chosen ? 'Chosen' : (mode === 'ternary' ? 'Top 3 most-varying' : 'Top 2 most-varying')} ${kind}, ${mode === 'ternary' ? 'as relative proportions (a ternary: each axis is its share of the three shown, not wt% of the recipe).' : 'as absolute wt-%.'}`,
+      [byRole ? 'roles' : 'ingredients']: comps.map(c => c.name),
     };
 
     // Occupied-region summary: the bounding envelope of the plotted axes + how
     // many formulas actually sit in the space. The app draws the convex hull of
     // these points; the per-axis min/max here is that hull's bounding box.
-    let inSpace = 0;
-    forms.forEach(f => { if (comps.some(c => _ingVal(mapsByForm, f, c.id) != null)) inSpace++; });
+    const onMap = forms.filter(f => comps.some(c => (_ingVal(vmaps, f, c.id) || 0) > 0));
+    const inSpace = onMap.length;
+    if (inSpace < forms.length) out.notes.push(`${forms.length - inSpace} of ${forms.length} formulas contain none of the axes and are not on the map.`);
+    const share = onMap.map(f => { const v = comps.map(c => _ingVal(vmaps, f, c.id) || 0); const t = v.reduce((a, b) => a + b, 0) || 1; return mode === 'ternary' ? v.map(x => 100 * x / t) : v; });
     out.occupiedRegion = {
       formulaPoints: inSpace,
+      spreadOnMap: comps.map((c, i) => { const vs = share.map(r => r[i]); return { axis: c.name, min: +Math.min(...vs).toFixed(2), max: +Math.max(...vs).toFixed(2), unit: mode === 'ternary' ? '% of the three' : '%' }; }),
       axisRanges: comps.map(c => ({ ingredient: c.name, id: c.id, min: +c.obs.min.toFixed(4), max: +c.obs.max.toFixed(4), unit: '%' })),
       note: 'Bounding envelope of the observed compositions on the mapped axes. In the app this is the shaded convex hull ("where you\'ve been"); the untested gap below was found INSIDE that occupied cloud, not on its frontier.',
     };
 
-    // The top untested interior gap, as ready-to-seed DOE ranges.
-    const gap = _computeGap(mode, comps, forms, mapsByForm);
-    if (!gap) {
+    // Property insights over the formulas on the map.
+    if (args.property) {
+      const vals = onMap.map(f => ({ f, v: _paramValue(f, args.property, db) })).filter(x => x.v != null);
+      if (vals.length < 2) out.notes.push(`"${args.property}" is measured on ${vals.length} of the formulas on the map — need at least 2 for insights (check the exact parameter name).`);
+      else {
+        const hi = vals.reduce((a, b) => b.v > a.v ? b : a), lo = vals.reduce((a, b) => b.v < a.v ? b : a);
+        const pi = { property: args.property, basis: 'mean of every reading per formula', formulasMeasured: vals.length,
+          highest: { formula: hi.f.name, uid: hi.f.uid || null, value: +hi.v.toFixed(4) },
+          lowest: { formula: lo.f.name, uid: lo.f.uid || null, value: +lo.v.toFixed(4) } };
+        if (vals.length >= 4) {
+          const ranked = [];
+          cand.forEach(c => { const xs = vals.map(x => _ingVal(mapsByForm, x.f, c.id) || 0); if (new Set(xs).size < 2) return; const r = _spearman(xs, vals.map(x => x.v)); if (r != null) ranked.push({ ingredient: c.name, rho: +r.toFixed(3) }); });
+          ranked.sort((a, b) => Math.abs(b.rho) - Math.abs(a.rho));
+          pi.tracksMost = ranked.slice(0, 5);
+          pi.note = 'Spearman rank correlation across these formulas — a lead for what to vary, not proof of cause' + (vals.length < 8 ? '; few formulas, so treat it cautiously.' : '.');
+        }
+        out.propertyInsights = pi;
+      }
+    }
+
+    // The top untested interior gap, as ready-to-seed DOE ranges (not for roles:
+    // they aren't DOE factors).
+    const gap = byRole ? null : _computeGap(mode, comps, forms, mapsByForm);
+    if (byRole) {
+      out.gap = null;
+    } else if (!gap) {
       out.gap = null;
       out.notes.push('Too few distinct formula points (need ≥4 with these axes) to locate a trustworthy gap.');
     } else {

package/tools/documents.js

@@ -60,7 +60,7 @@ function allDocuments(db) {
       lot: d.lotNumber || '', version: d.version != null ? String(d.version) : '', source: d.source || '',
       expiryDate: d.expiryDate || null, expiryStatus: ex.status, daysToExpiry: ex.daysToExpiry,
       sizeKb: Number.isFinite(+d.size) && d.size != null ? Math.round(+d.size / 102.4) / 10 : null,
-      uploadedAt: d.uploadedAt || null,
+      uploadedAt: d.uploadedAt || null, addedBy: d.addedBy || null,
     });
   }));
   const testsById = new Map((db.testResults || []).map(t => [t.id, t]));
@@ -71,7 +71,7 @@ function allDocuments(db) {
       record: 'test', linked: (t ? (t.uid || t.id) : 'Test') + (a.measurementParameter ? ' · ' + a.measurementParameter : ''), linkedId: t ? (t.uid || t.id) : null,
       lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
       sizeKb: Number.isFinite(+a.fileSize) && a.fileSize != null ? Math.round(+a.fileSize / 102.4) / 10 : null,
-      uploadedAt: a.uploadedAt || null,
+      uploadedAt: a.uploadedAt || null, addedBy: a.addedBy || null,
     });
   });
   (db.notebookEntries || []).filter(live).forEach(ne => (ne.attachments || []).forEach(att => {
@@ -83,7 +83,7 @@ function allDocuments(db) {
       record: 'notebook', linked: rec ? (rec.name || rec.uid || '') : (ne.entityType || 'note'), linkedId: rec ? (rec.uid || rec.id) : null,
       lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
       sizeKb: Number.isFinite(+att.size) && att.size != null ? Math.round(+att.size / 102.4) / 10 : null,
-      uploadedAt: att.uploadedAt || null,
+      uploadedAt: att.uploadedAt || null, addedBy: att.addedBy || ne.author || null,   // a note's file is its author's
     });
   }));
   Object.entries(ATTACH_COLL).forEach(([etype, coll]) => (db[coll] || []).filter(live).forEach(rec => (rec.fileAttachments || []).forEach(a => {
@@ -95,7 +95,7 @@ function allDocuments(db) {
       ...(isLink && a.url ? { url: a.url } : {}),
       lot: '', version: '', source: '', expiryDate: null, expiryStatus: 'none', daysToExpiry: null,
       sizeKb: (!isLink && Number.isFinite(+a.size) && a.size != null) ? Math.round(+a.size / 102.4) / 10 : null,
-      uploadedAt: a.createdAt || null,
+      uploadedAt: a.createdAt || null, addedBy: a.addedBy || null,
     });
   })));
   return out;
@@ -121,7 +121,7 @@ function summary(db, docs) {
 const list_documents = {
   definition: {
     name: 'list_documents',
-    description: 'The workspace document register — same list as the app\'s Documents page: ingredient SDS / PDS / CoA / other files (with lot, version, source, expiry), test-result and notebook attachments, and per-record uploads and links (formulas, batches, samples, suppliers, equipment…). Returns file METADATA only (never the text inside a file). Filters combine. The summary block matches the page\'s tiles: expired, expiring in 30 days, SDS/CoA without an expiry date, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, files added in the last 7 days. For the lots themselves use list_lots with missing_coa: true.',
+    description: 'The workspace document register — same list as the app\'s Documents page: ingredient SDS / PDS / CoA / other files (with lot, version, source, expiry), test-result and notebook attachments, and per-record uploads and links (formulas, batches, samples, suppliers, equipment…). Returns file METADATA only (never the text inside a file), including addedBy (who added it — null for files added before that was recorded) and uploadedAt. Filters combine. The summary block matches the page\'s tiles: expired, expiring in 30 days, SDS/CoA without an expiry date, ingredients missing an SDS (+ coverage %), lots in stock without a CoA, files added in the last 7 days. For the lots themselves use list_lots with missing_coa: true.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -135,6 +135,7 @@ const list_documents = {
         expiring_within_days: { type: 'number', description: 'Only documents whose expiry date is within this many days (already expired included).' },
         without_expiry: { type: 'boolean', description: 'true = only SDS / CoA files with no expiry date (the "SDS / CoA without expiry" tile).' },
         uploaded_within_days: { type: 'number', description: 'Only files uploaded within this many days.' },
+        added_by: { type: 'string', description: 'Who added the file: case-insensitive substring of their email / name. Files from before this was recorded have none and never match.' },
         limit: { type: 'number', description: 'Max rows (default 200, max 1000).' },
       },
     },
@@ -156,6 +157,7 @@ const list_documents = {
       if (args.expiring_within_days != null && !(d.daysToExpiry != null && d.daysToExpiry <= args.expiring_within_days)) return false;
       if (args.without_expiry === true && !(d.record === 'ingredient' && d.expiryStatus === 'none' && (d.type === 'SDS' || d.type === 'COA'))) return false;
       if (args.uploaded_within_days != null && !(d.ageDays != null && d.ageDays <= args.uploaded_within_days)) return false;
+      if (args.added_by && !norm(d.addedBy).includes(norm(args.added_by))) return false;
       return true;
     }).sort((a, b) => String(b.uploadedAt || '').localeCompare(String(a.uploadedAt || '')));
     return { summary: summary(db, all), totalMatching: rows.length, returned: Math.min(rows.length, limit), documents: rows.slice(0, limit) };

package/tools/notebook.js

@@ -46,6 +46,10 @@ function _trimEntry(e, db, { full = false } = {}) {
     updatedAt: e.updatedAt || null,
     author: e.author || '',
     attachmentCount: atts.length,
+    // Withdrawn by its author or the workspace owner (append-only notebook):
+    // the note is kept, but it is not a finding. null when not retracted.
+    retracted: (e.retracted && typeof e.retracted === 'object')
+      ? { at: e.retracted.at || null, by: e.retracted.by || '', reason: e.retracted.reason || '' } : null,
   };
   if (!full) return { ...base, body: (e.body || '').slice(0, 240) };
   return {
@@ -58,7 +62,7 @@ function _trimEntry(e, db, { full = false } = {}) {
 const list_notebook_entries = {
   definition: {
     name: 'list_notebook_entries',
-    description: 'List ELN notebook entries — dated, authored notes attached to records — optionally filtered by the record they hang off (entity_type + entity_id), author, text, or date range. Newest first. Use get_notebook_entry for the full body + attachments.',
+    description: 'List ELN notebook entries — dated, authored notes attached to records — optionally filtered by the record they hang off (entity_type + entity_id), author, text, or date range. Newest first. Entries are append-only: a withdrawn one is kept with retracted = {at, by, reason} — treat it as withdrawn, not as a finding. Use get_notebook_entry for the full body + attachments.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -68,6 +72,7 @@ const list_notebook_entries = {
         text_contains: { type: 'string', description: 'Case-insensitive substring on the note body.' },
         since: { type: 'string', description: 'ISO date/time — only entries at or after this timestamp.' },
         until: { type: 'string', description: 'ISO date/time — only entries at or before this timestamp.' },
+        retracted: { type: 'boolean', description: 'false = only notes that stand (leave out retracted ones); true = only retracted notes. Omit for both.' },
         limit: { type: 'number', description: 'Max rows (default 100, max 1000).' },
       },
     },
@@ -91,6 +96,7 @@ const list_notebook_entries = {
       if (wantEntityId && e.entityId !== wantEntityId) return false;
       if (args.author && !_norm(e.author).includes(_norm(args.author))) return false;
       if (args.text_contains && !_norm(e.body).includes(_norm(args.text_contains))) return false;
+      if (typeof args.retracted === 'boolean' && (!!(e.retracted && typeof e.retracted === 'object')) !== args.retracted) return false;
       if (sinceMs != null || untilMs != null) {
         const t = Date.parse(_entryTs(e));
         if (!isFinite(t)) return false;
@@ -110,7 +116,7 @@ const list_notebook_entries = {
 const get_notebook_entry = {
   definition: {
     name: 'get_notebook_entry',
-    description: 'Get one ELN notebook entry by id — full note body, author, timestamp, the record it is attached to (resolved to uid/name), and attachment metadata (filename / type). Attachment binaries are not returned.',
+    description: 'Get one ELN notebook entry by id — full note body, author, timestamp, the record it is attached to (resolved to uid/name), attachment metadata (filename / type), and retracted = {at, by, reason} when the note was withdrawn. Attachment binaries are not returned.',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'string', description: 'Internal id of the notebook entry.' } },