From 590bad337447592b74e5a64866ed2fc020b50c24 Mon Sep 17 00:00:00 2001
From: mikael-lovqvists-claude-agent <mikaels.claude.agent@efforting.tech>
Date: Sat, 21 Mar 2026 00:31:03 +0000
Subject: [PATCH] Add README with features, install, and run instructions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..374337f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# Electronics Inventory
+
+A self-hosted web app for managing an electronics component collection. Track components, their
+field values, physical storage locations, and visual panel/grid layouts.
+
+## Features
+
+### Components
+Define reusable component types (e.g. Resistor, Capacitor, IC) with custom fields per component.
+Components show up in inventory entries and can be navigated to directly from storage locations.
+
+### Fields
+Create custom field definitions (e.g. `resistance`, `capacitance`, `package`) that can be attached
+to any component. Field values are entered per-component instance.
+
+### Inventory
+Log where things are stored. Each inventory entry links a component to a storage location.
+Supported location types:
+
+- **Grid cell** — a specific row/column in a named grid (e.g. drawer divider box)
+- *(plain entries without a grid reference work too)*
+
+### Grids
+Model physical storage grids (drawer organizers, parts boxes, etc.).
+
+1. Upload a photo of the grid
+2. Set up corner points to map the image to a logical grid
+3. Define row/column counts
+4. Click any cell to see what's stored there
+
+### Templates (Name Formatters)
+Write JavaScript formatter functions that generate smart display names for components based on their
+field values. Example:
+
+```js
+(c) => {
+    const F = c.fields;
+    if (F.resistance && F.imperial_package) {
+        return `${F.resistance}Ω ${F.imperial_package}`;
+    }
+}
+```
+
+Fields are accessed by name (e.g. `c.fields.resistance`). If the formatter returns a non-empty
+string it's used as the display name; otherwise the component's base name is used as fallback.
+Multiple formatters are tried in order.
+
+The template editor includes a test data box so you can preview the output without needing real
+inventory data.
+
+## Requirements
+
+- Node.js >= 25
+- npm
+
+## Install
+
+Clone directly from the git repository — there is no npm package yet:
+
+```bash
+git clone https://gitea.efforting.tech/mikael-lovqvists-claude-agent/electronics-inventory
+cd electronics-inventory
+npm install
+```
+
+## Run
+
+```bash
+npm start
+```
+
+The server starts on port 3000 by default. Open [http://localhost:3000](http://localhost:3000) in
+your browser.
+
+To use a different port:
+
+```bash
+PORT=8080 npm start
+```
+
+## Data Storage
+
+All data is stored locally in a `data/` directory created automatically on first run:
+
+- `data/db.json` — component, field, inventory, grid, and template records (flat key-value store)
+- `data/uploads/` — source images uploaded for grid setup
+
+No external database is required.
+
+## Project Structure
+
+```
+server.mjs          Express 5 API server + SPA host
+lib/
+  storage.mjs       Server-side KV store wrappers
+  kv-store.mjs      JSON file-backed key-value store
+  ids.mjs           ID generation
+public/
+  app.mjs           Single-page app (vanilla JS ES modules)
+  templates.html    HTML templates (lazy-loaded)
+  style.css         Styles
+  lib/api.mjs       Fetch wrappers for the REST API
+  views/
+    grid-setup.mjs  Canvas-based grid corner editor
+```