vision-electronic-indexing-pi 0.1.6 → 0.1.8

package/.pi/extensions/vision-inventory-mcp/README.md

@@ -16,7 +16,9 @@ Then in Pi:
 /vision-inventory-setup
 ```
 
-Setup checks Python dependencies, checks whether a web-search/browser tool is available for datasheet lookup, and prompts for Cloudflare Workers AI credentials when needed.
+Setup creates/checks a Pi-managed Python virtual environment at `~/.pi/agent/vision-inventory/.venv`, installs Python dependencies there when approved, warns that datasheet lookup needs a separate web-search/browser capability, and prompts for Cloudflare Workers AI API token credentials when needed.
+
+On Debian/Ubuntu, Python venv creation may require `python3-venv` or a version-specific package such as `python3.10-venv`. If setup reports that `ensurepip` is unavailable, install the package, remove the incomplete venv with `rm -rf ~/.pi/agent/vision-inventory/.venv`, and rerun `/vision-inventory-setup`.
 
 Credentials are stored at:
 
@@ -24,6 +26,8 @@ Credentials are stored at:
 ~/.pi/agent/vision-inventory/credentials.json
 ```
 
+The file is written with `chmod 600` when supported. Token input may be visible depending on your Pi UI; avoid entering credentials while screen sharing.
+
 Change them later with:
 
 ```text
@@ -66,15 +70,15 @@ Options are forwarded to `scripts/inventory_folder_to_csv.py`, such as `--recurs
 
 - `vision_inventory_process_image` — analyze one electronics/PCB image.
 - `vision_inventory_process_folder` — analyze all supported images in a folder.
-- `vision_inventory_save` — save inventory output as JSON or CSV.
+- `vision_inventory_save` — save inventory output as JSON or quick CSV export. Use `/vision-inventory-bom` for the full BOM/evidence workflow.
 
 ## External dependencies not bundled
 
 This package intentionally does **not** bundle:
 
-- Python packages from `requirements.txt`: `mcp`, `requests`, `pillow`, `python-dotenv`; optional `pillow-heif`.
+- Python packages from `requirements.txt`: `mcp`, `requests`, `pillow`, `python-dotenv`; optional `pillow-heif`. Pi setup installs these into the package-managed venv when approved.
 - A Pi web-search/browser tool or skill for datasheet lookup.
-- Cloudflare Workers AI credentials.
+- Cloudflare Workers AI API token credentials.
 
 ## Output
 

package/.pi/extensions/vision-inventory-mcp/index.ts

@@ -3,16 +3,19 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { existsSync } from "node:fs";
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const SERVER_FILE = "vision_inventory_mcp.py";
-const PYTHON_COMMAND = process.env.PI_VISION_INVENTORY_PYTHON || "python3";
+const BASE_PYTHON_COMMAND = process.env.PI_VISION_INVENTORY_PYTHON || "python3";
 const MAX_RESULT_CHARS = 50_000;
 const EXTENSION_DIR = dirname(fileURLToPath(import.meta.url));
 const CONFIG_DIR = join(homedir(), ".pi", "agent", "vision-inventory");
+const VENV_DIR = join(CONFIG_DIR, ".venv");
+const VENV_PYTHON = process.platform === "win32" ? join(VENV_DIR, "Scripts", "python.exe") : join(VENV_DIR, "bin", "python");
+const VENV_PIP = process.platform === "win32" ? join(VENV_DIR, "Scripts", "pip.exe") : join(VENV_DIR, "bin", "pip");
 const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");
 
 type VisionCredentials = {
@@ -57,7 +60,8 @@ class McpStdioClient {
       throw new Error(`Cannot find ${SERVER_FILE} in ${this.packageRoot}`);
     }
 
-    this.proc = spawn(PYTHON_COMMAND, [serverPath], {
+    const pythonCommand = await getPythonCommand();
+    this.proc = spawn(pythonCommand, [serverPath], {
       cwd: this.packageRoot,
       env: await buildPythonEnv(),
       stdio: ["pipe", "pipe", "pipe"],
@@ -72,7 +76,7 @@ class McpStdioClient {
       this.lastStderr = (this.lastStderr + chunk).slice(-10_000);
     });
     this.proc.on("error", (error) => {
-      const err = new Error(`Failed to start Vision Inventory MCP server with ${PYTHON_COMMAND}: ${error.message}`);
+      const err = new Error(`Failed to start Vision Inventory MCP server: ${error.message}`);
       for (const pending of this.pending.values()) pending.reject(err);
       this.pending.clear();
       this.initialized = false;
@@ -215,6 +219,82 @@ async function buildPythonEnv(): Promise<NodeJS.ProcessEnv> {
   };
 }
 
+function hasCompleteVenv(): boolean {
+  return existsSync(VENV_PYTHON) && existsSync(VENV_PIP);
+}
+
+async function getPythonCommand(): Promise<string> {
+  return hasCompleteVenv() ? VENV_PYTHON : BASE_PYTHON_COMMAND;
+}
+
+function venvHelpText(): string {
+  return [
+    `Vision Inventory Python venv path: ${VENV_DIR}`,
+    "On Debian/Ubuntu, venv creation with pip requires python3-venv.",
+    "Install it with: sudo apt install python3-venv",
+    "If your system asks for a version-specific package, install that instead, e.g. sudo apt install python3.10-venv",
+  ].join("\n");
+}
+
+async function ensurePythonEnvironment(pi: ExtensionAPI, packageRoot: string, ctx: { ui: any; hasUI: boolean }): Promise<boolean> {
+  if (existsSync(VENV_PYTHON) && !existsSync(VENV_PIP)) {
+    const message = `Existing Vision Inventory venv is incomplete because pip is missing.\n${venvHelpText()}`;
+    if (!ctx.hasUI) {
+      ctx.ui.notify(message, "error");
+      return false;
+    }
+
+    const recreate = await ctx.ui.confirm(
+      "Recreate incomplete Vision Inventory Python virtual environment?",
+      `${message}\n\nChoose No if you have not installed python3-venv yet. After installing it, rerun /vision-inventory-setup.`
+    );
+    if (!recreate) {
+      ctx.ui.notify(message, "error");
+      return false;
+    }
+    await rm(VENV_DIR, { recursive: true, force: true });
+  }
+
+  if (!hasCompleteVenv()) {
+    if (!ctx.hasUI) {
+      ctx.ui.notify(`Vision Inventory Python venv is missing or incomplete. Run /vision-inventory-setup interactively, or install dependencies manually with ${BASE_PYTHON_COMMAND} -m pip install -r ${join(packageRoot, "requirements.txt")}\n${venvHelpText()}`, "error");
+      return false;
+    }
+
+    const create = await ctx.ui.confirm("Create Vision Inventory Python virtual environment?", `${BASE_PYTHON_COMMAND} -m venv ${VENV_DIR}`);
+    if (!create) {
+      ctx.ui.notify("Python environment setup skipped. Vision Inventory tools may fail until dependencies are installed.", "error");
+      return false;
+    }
+
+    await mkdir(CONFIG_DIR, { recursive: true });
+    const venvResult = await pi.exec(BASE_PYTHON_COMMAND, ["-m", "venv", VENV_DIR], { timeout: 120_000 });
+    if (venvResult.code !== 0 || !hasCompleteVenv()) {
+      await rm(VENV_DIR, { recursive: true, force: true });
+      ctx.ui.notify(`${venvResult.stderr || venvResult.stdout || "Python venv creation failed"}\n${venvHelpText()}`, "error");
+      return false;
+    }
+  }
+
+  const deps = await pi.exec(VENV_PYTHON, ["-c", "import mcp, requests, PIL, dotenv; print('ok')"], { timeout: 10_000 });
+  if (deps.code === 0) return true;
+
+  if (!ctx.hasUI) {
+    ctx.ui.notify(`Missing Python dependencies in ${VENV_DIR}. Run: ${VENV_PYTHON} -m pip install -r ${join(packageRoot, "requirements.txt")}`, "error");
+    return false;
+  }
+
+  const install = await ctx.ui.confirm("Install Python dependencies into the Vision Inventory venv?", `${VENV_PYTHON} -m pip install -r ${join(packageRoot, "requirements.txt")}`);
+  if (!install) return false;
+
+  const result = await pi.exec(VENV_PYTHON, ["-m", "pip", "install", "-r", join(packageRoot, "requirements.txt")], { timeout: 120_000 });
+  if (result.code !== 0) {
+    ctx.ui.notify(result.stderr || result.stdout || "pip install failed", "error");
+    return false;
+  }
+  return true;
+}
+
 function extractMcpPayload(result: unknown): unknown {
   const maybe = result as { content?: Array<{ type?: string; text?: string }>; structuredContent?: unknown } | null;
   if (maybe && typeof maybe === "object") {
@@ -304,9 +384,10 @@ async function runBatchWorkflow(packageRoot: string, userCwd: string, argsLine:
   }
 
   const env = await buildPythonEnv();
+  const pythonCommand = await getPythonCommand();
 
   return new Promise((resolve, reject) => {
-    const proc = spawn(PYTHON_COMMAND, [scriptPath, ...args], {
+    const proc = spawn(pythonCommand, [scriptPath, ...args], {
       cwd: packageRoot,
       env,
       stdio: ["ignore", "pipe", "pipe"],
@@ -421,14 +502,14 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  async function runSetup(ctx: { ui: any; hasUI: boolean }, forceCredentials = false): Promise<void> {
+  async function runSetup(ctx: { ui: any; hasUI: boolean }, forceCredentials = false): Promise<boolean> {
     const existing = await loadCredentials();
     const hasEffectiveAccountId = Boolean(process.env.CLOUDFLARE_ACCOUNT_ID || existing.cloudflareAccountId);
     const hasEffectiveToken = Boolean(process.env.CLOUDFLARE_AUTH_TOKEN || process.env.CLOUDFLARE_API_TOKEN || existing.cloudflareAuthToken);
     if ((!hasEffectiveAccountId || !hasEffectiveToken || forceCredentials) && ctx.hasUI) {
-      ctx.ui.notify("Vision Inventory stores Cloudflare credentials in ~/.pi/agent/vision-inventory/credentials.json with chmod 600 when supported. Use /vision-inventory-credentials to change them.", "info");
+      ctx.ui.notify("Vision Inventory stores Cloudflare credentials in ~/.pi/agent/vision-inventory/credentials.json with chmod 600 when supported. Use /vision-inventory-credentials to change them. Token input may be visible depending on your Pi UI; avoid entering credentials while screen sharing.", "info");
       const cloudflareAccountId = await ctx.ui.input("Cloudflare account ID", existing.cloudflareAccountId || "");
-      const cloudflareAuthToken = await ctx.ui.input("Cloudflare Workers AI token", existing.cloudflareAuthToken ? "<keep existing; paste new token to replace>" : "");
+      const cloudflareAuthToken = await ctx.ui.input("Cloudflare Workers AI API token (leave blank for default)", existing.cloudflareAuthToken ? "<keep existing; paste new token to replace>" : "");
       const workersAiModel = await ctx.ui.input("Workers AI model", existing.workersAiModel || "@cf/meta/llama-4-scout-17b-16e-instruct");
       await saveCredentials({
         cloudflareAccountId: cloudflareAccountId || existing.cloudflareAccountId,
@@ -439,31 +520,16 @@ export default function (pi: ExtensionAPI) {
       ctx.ui.notify("Missing Cloudflare credentials. Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_AUTH_TOKEN/CLOUDFLARE_API_TOKEN, or run /vision-inventory-setup in interactive Pi.", "error");
     }
 
-    const deps = await pi.exec(PYTHON_COMMAND, ["-c", "import mcp, requests, PIL, dotenv; print('ok')"], { timeout: 10_000 });
-    if (deps.code !== 0) {
-      if (!ctx.hasUI) {
-        ctx.ui.notify(`Missing Python dependencies. Run: ${PYTHON_COMMAND} -m pip install -r ${join(packageRoot, "requirements.txt")}`, "error");
-        return;
-      }
-      const install = await ctx.ui.confirm("Install Python dependencies?", `${PYTHON_COMMAND} -m pip install -r ${join(packageRoot, "requirements.txt")}`);
-      if (install) {
-        const result = await pi.exec(PYTHON_COMMAND, ["-m", "pip", "install", "-r", join(packageRoot, "requirements.txt")], { timeout: 120_000 });
-        if (result.code !== 0) throw new Error(result.stderr || result.stdout || "pip install failed");
-      }
-    }
+    const pythonReady = await ensurePythonEnvironment(pi, packageRoot, ctx);
+    if (!pythonReady) return false;
 
-    const commands = pi.getCommands().map((command) => command.name.toLowerCase());
-    const tools = pi.getAllTools().map((tool) => tool.name.toLowerCase());
-    const hasWebDependency = [...commands, ...tools].some((name) => name.includes("search") || name.includes("brave") || name.includes("browser") || name.includes("web"));
-    if (!hasWebDependency) {
-      ctx.ui.notify("Agent datasheet enrichment requires a web-search/browser Pi tool or skill. This package intentionally does not bundle one; install/enable your preferred search dependency before using /vision-inventory-agent-bom.", "error");
-    }
-
-    ctx.ui.notify(`Vision Inventory setup checked. Package root: ${packageRoot}`, "info");
+    ctx.ui.notify("Datasheet enrichment requires a separate web-search/browser Pi tool or skill. This package does not provide one; if your agent cannot search the web, fill datasheet_cache.json manually.", "info");
+    ctx.ui.notify(`Vision Inventory setup checked. Package root: ${packageRoot}. Python: ${await getPythonCommand()}`, "info");
+    return true;
   }
 
   pi.registerCommand("vision-inventory-setup", {
-    description: "Configure Vision Inventory credentials and check Python/web-search dependencies",
+    description: "Configure Vision Inventory credentials and check Python dependencies",
     handler: async (args, ctx) => {
       try {
         await runSetup(ctx, args.includes("--reset") || args.includes("--credentials"));
@@ -510,10 +576,25 @@ export default function (pi: ExtensionAPI) {
         return;
       }
 
-      await runSetup(ctx, false);
-      const normalizedArgs = normalizeWorkflowArgs(ctx.cwd, parsed).map((arg) => JSON.stringify(arg)).join(" ");
-      const outputDir = normalizeWorkflowArgs(ctx.cwd, parsed)[1];
-      const prompt = `Run the complete Vision Electronic Indexing workflow as an agent.\n\nPackage root containing the bundled Python workflow: ${packageRoot}\nCommand arguments, already resolved relative to the user's cwd: ${normalizedArgs}\nOutput directory: ${outputDir}\n\nImportant external agent dependency: datasheet enrichment requires a web-search/browser Pi tool or skill. This package intentionally does not bundle a web-search dependency. If no search/browser tool is available, stop after generating parts_to_lookup.json and tell the user which dependency is missing.\n\nDo these steps end-to-end:\n1. Run: ${PYTHON_COMMAND} ${join(packageRoot, "scripts", "inventory_folder_to_csv.py")} ${normalizedArgs}\n2. Read ${outputDir}/parts_to_lookup.json.\n3. For every part, web-search for a datasheet. Prefer official manufacturer pages/PDFs.\n4. Write ${outputDir}/datasheet_cache.json using ${outputDir}/datasheet_cache.template.json as the exact shape.\n5. Rerun: ${PYTHON_COMMAND} ${join(packageRoot, "scripts", "inventory_folder_to_csv.py")} ${normalizedArgs} --skip-vision\n6. Read ${outputDir}/inventory.csv and ${outputDir}/inventory_evidence.csv.\n7. Summarize final BOM rows and call out every uncertainty.\n\nRules:\n- Do not invent datasheets, manufacturers, or descriptions.\n- If an exact candidate part has no official datasheet but search results strongly indicate a likely OCR correction, keep the original candidate as the datasheet_cache key and set normalized_part to the official datasheet part number. Example: key SN74AS283N may normalize to SN74LS283N when official TI results match the family/function/package and the image could plausibly confuse A with 4/LS.\n- Only set verified=true for an OCR correction when official source evidence and visual/package context make the correction highly likely; otherwise set verified=false and explain in notes.\n- Include OCR correction notes such as: \"SN74AS283N appears to be OCR for SN74LS283N; verified against TI datasheet.\"\n- Set verified=false if the part or datasheet match is uncertain.\n- Keep descriptions short, like: \"74ls (4 bit) adder low power schottky ttl 5v DIP\".\n- Preserve raw JSON and evidence files.\n- Do not expose Cloudflare credentials.\n- If a command fails because credentials or Python dependencies are missing, tell the user to run /vision-inventory-setup or /vision-inventory-credentials.`;
+      const setupOk = await runSetup(ctx, false);
+      if (!setupOk) return;
+      const normalized = normalizeWorkflowArgs(ctx.cwd, parsed);
+      const normalizedArgs = normalized.map((arg) => JSON.stringify(arg)).join(" ");
+      const outputDir = normalized[1];
+      const pythonCommand = await getPythonCommand();
+
+      ctx.ui.setStatus("vision-inventory", "Running initial vision workflow...");
+      try {
+        const initialOutput = await runBatchWorkflow(packageRoot, ctx.cwd, args || "");
+        ctx.ui.notify(initialOutput.slice(-4000), "info");
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message.slice(-4000) : String(error), "error");
+        ctx.ui.setStatus("vision-inventory", "");
+        return;
+      }
+      ctx.ui.setStatus("vision-inventory", "");
+
+      const prompt = `Continue the Vision Electronic Indexing workflow as an agent.\n\nThe deterministic vision step has already been run by the Pi command.\nPackage root containing the bundled Python workflow: ${packageRoot}\nCommand arguments, already resolved relative to the user's cwd: ${normalizedArgs}\nOutput directory: ${outputDir}\n\nImportant external agent dependency: datasheet enrichment requires a web-search/browser Pi tool or skill. This package intentionally does not bundle a web-search dependency. If no search/browser tool is available, stop after reviewing ${outputDir}/parts_to_lookup.json and tell the user to fill ${outputDir}/datasheet_cache.json manually.\n\nDo these remaining steps end-to-end:\n1. Read ${outputDir}/parts_to_lookup.json.\n2. For every part, web-search for a datasheet. Prefer official manufacturer pages/PDFs.\n3. Write ${outputDir}/datasheet_cache.json using ${outputDir}/datasheet_cache.template.json as the exact shape.\n4. Rerun: ${pythonCommand} ${join(packageRoot, "scripts", "inventory_folder_to_csv.py")} ${normalizedArgs} --skip-vision\n5. Read ${outputDir}/inventory.csv and ${outputDir}/inventory_evidence.csv.\n6. Summarize final BOM rows and call out every uncertainty.\n\nRules:\n- Do not invent datasheets, manufacturers, or descriptions.\n- If an exact candidate part has no official datasheet but search results strongly indicate a likely OCR correction, keep the original candidate as the datasheet_cache key and set normalized_part to the official datasheet part number. Example: key SN74AS283N may normalize to SN74LS283N when official TI results match the family/function/package and the image could plausibly confuse A with 4/LS.\n- Only set verified=true for an OCR correction when official source evidence and visual/package context make the correction highly likely; otherwise set verified=false and explain in notes.\n- Include OCR correction notes such as: \"SN74AS283N appears to be OCR for SN74LS283N; verified against TI datasheet.\"\n- Set verified=false if the part or datasheet match is uncertain.\n- Keep descriptions short, like: \"74ls (4 bit) adder low power schottky ttl 5v DIP\".\n- Preserve raw JSON and evidence files.\n- Do not expose Cloudflare credentials.\n- If a command fails because credentials or Python dependencies are missing, tell the user to run /vision-inventory-setup or /vision-inventory-credentials.`;
 
       await ctx.sendUserMessage(prompt);
     },

package/.pi/skills/vision-inventory-workflow/SKILL.md

@@ -13,9 +13,9 @@ This package intentionally does **not** bundle these dependencies:
 
 - Python packages from `requirements.txt`: `mcp`, `requests`, `pillow`, `python-dotenv`; optional `pillow-heif` for HEIC/HEIF.
 - A Pi web-search/browser tool or skill for datasheet enrichment.
-- Cloudflare Workers AI credentials.
+- Cloudflare Workers AI API token credentials.
 
-Use `/vision-inventory-setup` to configure credentials and check/install Python dependencies. Use `/vision-inventory-credentials` to change stored Cloudflare credentials.
+Use `/vision-inventory-setup` to configure credentials, create/check the Pi-managed Python venv, install Python dependencies when approved, and see the web-search/browser requirement warning. Use `/vision-inventory-credentials` to change stored Cloudflare credentials.
 
 ## Preferred Command
 

package/README.md

@@ -1,6 +1,6 @@
 # Vision Electronic Indexing for Pi
 
-Agent-assisted electronics/PCB photo indexing for Pi. The package processes images with Cloudflare Workers AI, extracts visible IC/package markings, prepares parts for datasheet lookup, and produces an enriched inventory CSV.
+Agent-assisted electronics parts/PCB photo indexing for Pi. The package processes images with Cloudflare Workers AI, extracts visible IC/package markings, prepares parts for datasheet lookup, and produces an enriched inventory CSV.
 
 Typical flow:
 
@@ -10,6 +10,12 @@ photos -> vision extraction -> raw JSON + evidence -> agent datasheet verificati
 
 The vision step does **not** perform datasheet lookup or invent part details. Datasheet enrichment is handled by a Pi agent with a web-search/browser tool or by manual review.
 
+## Which setup should I use?
+
+- **Using Pi?** Install the package with `pi install npm:vision-electronic-indexing-pi`, then run `/vision-inventory-setup`.
+- **Using Claude Code, Codex CLI, OpenCode, Cursor, or another MCP-capable harness?** Use the recommended universal installer in `.universal/scripts/quick-install.sh`.
+- **Using plain Python or manual MCP configuration?** Install `requirements.txt`, configure Cloudflare credentials, and run `vision_inventory_mcp.py` directly.
+
 ## Quick setup with Pi
 
 ### 1. Install the Pi package
@@ -20,9 +26,9 @@ pi install npm:vision-electronic-indexing-pi
 
 For local development from this repository, open the repo in Pi and trust the project. Do not also install the npm package while working inside this repo, because the project-local extension and npm package register the same tools.
 
-### 2. Install/enable an agent web-search dependency
+### 2. Plan for datasheet web search
 
-Datasheet enrichment requires a Pi web-search or browser tool/skill. This package intentionally does **not** bundle one.
+Datasheet enrichment requires a separate Pi web-search or browser tool/skill. This package intentionally does **not** bundle one and does not try to auto-detect one because detection is unreliable.
 
 Examples of acceptable capabilities:
 
@@ -30,7 +36,7 @@ Examples of acceptable capabilities:
 - a browser automation skill
 - another trusted web-search extension/tool
 
-If no search/browser capability is available, the agent workflow can still generate `parts_to_lookup.json`, but it cannot verify datasheets.
+If no search/browser capability is available, the workflow can still generate `parts_to_lookup.json`, but it cannot verify datasheets. Fill `datasheet_cache.json` manually in that case.
 
 ### 3. Configure Cloudflare credentials
 
@@ -40,7 +46,9 @@ Start Pi and run:
 /vision-inventory-setup
 ```
 
-The setup command checks Python dependencies, checks for web-search/browser capability, and prompts for Cloudflare Workers AI credentials the first time.
+The setup command creates/checks a Pi-managed Python virtual environment under `~/.pi/agent/vision-inventory/.venv`, installs Python dependencies there when approved, warns that datasheet enrichment needs a separate web-search/browser capability, and prompts for Cloudflare Workers AI API token credentials the first time.
+
+On Debian/Ubuntu, Python venv creation may require the system package `python3-venv` or a version-specific package such as `python3.10-venv`. If setup reports that `ensurepip` is unavailable, install the package, remove the incomplete venv with `rm -rf ~/.pi/agent/vision-inventory/.venv`, and rerun `/vision-inventory-setup`.
 
 Credentials are stored at:
 
@@ -48,7 +56,7 @@ Credentials are stored at:
 ~/.pi/agent/vision-inventory/credentials.json
 ```
 
-The file is written with `chmod 600` when supported.
+The file is written with `chmod 600` when supported. Token input may be visible depending on your Pi UI; avoid entering credentials while screen sharing.
 
 To change credentials later:
 
@@ -60,9 +68,9 @@ Environment variables also work and override stored credentials:
 
 ```bash
 export CLOUDFLARE_ACCOUNT_ID=your_account_id
-export CLOUDFLARE_AUTH_TOKEN=your_workers_ai_token
-# or
-export CLOUDFLARE_API_TOKEN=your_workers_ai_token
+export CLOUDFLARE_AUTH_TOKEN=your_workers_ai_api_token
+# CLOUDFLARE_API_TOKEN is also accepted as an alias:
+export CLOUDFLARE_API_TOKEN=your_workers_ai_api_token
 ```
 
 Optional model override:
@@ -71,6 +79,112 @@ Optional model override:
 export WORKERS_AI_MODEL=@cf/meta/llama-4-scout-17b-16e-instruct
 ```
 
+## Other harnesses / universal MCP compatibility
+
+_Contributed by user [@Brun0-v](https://github.com/Brun0-V)_ 
+
+This repository also includes a harness-neutral compatibility layer in `.universal/` for MCP-capable coding agents such as OpenCode, Claude Code, Codex CLI, Cursor, and similar clients.
+
+The universal layer does **not** replace the Pi package integration. Pi users should keep using the commands above.
+
+For other harnesses, use the universal installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Pichi-Cell/vision-electronic-indexing-mcp/main/.universal/scripts/quick-install.sh -o /tmp/vei-install.sh && bash /tmp/vei-install.sh
+```
+
+This installs to `~/.vei/`, sets up a Python venv, prompts for Cloudflare Workers AI API token credentials, installs the agent skill, and **automatically configures the MCP server** in your agent's settings. **Requires an MCP-capable agent** (OpenCode, Claude Code, Codex CLI, Cursor, etc.).
+
+Warning: some MCP clients store environment variables in plaintext JSON config files. Prefer shell environment variables or your agent's secret storage if available.
+
+Other harnesses can also connect directly to the Python MCP server:
+
+```bash
+python3 /path/to/vision-electronic-indexing-mcp/vision_inventory_mcp.py
+```
+
+### 1. Manual setup: install Python dependencies
+
+From the repository root:
+
+```bash
+python3 -m pip install -r requirements.txt
+# Optional for iPhone HEIC/HEIF photos:
+# python3 -m pip install pillow-heif
+```
+
+### 2. Configure Cloudflare credentials
+
+Either copy `.env.example` to `.env` in the repository root:
+
+```bash
+cp .env.example .env
+# edit .env and set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_AUTH_TOKEN
+# CLOUDFLARE_AUTH_TOKEN should be your Cloudflare Workers AI API token.
+```
+
+or put the credentials directly in your harness MCP server configuration. Be aware that many harness config files store these values in plaintext.
+
+### 3. Add the MCP server to your harness
+
+Example config snippets are provided in:
+
+```text
+.universal/configs/opencode.json.example
+.universal/configs/claude.json.example
+.universal/configs/codex.json.example
+.universal/configs/cursor.json.example
+```
+
+Each config should point to the repository-root server file, for example:
+
+```json
+{
+  "mcpServers": {
+    "vision-inventory": {
+      "command": "python3",
+      "args": ["/path/to/vision-electronic-indexing-mcp/vision_inventory_mcp.py"],
+      "env": {
+        "CLOUDFLARE_ACCOUNT_ID": "your_cloudflare_account_id",
+        "CLOUDFLARE_AUTH_TOKEN": "your_cloudflare_workers_ai_api_token"
+      }
+    }
+  }
+}
+```
+
+The `.universal/configs/*.json.example` files are strict JSON; copy the appropriate file into your harness config location and adjust paths/credentials. OpenCode uses a harness-specific `mcp` shape; the other examples use `mcpServers`.
+
+The older `.universal/setup/install.sh` and `.universal/setup/install.ps1` scripts are manual/legacy helpers. Prefer `.universal/scripts/quick-install.sh` for automated universal setup.
+
+The raw MCP server exposes these tool names:
+
+| Tool | Purpose |
+|---|---|
+| `process_image` | Analyze one electronics/PCB image. |
+| `process_image_folder` | Analyze a folder of supported images. |
+| `save_inventory` | Save inventory output as JSON or quick CSV export. Use the batch workflow for full BOM/evidence output. |
+
+### 4. Install the universal skill/prompt, if your harness supports them
+
+Universal workflow assets are available at:
+
+```text
+.universal/skills/vision-inventory-workflow/SKILL.md
+.universal/prompts/vision-inventory-agent-bom.md
+```
+
+Copy them into your harness-specific skills/prompts location. The skill instructs the agent to run the deterministic workflow, read `parts_to_lookup.json`, verify datasheets with web search, fill `datasheet_cache.json`, regenerate the CSV with `--skip-vision`, and summarize uncertainties.
+
+The deterministic workflow command is the same as the manual shell workflow:
+
+```bash
+python3 scripts/inventory_folder_to_csv.py ./photos ./output
+python3 scripts/inventory_folder_to_csv.py ./photos ./output --skip-vision
+```
+
+Datasheet enrichment still requires a separate web-search/browser capability in the agent. This package does not bundle one.
+
 ## Recommended workflow
 
 ### 1. Take photos
@@ -94,6 +208,13 @@ In Pi:
 /vision-inventory-agent-bom ./photos ./output
 ```
 
+In other harnesses:
+
+```text
+/vision-inventory-workflow ./photos ./output
+```
+
+
 Useful options:
 
 ```text
@@ -186,7 +307,7 @@ Command summary:
 |---|---|
 | `vision_inventory_process_image` | Analyze one electronics/PCB image. |
 | `vision_inventory_process_folder` | Analyze a folder of supported images. |
-| `vision_inventory_save` | Save inventory output as JSON or CSV. |
+| `vision_inventory_save` | Save inventory output as JSON or quick CSV export. For the full BOM workflow, use `/vision-inventory-bom` or `scripts/inventory_folder_to_csv.py`. |
 
 ## Manual shell workflow
 
@@ -194,6 +315,7 @@ You can run the deterministic workflow without Pi commands:
 
 ```bash
 python3 -m pip install -r requirements.txt
+python3 scripts/inventory_folder_to_csv.py ./photos ./output --validate-setup
 python3 scripts/inventory_folder_to_csv.py ./photos ./output
 ```
 
@@ -203,17 +325,42 @@ Then fill `output/datasheet_cache.json` manually or with an agent, and regenerat
 python3 scripts/inventory_folder_to_csv.py ./photos ./output --skip-vision
 ```
 
+## No-Cloudflare demo and sample output
+
+A fixture-based demo is available at:
+
+```text
+examples/no-cloudflare-demo/
+```
+
+Run it without Cloudflare credentials:
+
+```bash
+python3 scripts/inventory_folder_to_csv.py ./examples/no-cloudflare-demo/photos ./examples/no-cloudflare-demo/output --skip-vision
+```
+
+The demo includes mock raw vision JSON, a small `datasheet_cache.json`, and generated sample outputs:
+
+```text
+examples/no-cloudflare-demo/output/parts_to_lookup.json
+examples/no-cloudflare-demo/output/datasheet_cache.json
+examples/no-cloudflare-demo/output/inventory.csv
+examples/no-cloudflare-demo/output/inventory_evidence.csv
+```
+
+Use these files to understand the expected output shapes before running real image analysis.
+
 ## Python requirements
 
 Python 3.10 or newer is recommended.
 
-Required:
+Required versions are constrained in `requirements.txt` for reproducible installs:
 
 ```text
-mcp
-requests
-pillow
-python-dotenv
+mcp>=1.0,<2.0
+requests>=2.31,<3.0
+pillow>=10.0,<12.0
+python-dotenv>=1.0,<2.0
 ```
 
 Install:
@@ -301,7 +448,7 @@ MCP tools:
 |---|---|
 | `process_image` | Analyze one image and return structured visible inventory data. |
 | `process_image_folder` | Analyze all supported images in a folder. |
-| `save_inventory` | Save inventory output to JSON or CSV. |
+| `save_inventory` | Save inventory output to JSON or quick CSV export. Use `scripts/inventory_folder_to_csv.py` for the full BOM/evidence workflow. |
 
 Run directly for MCP-compatible clients:
 
@@ -319,7 +466,7 @@ Example MCP client configuration:
       "args": ["/path/to/vision_inventory_mcp.py"],
       "env": {
         "CLOUDFLARE_ACCOUNT_ID": "your_cloudflare_account_id",
-        "CLOUDFLARE_AUTH_TOKEN": "your_cloudflare_workers_ai_token"
+        "CLOUDFLARE_AUTH_TOKEN": "your_cloudflare_workers_ai_api_token"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vision-electronic-indexing-pi",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Pi package for agent-assisted electronics/PCB image inventory with Cloudflare Workers AI vision and datasheet enrichment.",
   "license": "MIT",
   "repository": {

package/requirements.txt

@@ -1,6 +1,6 @@
-mcp
-requests
-pillow
-python-dotenv
+mcp>=1.0,<2.0
+requests>=2.31,<3.0
+pillow>=10.0,<12.0
+python-dotenv>=1.0,<2.0
 # Optional: install for iPhone HEIC/HEIF image support
-# pillow-heif
+# pillow-heif>=0.16,<1.0

package/scripts/inventory_folder_to_csv.py

@@ -18,9 +18,9 @@ import csv
 import json
 import re
 import sys
-from collections import defaultdict
+from collections import Counter, defaultdict
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, Optional
+from typing import Any, Dict, List, Optional
 
 PROJECT_ROOT = Path(__file__).resolve().parents[1]
 if str(PROJECT_ROOT) not in sys.path:
@@ -133,13 +133,30 @@ def extract_part_evidence(image_name: str, result: Dict[str, Any]) -> List[Dict[
     return evidence
 
 
+def preflight_credentials() -> None:
+    _account_id, _api_token, credential_error = vision.get_cloudflare_credentials()
+    if credential_error:
+        raise SystemExit(
+            f"{credential_error.get('message', 'Missing Cloudflare credentials.')} "
+            "Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_AUTH_TOKEN/CLOUDFLARE_API_TOKEN, "
+            "or run /vision-inventory-setup in Pi."
+        )
+
+
 def process_images(args: argparse.Namespace, raw_dir: Path) -> List[Dict[str, Any]]:
     image_folder = Path(args.image_folder).expanduser().resolve()
     if not image_folder.is_dir():
         raise SystemExit(f"Image folder does not exist or is not a directory: {image_folder}")
 
+    images = iter_images(image_folder, args.recursive, args.limit)
+    if not images:
+        print(f"No supported image files found in {image_folder}.")
+        return []
+
+    preflight_credentials()
+
     results: List[Dict[str, Any]] = []
-    for image_path in iter_images(image_folder, args.recursive, args.limit):
+    for image_path in images:
         print(f"Processing {image_path}")
         result = vision.process_image_impl(
             image_path=str(image_path),
@@ -161,7 +178,30 @@ def load_raw_results(raw_dir: Path) -> List[Dict[str, Any]]:
     return results
 
 
-def build_parts_to_lookup(results: List[Dict[str, Any]]) -> Dict[str, Any]:
+def classify_error(result: Dict[str, Any]) -> str:
+    message = str(result.get("message") or result.get("error") or "Unknown error")
+    lowered = message.lower()
+    if "credential" in lowered or "cloudflare_account_id" in lowered or "api token" in lowered:
+        return "credential errors"
+    if "cloudflare" in lowered or "workers ai" in lowered:
+        return "cloudflare api errors"
+    if "prepare image" in lowered or "unsupported image" in lowered or "image file" in lowered:
+        return "image preprocessing/input errors"
+    if result.get("parse_error"):
+        return "model json parse errors"
+    return "other errors"
+
+
+def result_error_summary(results: List[Dict[str, Any]]) -> Counter[str]:
+    summary: Counter[str] = Counter()
+    for entry in results:
+        result = entry.get("result", {})
+        if isinstance(result, dict) and (result.get("error") or result.get("parse_error")):
+            summary[classify_error(result)] += 1
+    return summary
+
+
+def build_parts_to_lookup(results: List[Dict[str, Any]], output_dir: Path) -> Dict[str, Any]:
     grouped: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
     all_evidence: List[Dict[str, Any]] = []
 
@@ -196,16 +236,27 @@ def build_parts_to_lookup(results: List[Dict[str, Any]]) -> Dict[str, Any]:
             }
         })
 
+    warnings: List[str] = []
+    if not parts:
+        warnings.append(
+            "No candidate IC parts were extracted. Inspect raw JSON files for unreadable markings, "
+            "image quality issues, or model/API errors."
+        )
+
     return {
+        "output_dir": str(output_dir),
+        "datasheet_cache_path": str(output_dir / "datasheet_cache.json"),
+        "datasheet_cache_template_path": str(output_dir / "datasheet_cache.template.json"),
         "instructions": [
             "Use web search to find each part datasheet, preferably from the manufacturer.",
-            "Fill output/datasheet_cache.json using the template shape shown in datasheet_cache.template.json.",
+            "Fill datasheet_cache.json in this same output directory, using datasheet_cache.template.json as the shape.",
             "Keep descriptions short, e.g. '74ls (4 bit) adder low power schottky ttl 5v DIP'.",
             "If exact candidate search fails but official results strongly indicate a likely OCR correction, keep the original candidate as this cache key and set normalized_part to the official datasheet part number.",
             "Example: if SN74AS283N appears to be an OCR error for official SN74LS283N, use key SN74AS283N with normalized_part SN74LS283N and explain the correction in notes.",
             "Only mark verified=true for a correction when the official datasheet and visual/package context make the correction highly likely; otherwise set verified=false and explain in notes.",
             "If the visual marking is uncertain, set verified=false and explain in notes."
         ],
+        "warnings": warnings,
         "parts": parts,
         "all_evidence": all_evidence,
     }
@@ -228,13 +279,20 @@ def lookup_enrichment(part: str, cache: Dict[str, Any]) -> Dict[str, Any]:
     return {}
 
 
+def positive_int(value: Any) -> Optional[int]:
+    try:
+        parsed = int(value)
+    except Exception:
+        return None
+    return parsed if parsed > 0 else None
+
+
 def estimate_amount_for_candidate(result: Dict[str, Any], candidate: str, evidence_count: int = 1) -> int:
     """Estimate physical IC quantity for one candidate in one image.
 
-    Some vision results use count_index as a grouped visible count, while others
-    use it as an ordinal. Use the maximum of matching item count, evidence count,
-    and any numeric count_index values so grouped detections like count_index=4
-    produce amount=4 without double-counting duplicate observations.
+    Prefer explicit visible_quantity when the model provides it. Older results only
+    have count_index, which may be either an ordinal index or a grouped count, so
+    the fallback remains heuristic and should be reviewed for important BOMs.
     """
     items = result.get("items", [])
     if not isinstance(items, list):
@@ -242,6 +300,7 @@ def estimate_amount_for_candidate(result: Dict[str, Any], candidate: str, eviden
 
     matched = 0
     count_values: List[int] = []
+    visible_quantities: List[int] = []
     for item in items:
         if not isinstance(item, dict):
             continue
@@ -250,10 +309,15 @@ def estimate_amount_for_candidate(result: Dict[str, Any], candidate: str, eviden
         if candidate_from_item(item).upper() != candidate.upper():
             continue
         matched += 1
-        try:
-            count_values.append(max(1, int(item.get("count_index", 1))))
-        except Exception:
-            pass
+        visible_quantity = positive_int(item.get("visible_quantity"))
+        if visible_quantity is not None:
+            visible_quantities.append(visible_quantity)
+        count_index = positive_int(item.get("count_index"))
+        if count_index is not None:
+            count_values.append(count_index)
+
+    if visible_quantities:
+        return max(1, sum(visible_quantities))
 
     return max([1, evidence_count, matched, *count_values])
 
@@ -265,6 +329,11 @@ def image_part_rows(results: List[Dict[str, Any]], cache: Dict[str, Any]) -> Lis
         image_name = str(result.get("image") or Path(entry["image_path"]).name)
         evidence = extract_part_evidence(image_name, result)
         if not evidence:
+            notes = "No IC marking extracted"
+            if isinstance(result, dict) and result.get("error"):
+                notes = f"Vision processing error: {result.get('message', 'unknown error')}"
+            elif isinstance(result, dict) and result.get("warnings"):
+                notes = "; ".join(str(w) for w in result.get("warnings", []) if str(w).strip()) or notes
             rows.append({
                 "image": image_name,
                 "candidate_part": "",
@@ -279,7 +348,7 @@ def image_part_rows(results: List[Dict[str, Any]], cache: Dict[str, Any]) -> Lis
                 "observed_markings": "",
                 "observations": "",
                 "raw_json": entry["raw_json"],
-                "notes": "No IC marking extracted",
+                "notes": notes,
             })
             continue
 
@@ -425,6 +494,63 @@ def write_final_csv(results: List[Dict[str, Any]], cache: Dict[str, Any], output
     write_csv(output_csv.with_name(f"{output_csv.stem}_evidence{output_csv.suffix}"), evidence_fieldnames, evidence_rows)
 
 
+def validate_setup(args: argparse.Namespace, output_dir: Path) -> None:
+    image_folder = Path(args.image_folder).expanduser().resolve()
+    print("Setup validation:")
+    print(f"- Python executable: {sys.executable}")
+    print("- Required imports: ok")
+
+    if image_folder.is_dir():
+        images = iter_images(image_folder, args.recursive, args.limit)
+        print(f"- Image folder: ok ({image_folder})")
+        print(f"- Supported images found: {len(images)}")
+        heic_images = [p for p in images if p.suffix.lower() in {".heic", ".heif"}]
+        if heic_images:
+            try:
+                import pillow_heif  # noqa: F401
+                print("- HEIC/HEIF support: ok")
+            except Exception:
+                print("- HEIC/HEIF support: missing pillow-heif; install it to process HEIC/HEIF images")
+    else:
+        print(f"- Image folder: missing or not a directory ({image_folder})")
+
+    try:
+        output_dir.mkdir(parents=True, exist_ok=True)
+        probe = output_dir / ".vision_inventory_write_test"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink(missing_ok=True)
+        print(f"- Output directory writable: ok ({output_dir})")
+    except Exception as exc:
+        print(f"- Output directory writable: failed ({exc})")
+
+    if args.skip_vision:
+        raw_dir = output_dir / "raw"
+        raw_count = len(list(raw_dir.glob("*.json"))) if raw_dir.exists() else 0
+        print(f"- Raw JSON files for --skip-vision: {raw_count}")
+    else:
+        _account_id, _api_token, credential_error = vision.get_cloudflare_credentials()
+        if credential_error:
+            print(f"- Cloudflare credentials: missing ({credential_error.get('message')})")
+        else:
+            print("- Cloudflare credentials: present")
+
+
+def print_workflow_summary(results: List[Dict[str, Any]], parts_to_lookup: Dict[str, Any]) -> None:
+    error_summary = result_error_summary(results)
+    evidence_count = len(parts_to_lookup.get("all_evidence", []))
+    part_count = len(parts_to_lookup.get("parts", []))
+    print("Workflow summary:")
+    print(f"- Processed/raw result files: {len(results)}")
+    print(f"- IC marking evidence rows: {evidence_count}")
+    print(f"- Candidate parts extracted: {part_count}")
+    if error_summary:
+        print("- Processing errors:")
+        for label, count in sorted(error_summary.items()):
+            print(f"  - {label}: {count}")
+    if not part_count:
+        print("No candidate IC parts were extracted. Inspect output/raw/*.json for unreadable markings, image quality issues, or API errors.")
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description="Process electronics images and prepare datasheet-enriched CSV workflow.")
     parser.add_argument("image_folder", help="Folder containing electronics/PCB images")
@@ -433,6 +559,7 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--recursive", action="store_true", help="Scan image_folder recursively")
     parser.add_argument("--limit", type=int, default=None, help="Maximum number of images to process")
     parser.add_argument("--skip-vision", action="store_true", help="Reuse existing output_dir/raw/*.json instead of calling vision AI")
+    parser.add_argument("--validate-setup", action="store_true", help="Check dependencies, paths, credentials, and image discovery without processing images")
     parser.add_argument("--max-side", type=int, default=vision.DEFAULT_MAX_SIDE, help="Maximum resized image side; use 0 for full resolution (default)")
     parser.add_argument("--jpeg-quality", type=int, default=vision.DEFAULT_JPEG_QUALITY, help="JPEG quality for model input")
     return parser.parse_args()
@@ -441,6 +568,11 @@ def parse_args() -> argparse.Namespace:
 def main() -> None:
     args = parse_args()
     output_dir = Path(args.output_dir).expanduser().resolve()
+
+    if args.validate_setup:
+        validate_setup(args, output_dir)
+        return
+
     raw_dir = output_dir / "raw"
     output_dir.mkdir(parents=True, exist_ok=True)
     raw_dir.mkdir(parents=True, exist_ok=True)
@@ -452,7 +584,7 @@ def main() -> None:
     else:
         results = process_images(args, raw_dir)
 
-    parts_to_lookup = build_parts_to_lookup(results)
+    parts_to_lookup = build_parts_to_lookup(results, output_dir)
     parts_path = output_dir / "parts_to_lookup.json"
     template_path = output_dir / "datasheet_cache.template.json"
     cache_path = output_dir / "datasheet_cache.json"
@@ -470,8 +602,13 @@ def main() -> None:
     print(f"Datasheet cache template: {template_path}")
     print(f"Datasheet cache used: {cache_path if cache_path.exists() else 'not found yet'}")
     print(f"CSV written: {csv_path}")
+    print_workflow_summary(results, parts_to_lookup)
     if not cache_path.exists():
-        print("Next step: copy datasheet_cache.template.json to datasheet_cache.json, enrich it via web search, then rerun with --skip-vision.")
+        print("Next step: copy datasheet_cache.template.json to datasheet_cache.json in the output directory, enrich it via web search, then rerun with --skip-vision.")
+
+    errors = result_error_summary(results)
+    if results and sum(errors.values()) == len(results):
+        raise SystemExit("All processed images returned errors; see the summary above and inspect raw JSON files.")
 
 
 if __name__ == "__main__":

package/vision_inventory_mcp.py

@@ -105,6 +105,7 @@ Return only valid JSON using this schema:
     {{
       "item_type": "IC | connector | passive | module | switch | sensor | display | mechanical | unknown",
       "count_index": 1,
+      "visible_quantity": 1,
       "package_marking": "exact visible marking, unclear, unreadable, or [?]-marked partial text",
       "marking_confidence": "high | medium | low | unreadable",
       "likely_part": "visible part marking only, or unknown",
@@ -123,6 +124,7 @@ Rules:
 - Do not use web lookup.
 - If a marking is not readable, write "unreadable".
 - If a component is visible but not identifiable, item_type should be "unknown".
+- count_index is an ordinal item number; visible_quantity is the estimated number of matching visible physical components.
 - needs_review must be true when marking_confidence is "low" or "unreadable".
 """.strip()
 
@@ -362,6 +364,7 @@ def normalize_item(item: Any, fallback_index: int) -> Dict[str, Any]:
     default_item: Dict[str, Any] = {
         "item_type": "unknown",
         "count_index": fallback_index,
+        "visible_quantity": 1,
         "package_marking": "unknown",
         "marking_confidence": "unreadable",
         "likely_part": "unknown",
@@ -381,6 +384,11 @@ def normalize_item(item: Any, fallback_index: int) -> Dict[str, Any]:
     except Exception:
         normalized["count_index"] = fallback_index
 
+    try:
+        normalized["visible_quantity"] = max(1, int(normalized.get("visible_quantity", 1)))
+    except Exception:
+        normalized["visible_quantity"] = 1
+
     confidence = str(normalized.get("marking_confidence", "unreadable")).strip().lower()
     if confidence not in {"high", "medium", "low", "unreadable"}:
         confidence = "low"
@@ -459,17 +467,6 @@ def normalize_inventory_result(result: Dict[str, Any], image_name: str) -> Dict[
     return normalized
 
 
-def visible_ic_items(result: Dict[str, Any]) -> List[Dict[str, Any]]:
-    items = result.get("items", [])
-    if not isinstance(items, list):
-        return []
-    return [
-        item for item in items
-        if isinstance(item, dict) and str(item.get("item_type", "")).strip().lower() == "ic"
-    ]
-
-
-
 def process_image_impl(
     image_path: str,
     max_side: int = DEFAULT_MAX_SIDE,
@@ -512,10 +509,15 @@ def process_image_impl(
 
     parsed, parse_error = extract_json_object(response_text)
     if parse_error or parsed is None:
+        message = parse_error or "Model returned invalid JSON."
         return {
             "image": image_name,
             "items": [],
-            "warnings": [parse_error or "Model returned invalid JSON."],
+            "warnings": [message],
+            "parse_error": True,
+            "parse_error_message": message,
+            "raw_response_preview": response_text[:2000],
+            "raw_response_length": len(response_text),
             "raw_response": response_text,
         }
 
@@ -699,7 +701,10 @@ def flatten_inventory_for_csv(inventory: Dict[str, Any], enrichment_cache: Optio
             # Keep the main part number as the observation, not the full package/date/lot marking.
             row["observed_markings"].add(normalized)
             try:
-                row["amount"] = max(int(row["amount"]), int(item.get("count_index", 1)))
+                if "visible_quantity" in item:
+                    row["amount"] = int(row["amount"]) + max(1, int(item.get("visible_quantity", 1)))
+                else:
+                    row["amount"] = max(int(row["amount"]), int(item.get("count_index", 1)))
             except Exception:
                 row["amount"] = max(int(row["amount"]), 1)
 
@@ -736,9 +741,12 @@ def save_inventory(
     format: str = "json",
 ) -> Dict[str, Any]:
     """
-    Save inventory results to disk as JSON or CSV.
+    Save inventory results to disk as JSON or quick CSV export.
 
     The input inventory can be the result of process_image or process_image_folder.
+    CSV output from this tool is a quick export; use scripts/inventory_folder_to_csv.py
+    or /vision-inventory-bom for the full BOM workflow with raw evidence files,
+    parts_to_lookup.json, datasheet_cache.json, and inventory_evidence.csv.
     """
     if not isinstance(inventory, dict):
         return error_response("inventory must be an object/dict.")
@@ -795,12 +803,19 @@ def save_inventory(
 
             row_count = len(rows)
 
-        return {
+        response = {
             "saved": True,
             "output_path": str(output),
             "format": fmt,
             "row_count": row_count,
         }
+        if fmt == "csv":
+            response["note"] = (
+                "This is a quick CSV export. Use scripts/inventory_folder_to_csv.py "
+                "or /vision-inventory-bom for the full BOM workflow with raw evidence, "
+                "parts_to_lookup.json, datasheet_cache.json, and inventory_evidence.csv."
+            )
+        return response
 
     except Exception as exc:
         return error_response(f"Failed to save inventory: {exc}", output_path=str(output), format=fmt)